cupertino MCP工具

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)

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

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:

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

Quick Setup (Recommended) - download pre-built databases (~30 seconds)

cupertino setup # Download databases from GitHub cupertino serve # Start MCP server

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

Instant Setup (Recommended)

```bash

Stream and build locally (~45 minutes)

Use this if you want to build the database yourself

cupertino save --remote

Manual Setup (Advanced)

```bash

Build search index (~2-5 minutes)

cupertino save ```

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.

Install via Homebrew or from source (see Installation above)

cupertino setup

**Option A: Install with OpenSkills (Recommended)**

[OpenSkills](https://github.com/numman-ali/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

Build System

```bash

Quick Start

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

Example Use Cases

Download sample code from GitHub (~4 minutes, 619 projects)

cupertino fetch --type samples

List sample projects

cupertino list-samples --framework swiftui --format json ```

All commands support --format json for structured output that agents can parse.

Available Sources: - apple-docs - Official Apple documentation (~352,712 pages indexed in v1.2.0) - samples - Apple sample code projects - hig - Human Interface Guidelines - swift-evolution - Swift Evolution proposals - swift-org - Swift.org documentation - swift-book - The Swift Programming Language book - apple-archive - Legacy programming guides - packages - Swift package documentation

Quick Reference

```bash

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

Development workflow

make test-unit # Fast unit tests only make test-integration # All tests (includes network calls) make format # Format code with SwiftFormat make lint # Lint with SwiftLint ```

4. Custom Documentation Workflows

```bash

Alternative: Build from GitHub (~45 minutes)

cupertino save --remote # Stream and build locally

Alternative: Build from GitHub

```bash

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