appleref-mcp

Offline MCP server for Apple Developer Documentation, reading directly from a Dash-format Apple_API_Reference.docset. No network calls, no Dash.app required — just the .docset directory on disk.

Why

LLM agents working on Apple platforms need accurate, current API documentation, but developer.apple.com is heavy JS, scrapers fight TLS quirks, and Apple's docs aren't shipped in Xcode anymore. Dash maintains a complete, regularly-updated offline mirror as a single self-contained docset bundle. This server reads that bundle directly.

Requirements

• Python 3.11+

• An Apple_API_Reference.docset directory. By default the server downloads a packed copy (~350 MB compressed, ~1.4 GB on disk) from this repo's GitHub releases on first run — no Dash needed.

  If you'd rather supply your own, install Dash and download the Apple API Reference docset; the bundle lives at:

  ~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset
  

  The server uses it automatically from that path, or from anywhere you point APPLEREF_DOCSET at. Dash doesn't need to be running.

Install

Pick the option that fits your workflow.

Run straight from GitHub (no install)

uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp

Install as a uv tool (recommended)

uv tool install git+https://github.com/nzrsky/appleref-mcp
appleref-mcp           # binary on your PATH

To upgrade later: uv tool upgrade appleref-mcp.

From a local checkout

git clone https://github.com/nzrsky/appleref-mcp.git
cd appleref-mcp
uv tool install --from . appleref-mcp
# or, for hacking:
uv sync && uv run appleref-mcp

Configure docset location

The server looks for the docset in this order:

1. APPLEREF_DOCSET environment variable (path to the .docset directory, or its parent)
2. ./Apple_API_Reference.docset
3. ~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset
4. ~/Apple_API_Reference.docset
5. ~/.cache/appleref-mcp/Apple_API_Reference.docset (auto-download cache)

If none of those exist, the server downloads the latest packed docset from this repo's GitHub releases into the cache directory on first run, then operates fully offline from then on.

env var	default	purpose
APPLEREF_DOCSET	unset	explicit docset path (highest priority)
APPLEREF_AUTO_DOWNLOAD	1	set to 0 to disable the GitHub fallback
APPLEREF_CACHE_DIR	~/.cache/appleref-mcp	where the auto-downloaded docset lives
APPLEREF_RELEASE_REPO	nzrsky/appleref-mcp	source repo for the release asset
APPLEREF_RELEASE_TAG	latest docset-*	pin to a specific release

Wire it up to Claude Code

The fastest path uses uvx so nothing needs to be installed up front:

claude mcp add appleref -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp

If your docset isn't in the default Dash location, pass APPLEREF_DOCSET:

claude mcp add appleref \
    --env APPLEREF_DOCSET=/path/to/Apple_API_Reference.docset \
    -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp

After adding, restart Claude Code and verify:

claude mcp list                    # should show 'appleref'
# or, in a Claude Code session:
/mcp                               # interactive view of connected servers

If you installed via uv tool install, swap the command for the bare binary:

claude mcp add appleref -- appleref-mcp

Manual MCP config (other clients)

{
  "mcpServers": {
    "appleref": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nzrsky/appleref-mcp",
        "appleref-mcp"
      ],
      "env": {
        "APPLEREF_DOCSET": "/path/to/Apple_API_Reference.docset"
      }
    }
  }
}

Quick smoke test

Without a Claude client, you can drive the server directly over stdio:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | appleref-mcp

You should see two JSON-RPC responses listing the four tools.

Tools

Tool	Purpose
search_apple_docs(query, language?, framework?, type?, limit?)	Find symbols by name.
get_apple_doc(query, language?, framework?)	Return a full documentation page as markdown. Accepts a name or a canonical path.
list_frameworks(filter?)	List indexed frameworks.
list_types()	List symbol kinds with counts.

language is "swift" (default) or "objc".

How it works

The Dash docset stores documentation in two SQLite databases plus a directory of brotli-compressed files:

Contents/Resources/optimizedIndex.dsidx     ← name → URL index (FTS4)
Contents/Resources/Documents/cache.db        ← uuid → (data_id, offset, length)
Contents/Resources/Documents/fs/<data_id>    ← brotli(concatenated DocC RenderJSON)

For a given symbol path:

canonical = "/documentation/swiftui/griditem"
uuid      = lang_prefix + base64url(sha1(canonical)[:6]).rstrip("=")
            (lang_prefix is "ls" for Swift, "lc" for ObjC)
→ refs WHERE uuid=? → (data_id, offset, length)
→ brotli.decompress(fs/<data_id>)[offset:offset+length] = DocC JSON

The server renders the JSON to markdown and returns it.

Development

uv sync
uv run pytest -v

Tests run end-to-end against a real docset and skip cleanly if none is available.

Publishing a new docset release

Maintainer-only. Requires a local Dash with the Apple API Reference docset downloaded.

# 1. pack — writes dist/appleref-docset-<tag>.tar.xz + .sha256 + .notes.md
./tools/pack-docset.sh

# 2. publish — prints the exact gh command at the end of step 1; e.g.
gh release create docset-24500-79 \
  --title 'Apple docset 24500-79' \
  --notes-file dist/appleref-docset-24500-79.notes.md \
  dist/appleref-docset-24500-79.tar.xz \
  dist/appleref-docset-24500-79.tar.xz.sha256

The MCP server picks up the new release automatically on its next first-run install (or when the cache directory is cleared).

License

MIT