{"id":50891590,"url":"https://github.com/nzrsky/appleref-mcp","last_synced_at":"2026-06-15T21:30:27.529Z","repository":{"id":360405223,"uuid":"1224626715","full_name":"nzrsky/appleref-mcp","owner":"nzrsky","description":"Offline MCP server for Apple Developer Documentation, reading directly from a Dash-format Apple_API_Reference.docset","archived":false,"fork":false,"pushed_at":"2026-05-26T08:07:10.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T10:09:40.940Z","etag":null,"topics":["apple-developer-documentation","claude-code","claude-mcp","dash-docset","ios","macos","mcp","model-context-protocol","objective-c","offline-documentation","swift","swiftui","uikit"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nzrsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-29T13:18:07.000Z","updated_at":"2026-05-26T08:07:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nzrsky/appleref-mcp","commit_stats":null,"previous_names":["nzrsky/appleref-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nzrsky/appleref-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Fappleref-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Fappleref-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Fappleref-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Fappleref-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nzrsky","download_url":"https://codeload.github.com/nzrsky/appleref-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nzrsky%2Fappleref-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34381756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-developer-documentation","claude-code","claude-mcp","dash-docset","ios","macos","mcp","model-context-protocol","objective-c","offline-documentation","swift","swiftui","uikit"],"created_at":"2026-06-15T21:30:26.493Z","updated_at":"2026-06-15T21:30:27.523Z","avatar_url":"https://github.com/nzrsky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# appleref-mcp\n\nOffline MCP server for **Apple Developer Documentation**, reading directly from a\nDash-format `Apple_API_Reference.docset`. No network calls, no Dash.app required —\njust the `.docset` directory on disk.\n\n## Why\n\nLLM agents working on Apple platforms need accurate, current API documentation,\nbut `developer.apple.com` is heavy JS, scrapers fight TLS quirks, and Apple's docs\naren't shipped in Xcode anymore. Dash maintains a complete, regularly-updated\noffline mirror as a single self-contained docset bundle. This server reads that\nbundle directly.\n\n## Requirements\n\n- Python 3.11+\n- An `Apple_API_Reference.docset` directory. By default the server downloads\n  a packed copy (~350 MB compressed, ~1.4 GB on disk) from this repo's\n  GitHub releases on first run — no Dash needed.\n\n  If you'd rather supply your own, install [Dash](https://kapeli.com/dash)\n  and download the *Apple API Reference* docset; the bundle lives at:\n  ```\n  ~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset\n  ```\n  The server uses it automatically from that path, or from anywhere you\n  point `APPLEREF_DOCSET` at. Dash doesn't need to be running.\n\n## Install\n\nPick the option that fits your workflow.\n\n### Run straight from GitHub (no install)\n\n```bash\nuvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp\n```\n\n### Install as a uv tool (recommended)\n\n```bash\nuv tool install git+https://github.com/nzrsky/appleref-mcp\nappleref-mcp           # binary on your PATH\n```\n\nTo upgrade later: `uv tool upgrade appleref-mcp`.\n\n### From a local checkout\n\n```bash\ngit clone https://github.com/nzrsky/appleref-mcp.git\ncd appleref-mcp\nuv tool install --from . appleref-mcp\n# or, for hacking:\nuv sync \u0026\u0026 uv run appleref-mcp\n```\n\n## Configure docset location\n\nThe server looks for the docset in this order:\n\n1. `APPLEREF_DOCSET` environment variable (path to the `.docset` directory, or its parent)\n2. `./Apple_API_Reference.docset`\n3. `~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset`\n4. `~/Apple_API_Reference.docset`\n5. `~/.cache/appleref-mcp/Apple_API_Reference.docset` (auto-download cache)\n\nIf none of those exist, the server downloads the latest packed docset from\nthis repo's GitHub releases into the cache directory on first run, then\noperates fully offline from then on.\n\n| env var | default | purpose |\n| --- | --- | --- |\n| `APPLEREF_DOCSET` | unset | explicit docset path (highest priority) |\n| `APPLEREF_AUTO_DOWNLOAD` | `1` | set to `0` to disable the GitHub fallback |\n| `APPLEREF_CACHE_DIR` | `~/.cache/appleref-mcp` | where the auto-downloaded docset lives |\n| `APPLEREF_RELEASE_REPO` | `nzrsky/appleref-mcp` | source repo for the release asset |\n| `APPLEREF_RELEASE_TAG` | latest `docset-*` | pin to a specific release |\n\n## Wire it up to Claude Code\n\nThe fastest path uses `uvx` so nothing needs to be installed up front:\n\n```bash\nclaude mcp add appleref -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp\n```\n\nIf your docset isn't in the default Dash location, pass `APPLEREF_DOCSET`:\n\n```bash\nclaude mcp add appleref \\\n    --env APPLEREF_DOCSET=/path/to/Apple_API_Reference.docset \\\n    -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp\n```\n\nAfter adding, restart Claude Code and verify:\n\n```bash\nclaude mcp list                    # should show 'appleref'\n# or, in a Claude Code session:\n/mcp                               # interactive view of connected servers\n```\n\nIf you installed via `uv tool install`, swap the command for the bare binary:\n\n```bash\nclaude mcp add appleref -- appleref-mcp\n```\n\n### Manual MCP config (other clients)\n\n```json\n{\n  \"mcpServers\": {\n    \"appleref\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/nzrsky/appleref-mcp\",\n        \"appleref-mcp\"\n      ],\n      \"env\": {\n        \"APPLEREF_DOCSET\": \"/path/to/Apple_API_Reference.docset\"\n      }\n    }\n  }\n}\n```\n\n### Quick smoke test\n\nWithout a Claude client, you can drive the server directly over stdio:\n\n```bash\nprintf '%s\\n' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"smoke\",\"version\":\"0\"}}}' \\\n  '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}' \\\n  '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}' \\\n  | appleref-mcp\n```\n\nYou should see two JSON-RPC responses listing the four tools.\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `search_apple_docs(query, language?, framework?, type?, limit?)` | Find symbols by name. |\n| `get_apple_doc(query, language?, framework?)` | Return a full documentation page as markdown. Accepts a name or a canonical path. |\n| `list_frameworks(filter?)` | List indexed frameworks. |\n| `list_types()` | List symbol kinds with counts. |\n\n`language` is `\"swift\"` (default) or `\"objc\"`.\n\n## How it works\n\nThe Dash docset stores documentation in two SQLite databases plus a directory\nof brotli-compressed files:\n\n```\nContents/Resources/optimizedIndex.dsidx     ← name → URL index (FTS4)\nContents/Resources/Documents/cache.db        ← uuid → (data_id, offset, length)\nContents/Resources/Documents/fs/\u003cdata_id\u003e    ← brotli(concatenated DocC RenderJSON)\n```\n\nFor a given symbol path:\n\n```\ncanonical = \"/documentation/swiftui/griditem\"\nuuid      = lang_prefix + base64url(sha1(canonical)[:6]).rstrip(\"=\")\n            (lang_prefix is \"ls\" for Swift, \"lc\" for ObjC)\n→ refs WHERE uuid=? → (data_id, offset, length)\n→ brotli.decompress(fs/\u003cdata_id\u003e)[offset:offset+length] = DocC JSON\n```\n\nThe server renders the JSON to markdown and returns it.\n\n## Development\n\n```bash\nuv sync\nuv run pytest -v\n```\n\nTests run end-to-end against a real docset and skip cleanly if none is\navailable.\n\n## Publishing a new docset release\n\nMaintainer-only. Requires a local Dash with the Apple API Reference\ndocset downloaded.\n\n```bash\n# 1. pack — writes dist/appleref-docset-\u003ctag\u003e.tar.xz + .sha256 + .notes.md\n./tools/pack-docset.sh\n\n# 2. publish — prints the exact gh command at the end of step 1; e.g.\ngh release create docset-24500-79 \\\n  --title 'Apple docset 24500-79' \\\n  --notes-file dist/appleref-docset-24500-79.notes.md \\\n  dist/appleref-docset-24500-79.tar.xz \\\n  dist/appleref-docset-24500-79.tar.xz.sha256\n```\n\nThe MCP server picks up the new release automatically on its next\nfirst-run install (or when the cache directory is cleared).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzrsky%2Fappleref-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnzrsky%2Fappleref-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnzrsky%2Fappleref-mcp/lists"}