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 catalog of Apple documentation, Swift packages, sample code, Human Interface Guidelines, Swift Evolution proposals, and Swift.org pages.

Latest: v1.4.1 (2026-06-24): refreshed database bundle. A full re-crawl + clean rebuild grew the Apple documentation slice to 363,562 documents / 308,118 symbols across 417 frameworks, now including post-WWDC26 iOS 27 content, alongside the HIG, archive, Swift Evolution, Swift.org, Swift Book, package, and sample-code DBs (8 per-source databases, read-only rollback mode). 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 fast, searchable SQLite FTS5 databases 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 363,562 Apple documentation pages / 308,118 Apple-doc symbols across 417 frameworks, plus the HIG, archive, Swift Evolution, Swift.org, Swift Book, package, and sample-code slices (v1.4.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.4.0 bundle (compressed download ~876 MB). Building from source additionally needs Swift 6.3+ and Xcode 26+ (use xcrun swift build, not bare swift).

Homebrew (recommended): installs the signed, notarized universal binary and lets you upgrade or uninstall it with brew:

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

One-command install (alternative): downloads the binary to /usr/local/bin and fetches the databases in one step:

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

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 catalog

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 (~363,562 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 (~368 pages in v1.4.0): pre-2016 conceptual docs (Core Animation, Quartz 2D, Core Text); included in default fan-out with a lower rank weight, or searchable alone with --source apple-archive
• Human Interface Guidelines: Apple's design guidelines across iOS, macOS, watchOS, visionOS, and tvOS

Full-text search engines

• 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, list_documents, list_children, read_document (format: json for agents, markdown for humans)
• Sample-code tools: list_samples, read_sample, read_sample_file; pass format=json for typed project/file payloads
• AST-powered symbol tools (#81): search_symbols, search_property_wrappers, search_concurrency, search_conformances, search_generics, get_inheritance; pass format=json for typed symbol rows and title-bearing inheritance trees
• Desktop boundary: desktop UI code consumes these backend/tool contracts. It must not open SQLite databases directly or duplicate Cupertino's read engine.

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: 48 in-tree strict-producer SPM targets with explicit import contracts, plus the external CupertinoDataEngine package. See docs/ARCHITECTURE.md for the full breakdown and docs/package-import-contract.md for the strict per-target import rules.

flowchart TB
  Foundation["Foundation tier<br/>SharedConstants · LoggingModels · MCPCore · MCPSharedTools · Resources"]
  Infrastructure["Infrastructure<br/>ASTIndexer · Diagnostics · Logging"]
  Producers["Strict producers<br/>Crawler · Core · Search · SampleIndex · Services<br/>AppleConstraintsKit · Availability · Cleanup · more"]
  Operations["Operation packs<br/>Distribution setup · Diagnostics doctor · Indexer save · Ingest fetch"]
  MCP["MCP layer<br/>MCPSupport · MCPClient · SearchToolProvider"]
  FrontDoors["Front doors<br/>CLI cupertino · TUI cupertino-tui"]
  External["External packages<br/>CupertinoDataKit · CupertinoDataEngine<br/>SwiftMCPCore · SwiftMCPClient"]

  Foundation --

…