cupertino

🍎📚 Cupertino

🕯️ v1.0.0 'First Light' is in the making. A proper 1.0, not a point release. The current version stands steadfast in the meantime — follow the roadmap →.

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 BM25 ranking
• Serves documentation to AI agents like Claude via the Model Context Protocol
• Provides offline access to 302,424+ documentation pages across 307 frameworks

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)
• ~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)