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)
• ~2-3 GB disk space for full documentation

Building from source additionally requires Swift 6.2+ and Xcode 16.0+

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
cupertino fetch --type package-docs  # Swift package READMEs
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 index                      # 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

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 301,000+ pages)
# 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, 606 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

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"]

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 Zed

Add to your Zed settings.json:

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

Use with Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Use with opencode

Add to opencode.jsonc:

{
  "mcp": {
    "cupertino": {
      "type": "local",
      "command": ["/opt/homebrew/bin/cupertino", "serve"]
    }
  }
}

Note: All examples use /opt/homebrew/bin/cupertino (Homebrew on Apple Silicon). Use /usr/local/bin/cupertino for Intel Macs or manual installs. Run which cupertino to find your path.

Use as an Agent Skill (No Server Required)

Cupertino can also be used as a stateless CLI skill without running an MCP server. This is useful for agents that support the Agent Skills specification.

Prerequisites:

Install cupertino and download the databases first:

# Install via Homebrew or from source (see Installation above)
cupertino setup

Option A: Install with OpenSkills (Recommended)

OpenSkills is a universal skills loader that works with Claude Code, Cursor, Windsurf, Aider, and other AI coding agents.

# Install the cupertino skill from GitHub
npx openskills install mihaelamj/cupertino

# Sync to update AGENTS.md
npx openskills sync

For global installation (available in all projects):

npx openskills install mihaelamj/cupertino --global

For multi-agent setups (installs to .agent/skills/ instead of .claude/skills/):

npx openskills install mihaelamj/cupertino --universal

Option B: Install as a Claude Code Plugin

Inside a Claude Code session, add the cupertino marketplace:

/plugin marketplace add mihaelamj/cupertino

Then enable the plugin from the marketplace.

Option C: Manual Installation

Copy the skill definition to your project or global skills directory:

# Clone this repo
git clone https://github.com/mihaelamj/cupertino.git

# For a single project
mkdir -p .claude/skills/cupertino
cp cupertino/skills/cupertino/SKILL.md .claude/skills/cupertino/

# Or for global use with Claude Code
mkdir -p ~/.claude/skills/cupertino
cp cupertino/skills/cupertino/SKILL.md ~/.claude/skills/cupertino/

How It Works:

The skill uses the CLI directly with JSON output, no server process needed:

# Search documentation
cupertino search "SwiftUI View" --format json

# Filter by source
cupertino search "NavigationStack" --source apple-docs --format json
cupertino search "button styles" --source samples --format json

# Read a document
cupertino read