Cupertino

🍎📚 Cupertino

Apple documentation CLI for humans and MCP server for AI agents.

Cupertino is a CLI for human developers and an MCP server for AI agents. Both surfaces use the same local index of Apple documentation, Swift packages, sample code, Human Interface Guidelines, Swift Evolution proposals, and Swift.org pages.

Latest: v1.3.0 (2026-05-31): per-source database bundle, read-only databases. The shipped bundle carries 351,505 documents / 240,543 symbols across 420+ frameworks. Release notes · CHANGELOG · Roadmap · live dashboard at https://cupertino.aleahim.com/. Follow updates on X: @cupertinomcp.

If Cupertino is useful to your work with Apple docs or AI agents, consider sponsoring its development. Sponsorship helps keep releases, documentation, and the Apple/Linux tooling around it moving.

What is Cupertino?

Cupertino is a local, structured documentation system for Apple platforms. It:

• Crawls Apple Developer documentation, Swift.org, Swift Evolution proposals, Human Interface Guidelines, Apple Archive legacy guides, and Swift package metadata
• Indexes everything into a fast, searchable SQLite FTS5 database with field-weighted BM25 (BM25F) ranking and AST-extracted symbol columns
• Runs as a terminal CLI for developers who want fast local search, read, doctor, and setup commands
• Serves the same corpus to AI agents like Claude, ChatGPT, Codex, Cursor, and Copilot via the Model Context Protocol
• Provides offline access to 351,505 documentation pages / 240,543 symbols across 420+ frameworks (v1.3.0 bundle)

Why build this:

• No more hallucinations: AI agents get accurate, up-to-date Apple API documentation
• Offline development: work with full documentation without internet access
• Deterministic search: the same query always returns the same results
• Local control: own your documentation, inspect the database, script workflows
• Dual-consumer design: use it directly at the terminal or wire it into an MCP-capable AI client

Installation

Requires macOS 15+ (Sequoia) and ~4.2 GB free disk for the full v1.3.0 bundle (compressed download ~742 MB). Building from source additionally needs Swift 6.3+ and Xcode 26+ (use xcrun swift build, not bare swift).

One-command install (recommended): downloads a signed, notarized universal binary to /usr/local/bin and fetches the databases:

bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)

Homebrew:

brew tap mihaelamj/tap
brew install cupertino
cupertino setup            # download the pre-built databases

Build from source:

git clone https://github.com/mihaelamj/cupertino.git
cd cupertino
make build                 # release binary (or: cd Packages && swift build -c release)
sudo make install          # install to /usr/local/bin
cupertino setup            # download the pre-built databases

The Homebrew path on Apple Silicon installs to /opt/homebrew/bin/cupertino; Intel and manual installs use /usr/local/bin/cupertino. Run which cupertino to confirm your path. See docs/DEPLOYMENT.md for distribution and CI/CD notes.

Quick start

cupertino setup                                  # download pre-built databases (~30s)
cupertino search "NavigationStack" --limit 5     # search from the terminal
cupertino read "apple-docs://swiftui/navigationstack" --source apple-docs
cupertino doctor                                 # check local database health
cupertino serve                                  # start the MCP server (also the default command)

Prefer to build the index yourself instead of downloading it? cupertino save --remote streams the corpus from GitHub and rebuilds locally, and cupertino fetch --source <name> crawls a single source from the original site. See docs/commands/ for every command, flag, and the slower self-hosted paths.

Two surfaces, one index

A terminal search prints a human-friendly result with scores and follow-up commands:

$ cupertino search "NavigationStack" --format text --limit 2
Question: NavigationStack
Searched: apple-docs, samples, swift-evolution, swift-org, swift-book, packages

======================================================================
[1] NavigationStack  •  source: apple-docs  •  score: 0.0324
    apple-docs://swiftui/navigationstack
----------------------------------------------------------------------
A view that displays a root view and enables navigation to additional views.

▶ Read full: cupertino read "apple-docs://swiftui/navigationstack" --source apple-docs

💡 Narrow with --source <name>: apple-docs, samples, hig, apple-archive, swift-evolution, swift-org, swift-book, packages
💡 Filter by platform: --platform iOS --min-version 16.0  (or macOS / tvOS / watchOS / visionOS)

The same query over MCP returns a structured tool result an AI client can read, cite, and follow with read_document:

{
  "name": "search",
  "arguments": { "query": "NavigationStack", "source": "apple-docs", "limit": 2 }
}

Demo: Watch on YouTube.

Use with AI agents

Claude Code registers Cupertino globally with one command:

claude mcp add cupertino --scope user -- $(which cupertino)

