内容
# appleref-mcp
适用于 **Apple 开发者文档** 的离线 MCP 服务器，直接从 Dash 格式的 `Apple_API_Reference.docset` 读取。无需网络调用，无需 Dash.app — 只需磁盘上的 `.docset` 目录。
## 为什么
在 Apple 平台上工作的 LLM 代理需要准确、当前的 API 文档，但 `developer.apple.com` 包含大量 JavaScript，爬虫难以应对 TLS 问题，而且 Apple 的文档已不再随 Xcode 一起提供。Dash 维护了一个完整、定期更新的离线镜像，作为一个自包含的 docset 包。此服务器直接读取该包。
## 要求
- Python 3.11+
- 一个 `Apple_API_Reference.docset` 目录。默认情况下，服务器会在首次运行时从此存储库的 GitHub 版本中下载一个打包副本（~350 MB 压缩，~1.4 GB 磁盘空间）— 无需 Dash。
如果您更愿意提供自己的，请安装 [Dash](https://kapeli.com/dash) 并下载 *Apple API Reference* docset；该包位于：
```
~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset
```
服务器将自动从该路径或您指向的任何 `APPLEREF_DOCSET` 路径使用它。Dash 不需要运行。
## 安装
选择适合您工作流的选项。
### 直接从 GitHub 运行（无需安装）
```bash
uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
```
### 作为 uv 工具安装（推荐）
```bash
uv tool install git+https://github.com/nzrsky/appleref-mcp
appleref-mcp # 您路径上的二进制文件
```
稍后升级：`uv tool upgrade appleref-mcp`.
### 从本地克隆
```bash
git clone https://github.com/nzrsky/appleref-mcp.git
cd appleref-mcp
uv tool install --from . appleref-mcp
# 或，用于开发：
uv sync && uv run appleref-mcp
```
## 配置 docset 位置
服务器按以下顺序查找 docset：
1. `APPLEREF_DOCSET` 环境变量（`.docset` 目录的路径或其父目录）
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` （自动下载缓存）
如果这些都不存在，服务器将在首次运行时从此存储库的 GitHub 版本中下载最新的打包 docset，然后完全离线运行。
| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `APPLEREF_DOCSET` | 未设置 | 显式 docset 路径（优先级最高） |
| `APPLEREF_AUTO_DOWNLOAD` | `1` | 设置为 `0` 以禁用 GitHub 备用下载 |
| `APPLEREF_CACHE_DIR` | `~/.cache/appleref-mcp` | 自动下载的 docset 存储位置 |
| `APPLEREF_RELEASE_REPO` | `nzrsky/appleref-mcp` | 发布资产的源存储库 |
| `APPLEREF_RELEASE_TAG` | 最新 `docset-*` | 固定到特定版本 |
## 连接到 Claude Code
最快的路径使用 `uvx`，因此无需预先安装任何内容：
```bash
claude mcp add appleref -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
```
如果您的 docset 不在默认的 Dash 位置，请传递 `APPLEREF_DOCSET`:
```bash
claude mcp add appleref \
--env APPLEREF_DOCSET=/path/to/Apple_API_Reference.docset \
-- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
```
添加后，重启 Claude Code 并验证：
```bash
claude mcp list # 应该显示 'appleref'
# 或，在 Claude Code 会话中：
/mcp # 连接服务器的交互式视图
```
如果您通过 `uv tool install` 安装，请将命令替换为裸二进制文件：
```bash
claude mcp add appleref -- appleref-mcp
```
### 手动 MCP 配置（其他客户端）
```json
{
"mcpServers": {
"appleref": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/nzrsky/appleref-mcp",
"appleref-mcp"
],
"env": {
"APPLEREF_DOCSET": "/path/to/Apple_API_Reference.docset"
}
}
}
}
```
### 快速测试
无需 Claude 客户端，您可以直接通过 stdio 驱动服务器：
```bash
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
```
您应该看到两个 JSON-RPC 响应，列出四个工具。
## 工具
| 工具 | 用途 |
| --- | --- |
| `search_apple_docs(query, language?, framework?, type?, limit?)` | 按名称查找符号。 |
| `get_apple_doc(query, language?, framework?)` | 返回一个完整的文档页面作为 markdown。可接受名称或规范路径。 |
| `list_frameworks(filter?)` | 列出索引框架。 |
| `list_types()` | 列出符号类型及其计数。 |
`language` 为 `"swift"`（默认）或 `"objc"`。
## 工作原理
Dash docset 将文档存储在两个 SQLite 数据库和一个 brotli 压缩文件目录中：
```
Contents/Resources/optimizedIndex.dsidx ← 名称 → URL 索引（FTS4）
Contents/Resources/Documents/cache.db ← uuid → （data_id, offset, length）
Contents/Resources/Documents/fs/<data_id> ← brotli(连接的 DocC RenderJSON)
```
对于给定的符号路径：
```
canonical = "/documentation/swiftui/griditem"
uuid = lang_prefix + base64url(sha1(canonical)[:6]).rstrip("=")
（lang_prefix 为 Swift 的 "ls"，ObjC 的 "lc"）
→ refs WHERE uuid=? → （data_id, offset, length）
→ brotli.decompress(fs/<data_id>)[offset:offset+length] = DocC JSON
```
服务器将 JSON 渲染为 markdown 并返回。
## 开发
```bash
uv sync
uv run pytest -v
```
测试与真实的 docset 配合使用，并可在无 docset 时干净地跳过。
## 发布新的 docset 版本
仅限维护人员。需要一个本地的 Dash，其中包含下载的 Apple API Reference docset。
```bash
# 1. 打包 — 写入 dist/appleref-docset-<tag>.tar.xz + .sha256 + .notes.md
./tools/pack-docset.sh
# 2. 发布 — 在步骤 1 的末尾打印确切的 gh 命令；例如：
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
```
MCP 服务器在下一次首次运行安装时（或清除缓存目录时）会自动获取新版本。
## 许可证
MIT
