苹果文档 MCP

一个模型上下文协议（MCP）服务器，可在您的 AI 编码助手内直接提供对苹果开发者文档的无缝访问。 注意： 大家好，感谢您查看这个 MCP！由于我一直定期维护它，在不断改进以支持不同平台并添加新功能的同时，开发成本变得非常高昂（令牌可不便宜啊各位）。

如果您觉得这个 MCP 有用，我将非常感激您点击上方的 ❤️ 赞助 按钮，任何贡献都将不胜感激！谢谢。

📋 更改日志

感谢 GitHub 团队赠送我一年的 Copilot Pro+ 订阅，你们太棒了！也感谢 @billibala、@theoddbrick、@christopherbattlefrontlegal 的赞助！你们真是了不起。

• 完整的发布历史请参见 CHANGELOG.md。
• 1.9.6
  • 重大修复：简化了 search_symbols，使其对 AI 代理更加可预测。
  • 在 search_symbols 中为诸如 GridItem、View 和 ButtonStyle 等查询添加了精确符号解析。
  • 将 search_symbols 改为优先返回符号结果，并将文章和指南单独归入一个部分。
  • 修复了通配符行为，使回退搜索能够尊重 * 和 ? 模式，而不是降级为简单的子字符串匹配。
  • 移除了关于后台下载和“全面”索引的误导性搜索提示信息。
  • 去除了那些既无用又会增加混淆、却无法提升搜索效果的代码路径。
  • 修复了首次搜索索引初始化问题，确保基于缓存的符号搜索在使用结果之前完成构建。
• 1.9.1
  • 将缓存文档移至 .cache/ 目录，以保持仓库整洁。
  • 将 MCP 日志输出重定向到标准错误流，以保持协议的标准输出干净（此前这会导致 Codex 符号搜索出错）。

安装

VS Code

1. 打开命令面板（Shift+Cmd+P）。
2. 运行 MCP: 添加服务器。
3. 当提示选择服务器类型时，选择 npm。
4. 输入以下包：

apple-doc-mcp-server

Claude Code:

claude mcp add apple-docs -- npx apple-doc-mcp-server@latest

OpenAI Codex:

codex mcp add apple-doc-mcp -- npx apple-doc-mcp-server@latest

手动配置：

{
	"mcpServers": {
		"apple-docs": {
			"command": "npx",
			"args": ["apple-doc-mcp-server@latest"]
		}
	}
}

本地运行：

yarn install
yarn build

{
  "mcpServers": {
    "apple-docs": {
      "command": "node",
      "args": ["/绝对路径/to/apple-doc-mcp/dist/index.js"]
    }
  }
}

搜索技巧

• 当您知道确切的 API 名称时，请使用完整名称（如 "GridItem"、"ButtonStyle"、"View"）。
• 从宽泛的关键词开始（例如 "tab"、"animation"、"gesture"）。
• 尝试使用同义词（如 "sheet" 对应 "modal"，"toolbar" 对应 "tabbar"）。
• 使用通配符（如 "Grid*"、"*Item"、"Lazy*"）进行灵活匹配。
• 使用多个关键词（如 "tab view layout"）来缩小结果范围。
• 如果没有找到任何结果，请使用不同的关键词重新运行 discover_technologies，或选择另一个框架。
• search_symbols 会优先返回符号结果，并将匹配的文章单独列出。

可用工具

• discover_technologies – 浏览并筛选框架，然后再选择一个。
• choose_technology – 设置当前活动的框架；在搜索文档之前必须先设置。
• current_technology – 显示当前选择及下一步操作建议。
• search_symbols – 优先搜索符号，支持精确名称解析和通配符匹配，并将文章结果单独列出。
• get_documentation – 打开已知符号或文档路径的详细文档。
• get_version – 获取当前 MCP 服务器的版本信息。

Apple Doc MCP 快速上手指南

Apple Doc MCP 是一个基于模型上下文协议（MCP）的服务器，旨在让 AI 编程助手能够无缝访问 Apple 开发者文档。通过它，你可以直接在对话中查询 SwiftUI、UIKit 等框架的 API 符号、指南和文章。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS（推荐，因主要面向 Apple 生态），Linux 或 Windows 亦可运行。
• 运行时依赖：必须安装 Node.js (建议 v18 或更高版本)，因为该工具通过 npx 运行。
• 宿主环境：已安装支持 MCP 协议的 AI 客户端，例如：
  • VS Code (需安装 MCP 相关插件)
  • Claude Code
  • OpenAI Codex
  • 其他兼容 MCP 标准的本地或云端助手

提示：国内用户若遇到 npm 或 npx 下载缓慢的问题，可临时配置淘宝镜像源： npm config set registry https://registry.npmmirror.com

安装步骤

根据你的使用场景，选择以下任一方式进行安装：

方式一：VS Code 图形化安装

1. 打开命令面板：按下 Shift + Cmd + P (Mac) 或 Shift + Ctrl + P (Win/Linux)。
2. 输入并运行命令：MCP: Add Server。
3. 当提示选择服务器类型时，选择 npm。
4. 在弹出的输入框中填入包名：

   apple-doc-mcp-server
   

方式二：命令行安装 (Claude Code / OpenAI Codex)

如果你使用的是 Claude Code：

claude mcp add apple-docs -- npx apple-doc-mcp-server@latest

如果你使用的是 OpenAI Codex：

codex mcp add apple-doc-mcp -- npx apple-doc-mcp-server@latest

方式三：手动配置文件安装

如果你的 AI 客户端支持直接编辑 mcp.json 配置文件，请添加以下内容：

{
	"mcpServers": {
		"apple-docs": {
			"command": "npx",
			"args": ["apple-doc-mcp-server@latest"]
		}
	}
}

方式四：本地源码构建 (开发者模式)

如需修改源码或离线运行：

git clone <仓库地址>
cd apple-doc-mcp
yarn install
yarn build

然后在配置文件中指向构建后的文件：

{
  "mcpServers": {
    "apple-docs": {
      "command": "node",
      "args": ["/absolute/path/to/apple-doc-mcp/dist/index.js"]
    }
  }
}

基本使用

安装完成后，重启你的 AI 助手即可开始使用。以下是典型的工作流和搜索技巧：

1. 选择技术框架

在搜索具体文档前，必须先激活目标框架（如 SwiftUI, UIKit 等）。

• 操作：询问助手“列出可用的技术框架”或直接调用 discover_technologies。
• 示例：

  “我想查找 SwiftUI 的文档，请帮我选择该技术。” (后台将执行 choose_technology)

2. 搜索 API 符号

使用 search_symbols 工具进行精确或模糊搜索。

• 精确搜索（推荐）：直接使用确切的类名或结构体名称。

  “查找 GridItem 的用法” “查看 ButtonStyle 的定义”

• 通配符搜索：当你不确定完整名称时。

  “搜索 Grid* 相关的符号” “查找以 View 结尾的类型 *View"

• 关键词组合：

  “搜索关于 tab view layout 的内容”

3. 获取详细文档

找到目标符号后，获取其完整文档内容。

• 操作：直接请求查看某个符号的详情。

  “显示 LazyVStack 的详细文档” (后台将执行 get_documentation)

💡 搜索小贴士

• 同义词尝试：如果搜不到结果，尝试近义词（例如用 sheet 代替 modal，用 toolbar 代替 tabbar）。
• 结果分类：search_symbols 会优先返回代码符号（Symbol），并将相关文章和指南单独列出，请注意区分。
• 无结果处理：如果搜索无果，尝试重新运行 discover_technologies 切换不同的关键词或框架。