Claude Desktop, OpenAI Codex, Cursor, VS Code (Copilot), GitHub Copilot for Xcode, Zed, Windsurf, and opencode are all covered with copy-paste config in docs/mcp-clients.md. Cupertino can also run as a stateless CLI Agent Skill with no server: see docs/agent-skill.md.

What you get

Core features

Multi-source documentation

• Apple Developer Documentation (~351,505 indexed pages): JavaScript-aware rendering via WKWebView, HTML-to-Markdown conversion, smart change detection
• Swift Evolution (~429 proposals) and Swift.org (~501 pages): GitHub- and site-based fetching in Markdown
• Swift package metadata: packages.db ships 185 packages with full source, stars, licenses, deployment-target platforms, and authored swift-tools-version
• Apple Sample Code (619 projects, 18,000+ indexed Swift files): fetched from Apple's CDN or the GitHub mirror, full-text searchable
• Apple Archive legacy guides (~75 pages): pre-2016 conceptual docs (Core Animation, Quartz 2D, Core Text); excluded from search by default (--include-archive)
• Human Interface Guidelines: Apple's design guidelines across iOS, macOS, watchOS, visionOS, and tvOS

Full-text search engine

• BM25F ranking: SQLite FTS5 with field-weighted BM25 (Robertson/Zaragoza/Taylor 2004) over a 9-column index (uri, source, framework, language, title, content, summary, symbols, symbol_components). Title 10×, AST-extracted symbols 5×, summary 3×, framework 2×, CamelCase-split components 1.5×.
• AST-aware: a Swift extractor pulls identifiers from every embedded code block and the page declaration into a symbols column, so a query like Task ranks the Swift Task struct above prose mentions of "task".
• smart-query: cupertino search (and the Search.SmartQuery API) fans the question across every source in parallel and fuses per-source rankings via reciprocal rank fusion (RRF, k=60, Cormack/Clarke/Büttcher 2009); one dead source never takes the whole query down.
• Porter stemming, framework + platform-availability filtering, snippet generation, sub-100 ms queries.
• Databases must live on a local filesystem (SQLite is unreliable on NFS/SMB).

Model Context Protocol server

• Resources: direct page access via apple-docs://{framework}/{page}, swift-evolution://{proposal-id}, hig://{category}/{page}
• search: unified full-text search across every indexed source. Parameters: query (required), source, framework, language, include_archive, limit, and the min_ios/min_macos/min_tvos/min_watchos/min_visionos/min_swift platform filters (AND-combined; malformed values are rejected at the boundary with a clear error frame). Replaces the pre-#239 per-source tools.
• list_frameworks, read_document (format: json for agents, markdown for humans)
• Sample-code tools: list_samples, read_sample, read_sample_file
• AST-powered symbol tools (#81): search_symbols, search_property_wrappers, search_concurrency, search_conformances, search_generics, get_inheritance

See docs/tools/ for per-tool documentation.

Intelligent crawling

Resumable from saved state, change-detection to skip unchanged pages, a respectful 0.05 s default delay (configurable), automatic URL-queue deduplication, and priority queues so important content is fetched first.

How it works

Cupertino uses an ExtremePackaging architecture: 49 strict-producer SPM targets across 63 source packages. See docs/ARCHITECTURE.md for the full breakdown and docs/package-import-contract.md for the strict per-target import rules.

Foundation tier:   SharedConstants, LoggingModels, MCPCore, MCPSharedTools, Resources
Infrastructure:    ASTIndexer, Diagnostics, Logging (concrete, composition-root only)
Producers:         Crawler, Core, Search, SampleIndex, Services,
                   AppleConstraintsKit, Availability, Cleanup, and more
Operation packs:   Distribution (setup), Diagnostics (doctor),
                   Indexer (save), Ingest (fetch)
MCP layer:         MCPSupport, MCPClient, SearchToolProvider
Front doors:       CLI (cupertino), TUI (cupertino-tui)

Data flows through three distinct phases:

1. Fetch   cupertino fetch --source apple-docs
           WKWebView → Apple JSON API → JSON files on disk (~/.cupertino/docs/)
2. Save    cupertino save --all
           JSON → parse + AST extract → per-source SQLite FTS5 indexes
           (~/.cupertino/apple-documentation.db, hig.db, …)
3. Serve   cupertino serve
           MCP server (stdio) ← JSON-RPC ← AI client
           DocsResourceProvider + CupertinoSearchToolProvider

Key design principles: Swift 6.3 with 100% strict concurrency checking, value semantics and Sendable by default, actor isolation (@MainActor for WKWebView), explicit dependency injection with no singletons, and a hard separation of Crawling → Indexing → Serving.

Published packages

Cupertino factors three reusable, independently-versioned Swift packages out of the monorepo. Each is its own public repository, depended on by tag (from: "0.1.0"), Foundation-only, and built so an external consumer can adopt it without pulling in cupertino's en

…