🍎📚 Cupertino

🕯️ v1.2.1 released on 2026-05-23. Maintenance release: architectural cleanup + DI / pluggability lift. Zero schema delta vs v1.2.0; the v1.2.0 bundle works as-is with the v1.2.1 binary (cupertino setup still downloads cupertino-databases-v1.2.0.zip). Headlines: Source Independence Day reached (adding a new content source is now a composition-root-only PR); strict-DI + standalone-portability epic closed (every Search-side producer is foundation-only, mechanically verified by scripts/check-target-portability.sh); Distribution.DatabaseHealthCheck strategy seam covers Doctor's 3 sibling per-DB sections. Live dashboard at https://cupertino.aleahim.com/. See the v1.2.1 release notes.

v1.2.0 "ironclad" (2026-05-20) was the most recent bundle release. Search-quality release: rank-1 accuracy on canonical-lookup queries jumped from 52% to 92% on the Phase 1 corpus, zero regressions across 110 paired queries, 30 / 30 modern Swift wins on the deprecation-pair corpus. databaseVersion is 1.2.0: cupertino setup downloads cupertino-databases-v1.2.0.zip (690 MiB compressed, sha256 097d6633…f47747) carrying 352,712 indexed documents across 420 frameworks, search.db user_version 18, packages.db 5, samples.db 4, 0 poison rows across the 13-category audit. Full write-up at docs/release-writeup-v1.2.0.md. See the v1.2.0 release notes.

Apple Documentation Crawler & MCP Server

A Swift-based tool to crawl, index, and serve Apple's developer documentation to AI agents via the Model Context Protocol (MCP).

What is Cupertino?

Cupertino is a local, structured, AI-ready 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
• Serves documentation to AI agents like Claude via the Model Context Protocol
• Provides offline access to 352,712+ documentation pages across 420 frameworks (v1.2.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: Same query always returns same results
• Local control: Own your documentation, inspect the database, script workflows
• AI-first design: Built specifically for AI agent integration via MCP

Quick Start

Note: When building from source, commands must be run from the Packages directory. The one-command install works from anywhere.

Requirements

• macOS 15+ (Sequoia)
• ~4.1 GB disk space for the full v1.2.0 bundle (search.db ~2.87 GB, packages.db ~1.06 GB, samples.db ~187 MB; compressed download is ~690 MiB)

Building from source additionally requires Swift 6.3+ and Xcode 26+ (use xcrun swift build, not bare swift)

Installation

One-command install (recommended):

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

This downloads a pre-built, signed, and notarized universal binary, installs it to /usr/local/bin, and downloads the documentation databases.

Or with Homebrew:

brew tap mihaelamj/tap
brew install cupertino
cupertino setup

Or build from source:

git clone https://github.com/mihaelamj/cupertino.git
cd cupertino

# Using Makefile (recommended)
make build                       # Build release binary
sudo make install                # Install to /usr/local/bin

# Or using Swift Package Manager directly
cd Packages
swift build -c release
sudo ln -sf "$(pwd)/.build/release/cupertino" /usr/local/bin/cupertino

Demo Video: Watch on YouTube

Quick Reference

# Quick Setup (Recommended) - download pre-built databases (~30 seconds)
cupertino setup                      # Download databases from GitHub
cupertino serve                      # Start MCP server

# Alternative: Build from GitHub (~45 minutes)
cupertino save --remote              # Stream and build locally

# Or fetch documentation yourself
cupertino fetch --type docs          # Apple Developer Documentation
cupertino fetch --type swift         # Swift.org documentation
cupertino fetch --type evolution     # Swift Evolution proposals
cupertino fetch --type packages      # Swift package metadata + GitHub archives
cupertino fetch --type code          # Sample code from Apple (requires auth)
cupertino fetch --type samples       # Sample code from GitHub (recommended)
cupertino fetch --type archive       # Apple Archive programming guides
cupertino fetch --type hig           # Human Interface Guidelines
cupertino fetch --type availability  # Platform availability data
cupertino fetch --type all           # All types in parallel

# Build indexes
cupertino save                       # Build documentation search index (from local files)
cupertino save --remote              # Build from GitHub (no local files needed)
cupertino save --samples                      # Index sample code for search

# Start server
cupertino                            # Start MCP server (default command)
cupertino serve                      # Start MCP server (explicit)

Instant Setup (Recommended)

# Download pre-built databases from GitHub (~30 seconds)
cupertino setup

# Start MCP server
cupertino serve

Note: cupertino setup --force is no longer valid (the flag was removed in v1.2.0). cupertino setup overwrites by default; pass --keep-existing to skip the download when databases are already installed.

Alternative: Build from GitHub

# Stream and build locally (~45 minutes)
# Use this if you want to build the database yourself
cupertino save --remote

# Start MCP server
cupertino serve

Manual Setup (Advanced)

# Download Apple documentation (~12+ days for ~404,000+ raw pages, indexed down to ~277,640)
# Takes time due to 0.05s default delay between requests
cupertino fetch --type docs --max-pages 15000

# Download Swift Evolution proposals (~2-5 minutes)
cupertino fetch --type evolution

# Download sample code from GitHub (~4 minutes, 619 projects)
cupertino fetch --type samples

# Build search index (~2-5 minutes)
cupertino save

Use with Claude Desktop

1. Configure Claude Desktop - Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cupertino": {
      "command": "/usr/local/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Note: Use /opt/homebrew/bin/cupertino for Homebrew on Apple Silicon, /usr/local/bin/cupertino for Intel or manual install. Run which cupertino to find your path.

2. Restart Claude Desktop

3. Ask Claude about Apple APIs:

   • "Search for SwiftUI documentation"
   • "What does Swift Evolution proposal SE-0001 propose?"
   • "List available frameworks"

Use with Claude Code

If you're using Claude Code, you can add Cupertino as an MCP server with a single command:

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

This registers Cupertino globally for all your projects. Claude Code will automatically have access to Apple documentation search.

Use with OpenAI Codex

If you're using OpenAI Codex, add Cupertino with:

codex mcp add cupertino -- $(which cupertino) serve --no-reap

Or add directly to ~/.codex/config.toml:

[mcp_servers.cupertino]
command = "/opt/homebrew/bin/cupertino"  # Homebrew on Apple Silicon
# command = "/usr/local/bin/cupertino"   # Intel Mac or manual install
args = ["serve", "--no-reap"]

Why --no-reap? Codex spawns a fresh cupertino serve per tool call. Without --no-reap, each new instance kills its predecessor as a stale sibling, and the in-flight transport closes (Transport closed error on every tool call — see #280). Claude Desktop / Cursor users keep the default (reap on) so MCP-host config reloads don't leak orphan servers.

Equivalent env-var form: CUPERTINO_DISABLE_REAPER=1 in [mcp_servers.cupertino.env].

Tip: Run which cupertino to find your installation path.

Use with Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global access):

{
  "mcpServers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Use with VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "cupertino": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

Use with GitHub Copilot for Xcode

GitHub Copilot for Xcode supports MCP servers via Agent Mode. In the app, go to the Tools tab → MCP sub-tab → MCP Configuration → Edit Config, or edit ~/.config/github-copilot/xcode/mcp.json direct