convez.ai
MCP ServerDesenvolvimento WebIntermediário
nzrsky

AppleRef MCP – Documentação Apple Offline

nzrsky/appleref-mcp

Documentação Apple offline para Claude e agentes LLM

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece acesso offline completo à documentação de API do Apple, lendo direto de um docset no formato Dash. Elimina dependência de scraping ou de rede para consultar APIs do ecossistema Apple durante desenvolvimento.

Instalação

$npx convez-ai nzrsky/appleref-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
docset-24500-79
Issues abertas
1
Contribuidores
2

Casos de uso

  • Consultar APIs Apple (iOS, macOS, Swift) sem internet
  • Assistir desenvolvimento de apps nativos com contexto preciso de referência
  • Integrar documentação oficial Apple a workflows de IA sem latência de rede

Veredito

Ferramenta especializada e bem pensada para quem desenvolve no ecossistema Apple com suporte a IA. O design offline + auto-download eficiente resolve um problema real de latência e confiabilidade em buscas de referência.

README

A tradução para o português deste README ainda está na fila.

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 vardefaultpurpose
APPLEREF_DOCSETunsetexplicit docset path (highest priority)
APPLEREF_AUTO_DOWNLOAD1set to 0 to disable the GitHub fallback
APPLEREF_CACHE_DIR~/.cache/appleref-mcpwhere the auto-downloaded docset lives
APPLEREF_RELEASE_REPOnzrsky/appleref-mcpsource repo for the release asset
APPLEREF_RELEASE_TAGlatest 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

ToolPurpose
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

Ver o original no GitHub

Bom para

Relacionados