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). 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 Sw
Add this skill
npx mdskills install mihaelamj/cupertinoWell-documented MCP server providing offline Apple documentation search with comprehensive setup guides
1# 🍎📚 Cupertino23**Apple Documentation Crawler & MCP Server**45A Swift-based tool to crawl, index, and serve Apple's developer documentation to AI agents via the Model Context Protocol (MCP).67[](https://swift.org)8[](https://www.apple.com/macos)9[](LICENSE)10[](https://www.pulsemcp.com/servers/mihaelamj-cupertino)11[](https://lobehub.com/mcp/mihaelamj-cupertino)12131415## What is Cupertino?1617Cupertino is a local, structured, AI-ready documentation system for Apple platforms. It:1819- **Crawls** Apple Developer documentation, Swift.org, Swift Evolution proposals, Human Interface Guidelines, Apple Archive legacy guides, and Swift package metadata20- **Indexes** everything into a fast, searchable SQLite FTS5 database with BM25 ranking21- **Serves** documentation to AI agents like Claude via the Model Context Protocol22- **Provides** offline access to 302,424+ documentation pages across 307 frameworks2324### Why Build This?2526- **No more hallucinations**: AI agents get accurate, up-to-date Apple API documentation27- **Offline development**: Work with full documentation without internet access28- **Deterministic search**: Same query always returns same results29- **Local control**: Own your documentation, inspect the database, script workflows30- **AI-first design**: Built specifically for AI agent integration via MCP3132## Quick Start3334> **Note:** When building from source, commands must be run from the `Packages` directory. The one-command install works from anywhere.3536### Requirements3738- macOS 15+ (Sequoia)39- ~2-3 GB disk space for full documentation4041*Building from source additionally requires Swift 6.2+ and Xcode 16.0+*4243### Installation4445**One-command install (recommended):**4647```bash48bash <(curl -sSL https://raw.githubusercontent.com/mihaelamj/cupertino/main/install.sh)49```5051This downloads a pre-built, signed, and notarized universal binary, installs it to `/usr/local/bin`, and downloads the documentation databases.5253**Or with Homebrew:**5455```bash56brew tap mihaelamj/tap57brew install cupertino58cupertino setup59```6061**Or build from source:**6263```bash64git clone https://github.com/mihaelamj/cupertino.git65cd cupertino6667# Using Makefile (recommended)68make build # Build release binary69sudo make install # Install to /usr/local/bin7071# Or using Swift Package Manager directly72cd Packages73swift build -c release74sudo ln -sf "$(pwd)/.build/release/cupertino" /usr/local/bin/cupertino75```7677**Demo Video:** [Watch on YouTube](https://youtu.be/B-mRdainTMA)7879### Quick Reference8081```bash82# Quick Setup (Recommended) - download pre-built databases (~30 seconds)83cupertino setup # Download databases from GitHub84cupertino serve # Start MCP server8586# Alternative: Build from GitHub (~45 minutes)87cupertino save --remote # Stream and build locally8889# Or fetch documentation yourself90cupertino fetch --type docs # Apple Developer Documentation91cupertino fetch --type swift # Swift.org documentation92cupertino fetch --type evolution # Swift Evolution proposals93cupertino fetch --type packages # Swift package metadata94cupertino fetch --type package-docs # Swift package READMEs95cupertino fetch --type code # Sample code from Apple (requires auth)96cupertino fetch --type samples # Sample code from GitHub (recommended)97cupertino fetch --type archive # Apple Archive programming guides98cupertino fetch --type hig # Human Interface Guidelines99cupertino fetch --type availability # Platform availability data100cupertino fetch --type all # All types in parallel101102# Build indexes103cupertino save # Build documentation search index (from local files)104cupertino save --remote # Build from GitHub (no local files needed)105cupertino index # Index sample code for search106107# Start server108cupertino # Start MCP server (default command)109cupertino serve # Start MCP server (explicit)110```111112### Instant Setup (Recommended)113114```bash115# Download pre-built databases from GitHub (~30 seconds)116cupertino setup117118# Start MCP server119cupertino serve120```121122### Alternative: Build from GitHub123124```bash125# Stream and build locally (~45 minutes)126# Use this if you want to build the database yourself127cupertino save --remote128129# Start MCP server130cupertino serve131```132133### Manual Setup (Advanced)134135```bash136# Download Apple documentation (~12+ days for 301,000+ pages)137# Takes time due to 0.5s default delay between requests to respect Apple's servers138cupertino fetch --type docs --max-pages 15000139140# Download Swift Evolution proposals (~2-5 minutes)141cupertino fetch --type evolution142143# Download sample code from GitHub (~4 minutes, 606 projects)144cupertino fetch --type samples145146# Build search index (~2-5 minutes)147cupertino save148```149150### Use with Claude Desktop1511521. **Configure Claude Desktop** - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:153154```json155{156 "mcpServers": {157 "cupertino": {158 "command": "/usr/local/bin/cupertino",159 "args": ["serve"]160 }161 }162}163```164165> **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.1661672. **Restart Claude Desktop**1681693. **Ask Claude about Apple APIs:**170 - "Search for SwiftUI documentation"171 - "What does Swift Evolution proposal SE-0001 propose?"172 - "List available frameworks"173174### Use with Claude Code175176If you're using [Claude Code](https://code.claude.com/docs/en/overview), you can add Cupertino as an MCP server with a single command:177178```bash179claude mcp add cupertino --scope user -- $(which cupertino)180```181182This registers Cupertino globally for all your projects. Claude Code will automatically have access to Apple documentation search.183184### Use with OpenAI Codex185186If you're using [OpenAI Codex](https://github.com/openai/codex), add Cupertino with:187188```bash189codex mcp add cupertino -- $(which cupertino) serve190```191192Or add directly to `~/.codex/config.toml`:193194```toml195[mcp_servers.cupertino]196command = "/opt/homebrew/bin/cupertino" # Homebrew on Apple Silicon197# command = "/usr/local/bin/cupertino" # Intel Mac or manual install198args = ["serve"]199```200201> **Tip:** Run `which cupertino` to find your installation path.202203### Use with Cursor204205Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global access):206207```json208{209 "mcpServers": {210 "cupertino": {211 "command": "/opt/homebrew/bin/cupertino",212 "args": ["serve"]213 }214 }215}216```217218### Use with VS Code (GitHub Copilot)219220Add to `.vscode/mcp.json` in your workspace:221222```json223{224 "servers": {225 "cupertino": {226 "type": "stdio",227 "command": "/opt/homebrew/bin/cupertino",228 "args": ["serve"]229 }230 }231}232```233234### Use with Zed235236Add to your Zed `settings.json`:237238```json239{240 "context_servers": {241 "cupertino": {242 "command": "/opt/homebrew/bin/cupertino",243 "args": ["serve"]244 }245 }246}247```248249### Use with Windsurf250251Add to `~/.codeium/windsurf/mcp_config.json`:252253```json254{255 "mcpServers": {256 "cupertino": {257 "command": "/opt/homebrew/bin/cupertino",258 "args": ["serve"]259 }260 }261}262```263264### Use with opencode265266Add to `opencode.jsonc`:267268```json269{270 "mcp": {271 "cupertino": {272 "type": "local",273 "command": ["/opt/homebrew/bin/cupertino", "serve"]274 }275 }276}277```278279> **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.280281### What You Get282283Once configured, Claude Desktop can search your local documentation:284285**Search Results Example:**286```287# Search Results for "SwiftUI"288289Found **20** results:290291## 1. NSHostingView | Apple Developer Documentation292- **Framework:** `swiftui`293- **URI:** `apple-docs://swiftui/documentation_swiftui_nshostingview`294- **Score:** 1.82295296An AppKit view that hosts a SwiftUI view hierarchy.297298## 2. UIHostingController | Apple Developer Documentation299- **Framework:** `swiftui`300- **URI:** `apple-docs://swiftui/documentation_swiftui_uihostingcontroller`301302A UIKit view controller that manages a SwiftUI view hierarchy.303...304```305306**Framework Statistics:**307| Framework | Documents |308|-----------|----------:|309| Kernel | 39,396 |310| Matter | 24,320 |311| Swift | 17,466 |312| AppKit | 12,443 |313| Foundation | 12,423 |314| UIKit | 11,158 |315| Accelerate | 9,114 |316| SwiftUI | 7,062 |317| ... | ... |318| **307 Frameworks** | **302,424** |319320## Core Features321322### 1. Multi-Source Documentation Fetching323324- **Apple Developer Documentation** (301,000+ pages)325 - JavaScript-aware rendering via WKWebView326 - HTML to Markdown conversion327 - Smart change detection328329- **Swift Evolution Proposals** (~400 proposals)330 - GitHub-based fetching331 - Markdown format332 - Fast downloads333334- **Swift.org Documentation**335 - Official Swift language docs336 - Clean HTML structure337338- **Swift Package Metadata**339 - Priority package catalogs340 - README files341342- **Apple Sample Code** (606 projects)343 - Two fetch methods: GitHub (recommended) or Apple website344 - Full-text search across all source files345 - 18,000+ indexed Swift files346347- **Apple Archive Legacy Guides** (~75 pages)348 - Pre-2016 programming guides (Core Animation, Quartz 2D, Core Text, etc.)349 - Deep conceptual knowledge not in modern docs350 - Excluded from search by default (use `--include-archive`)351352- **Human Interface Guidelines**353 - Apple's official design guidelines for all platforms354 - Covers iOS, macOS, watchOS, visionOS, and tvOS355 - Design patterns, components, foundations, and best practices356357### 2. Bundled Resources358359Cupertino includes pre-indexed catalog data bundled directly into the application:360361- **Swift Packages Catalog** (9,699 packages)362 - Manually curated from Swift Package Index + GitHub API363 - Includes package metadata, stars, licenses, descriptions364 - Updated periodically by maintainers365366- **Sample Code Catalog** (606 entries)367 - Apple's official sample code projects368 - Includes titles, descriptions, frameworks, download URLs369 - Bundled because Apple's catalog doesn't change frequently370371- **Priority Packages** (36 curated packages)372 - Apple official packages (31) + essential ecosystem packages (5)373 - High-priority Swift packages for quick access374375These catalogs are indexed during `cupertino save` and enable instant search without requiring multi-hour downloads. You can still fetch package READMEs and sample code separately via `cupertino fetch` if needed.376377### 3. Full-Text Search Engine378379- **Technology**: SQLite FTS5 with BM25 ranking380- **Features**:381 - Porter stemming (e.g., "running" matches "run")382 - Framework filtering383 - Platform availability filtering (iOS/macOS version)384 - Snippet generation385 - Sub-100ms query performance386- **Size**: ~2.4GB index for full documentation (302,000+ documents across 307 frameworks)387- **Storage**: Database must be on local filesystem - SQLite does not work reliably on network drives (NFS/SMB)388389### 4. Model Context Protocol Server390391- **Resources**: Direct access to documentation pages392 - `apple-docs://{framework}/{page}`393 - `swift-evolution://{proposal-id}`394 - `hig://{category}/{page}`395- **Tools**: Search and read capabilities for AI agents396 - **Documentation Tools** (requires `cupertino save`):397 - `search_docs` - Full-text search across all documentation398 - Parameters: `query` (required), `source`, `framework`, `min_ios`, `min_macos`, `include_archive`, `limit` (all optional)399 - `search_hig` - Search Human Interface Guidelines400 - Parameters: `query` (required), `platform` (optional), `category` (optional), `limit` (optional)401 - `list_frameworks` - List available frameworks402 - `read_document` - Read document by URI with format option403 - Parameters: `uri` (required), `format` (optional: `json` or `markdown`, default: `json`)404 - JSON format returns the full structured document data (recommended for AI)405 - Markdown format returns rendered content for human reading406 - **Sample Code Tools** (requires `cupertino index`):407 - `search_samples` - Search sample code projects and files408 - `list_samples` - List all indexed sample projects409 - `read_sample` - Read sample project README and metadata410 - `read_sample_file` - Read specific source file from a sample411412### 5. Intelligent Crawling413414- **Resumable**: Continue interrupted crawls from saved state415- **Change Detection**: Skip unchanged pages on updates416- **Respectful**: 0.5s default delay between requests (configurable)417- **Deduplication**: Automatic URL queue management418- **Priority Queues**: Important content fetched first419420## Commands421422| Command | Description |423|---------|-------------|424| `cupertino` | Start MCP server (default) |425| `cupertino setup` | Download pre-built databases from GitHub |426| `cupertino serve` | Start MCP server |427| `cupertino fetch` | Download documentation |428| `cupertino save` | Build search index |429| `cupertino search` | Search documentation from CLI |430| `cupertino read` | Read full document by URI |431| `cupertino doctor` | Check server health |432| `cupertino index` | Index sample code for search |433| `cupertino cleanup` | Clean up sample code archives |434435See [docs/commands/](docs/commands/) for detailed usage and options.436437## Architecture438439Cupertino uses an **[ExtremePackaging](https://aleahim.com/blog/extreme-packaging/)** architecture with 9 consolidated packages:440441```442Foundation Layer:443 ├─ MCP # Consolidated MCP framework (Protocol + Transport + Server)444 ├─ Logging # os.log infrastructure445 └─ Shared # Configuration & models446447Infrastructure Layer:448 ├─ Core # Crawler & downloaders449 └─ Search # SQLite FTS5 search450451Application Layer:452 ├─ MCPSupport # Resource providers453 ├─ SearchToolProvider # Search tool implementations454 └─ Resources # Embedded resources455456Executables:457 ├─ CLI # Unified cupertino binary458 ├─ TUI # Terminal UI (cupertino-tui)459 └─ MockAIAgent # Testing tool (mock-ai-agent)460```461462### Data Flow463464```4651. Fetch: cupertino fetch --type docs466 ↓467 WKWebView → HTML → Markdown → disk (~/.cupertino/docs/)4684692. Save: cupertino save470 ↓471 Markdown files → SQLite FTS5 index (~/.cupertino/search.db)4724733. Serve: cupertino serve474 ↓475 MCP Server (stdio) ← JSON-RPC ← Claude Desktop476 ↓477 DocsResourceProvider + CupertinoSearchToolProvider478```479480### Key Design Principles481482- **Swift 6.2 Concurrency**: 100% strict concurrency checking with actors and async/await483- **Value Semantics**: Immutable structs by default, Sendable conformance484- **Actor Isolation**: @MainActor for WKWebView, actors for shared state485- **Explicit Dependencies**: No singletons, clear dependency injection486- **Separation of Concerns**: Crawling → Indexing → Serving as distinct phases487488## Development489490### Build System491492```bash493# Show all available commands494make help495496# Common tasks497make build # Build release binaries498sudo make install # Install to /usr/local/bin499sudo make update # Rebuild and reinstall500make test # Run all tests501make clean # Clean build artifacts502503# Development workflow504make test-unit # Fast unit tests only505make test-integration # All tests (includes network calls)506make format # Format code with SwiftFormat507make lint # Lint with SwiftLint508```509510### Testing511512**Test Suite:**513- 698 tests across 73 test suites514- ~35 seconds duration515- Includes unit tests, integration tests, and formatter tests516517**Test Categories:**518- Web Crawl Tests - Real Apple documentation fetching519- Fetch Command Tests - Package/code downloading520- Save Command Tests - Search index building521- MCP Tests - Server health, tool/resource providers522- Core Tests - Search, logging, state management523524### Logging525526Cupertino uses **os.log** for structured logging:527528```bash529# View all logs530log show --predicate 'subsystem == "com.cupertino"' --last 1h531532# View specific category533log show --predicate 'subsystem == "com.cupertino" AND category == "crawler"' --last 1h534535# Stream live logs536log stream --predicate 'subsystem == "com.cupertino"'537```538539**Categories**: crawler, mcp, search, cli, transport, pdf, evolution, samples540541## Performance542543| Operation | Time | Size |544|-----------|------|------|545| Build CLI | 10-15s | 4.3MB |546| Crawl 301,000+ pages | 12+ days | 2-3GB |547| Swift Evolution | 2-5 min | 429 proposals |548| Swift.org docs | 5-10 min | 501 pages |549| Build search index | 2-5 min | ~160MB |550| Search query | <100ms | - |551552### Why Crawling Takes 12+ Days553554The crawler respects Apple's servers with a **0.5 second default delay between each request** (configurable):555- 301,000 pages × 0.5s = 150,500 seconds (~42 hours minimum)556- Plus page rendering, parsing, and saving time557- Crawl must reach depth 21+ to get all documentation558- **Total: ~12+ days for initial full crawl**559560Use `cupertino setup` to download pre-built databases instead (~30 seconds).561562This is a **one-time operation**. Incremental updates use change detection to skip unchanged pages and complete much faster.563564## Example Use Cases565566### 1. Offline Documentation Archive567568```bash569# Download everything for offline access570cupertino fetch --type docs --max-pages 15000571cupertino fetch --type evolution572cupertino save573```574575### 2. Framework-Specific Research576577```bash578# Just SwiftUI documentation579cupertino fetch --type docs \580 --start-url "https://developer.apple.com/documentation/swiftui" \581 --max-pages 500582```583584### 3. AI-Assisted Development585586```bash587# Serve documentation to Claude588cupertino serve589590# Then ask Claude: "How do I use @Observable in SwiftUI?"591```592593### 4. Custom Documentation Workflows594595```bash596# Multiple sources with custom paths597cupertino fetch --type docs --output-dir ~/docs/apple598cupertino fetch --type evolution --output-dir ~/docs/evolution599cupertino save --base-dir ~/docs --search-db ~/docs/search.db600cupertino serve --docs-dir ~/docs/apple --search-db ~/docs/search.db601```602603## Documentation604605- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Build, test, contribute, and release workflow606- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical deep-dives (Concurrency, MCP, WKWebView testing)607- **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Homebrew distribution and CI/CD setup608- **[docs/commands/](docs/commands/)** - Command-specific documentation609610### Command Documentation611612Each command has detailed documentation:613- [docs/commands/fetch/](docs/commands/fetch/) - Download documentation614- [docs/commands/save/](docs/commands/save/) - Build search indexes615- [docs/commands/serve/](docs/commands/serve/) - Start MCP server616- [docs/commands/search/](docs/commands/search/) - Search documentation from CLI617- [docs/commands/doctor/](docs/commands/doctor/) - Check server health618619## Contributing620621Issues and pull requests are welcome! I'd love to hear how you're using Cupertino with your AI workflow.622623For questions and discussion, use [GitHub Discussions](https://github.com/mihaelamj/cupertino/discussions).624625I prefer collaboration over competition — if you're working on something similar, let's find ways to work together.626627Don't hesitate to submit a PR because of code style. I'd rather have your contribution than perfect formatting.628629By participating in this project you agree to abide by the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/).630631For development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).632633## Project Status634635**Version:** 0.9.1636**Status:** 🚧 Active Development637638- ✅ All core functionality working639- ✅ 93 tests passing (100% pass rate)640- ✅ 0 lint violations641- ✅ Swift 6.2 compliant with 100% strict concurrency checking642- ✅ All production bugs resolved643644## License645646MIT License - see [LICENSE](LICENSE) for details647648## Acknowledgments649650- Built with Swift 6.2 and Swift Package Manager651- Uses [swift-argument-parser](https://github.com/apple/swift-argument-parser) for CLI652- Implements [Model Context Protocol](https://modelcontextprotocol.io) specification653- Inspired by the need for offline Apple documentation access654655## Related Repositories656657- **[cupertino-desktop](https://github.com/mihaelamj/cupertino-desktop)** - Native macOS desktop app with graphical interface658- **[cupertino-docs](https://github.com/mihaelamj/cupertino-docs)** - Pre-built documentation archive for quick installation659- **[cupertino-sample-code](https://github.com/mihaelamj/cupertino-sample-code)** - Apple sample code repository mirror660661The docs and sample-code repositories will be used by the planned `make install (full)` command (see [#52](https://github.com/mihaelamj/cupertino/issues/52)), providing pre-built documentation and sample code to avoid the initial 20+ hour crawl.662663## Support664665- **Issues:** [GitHub Issues](https://github.com/mihaelamj/cupertino/issues)666- **Discussions:** [GitHub Discussions](https://github.com/mihaelamj/cupertino/discussions)667668---669670**Note:** This tool is for educational and development purposes. Respect Apple's Terms of Service when using their documentation.671
Full transparency — inspect the skill content before installing.