Apple Doc MCP

🚀 Apple Doc MCP

Apple Doc MCP 是一个模型上下文协议（MCP）服务器，可让你在 AI 编码助手内无缝访问苹果开发者文档。

📋 变更日志

1.0.1 版本更新

• 🎯 智能回退系统：当搜索框架而非符号（例如“SwiftUI”）时，服务器现在会提供有用的框架信息和正确使用指南。
• 🔧 工具整合：从 4 个工具精简为 4 个重点工具：
  • list_technologies - 浏览所有苹果框架
  • get_documentation - 获取符号或框架文档（自动处理两者）
  • search_symbols - 使用通配符和过滤器进行搜索
  • check_updates - 通过 git 检查仓库更新
• 🚀 预构建分发：无需手动构建 - 克隆后即可立即使用
• 🧹 动态框架发现：移除所有硬编码的框架列表，实现完全动态操作
• ⚡ 自动更新通知：服务器在启动时自动检查更新，并在有新版本可用时通知用户
• 🛡️ 增强的错误处理：更好的空值安全性和专业的错误消息

✨ 主要特性

• 🔍 智能搜索：通过通配符支持（*, ?）在所有苹果框架中查找符号。
• 📚 框架浏览：探索任何苹果框架结构（如 SwiftUI、UIKit、Foundation 等）。
• 📖 详细文档：获取带有示例的全面符号文档。
• 🎯 高级过滤：按平台（iOS、macOS 等）、符号类型或框架进行过滤。
• ⚡ 实时数据：始终与苹果的最新文档保持同步。
• 🔄 自动更新提醒：当仓库有更新时自动通知。
• 🧠 针对 AI 优化：干净的 Markdown 输出，非常适合 AI 助手。

📦 安装指南

前提条件

• 系统中安装了 Node.js 18+。
• 安装了 npm（随 Node.js 一起安装）。

步骤 1：克隆并构建

1. 克隆此仓库：

   git clone https://github.com/MightyDillah/apple-doc-mcp.git
   cd apple-doc-mcp
   

2. 安装依赖项：

   npm install
   

3. 构建服务器：

   npm run build
   

   这将编译 TypeScript 代码，并创建包含可执行服务器的 dist/ 文件夹。

步骤 2：配置你的 AI 助手

• Claude Desktop：编辑 ~/.config/claude/claude_desktop_config.json
• Cursor：设置（Cmd/Ctrl + ,）→ 扩展 → MCP
• Continue.dev：编辑 ~/.continue/config.json
• VS Code (Claude)：设置 → MCP 服务器

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

⚠️ 重要提示

请将 /path/to/apple-doc-mcp 替换为你克隆仓库的实际路径。

💡 使用建议

在 macOS/Linux 系统中，可在 apple-doc-mcp 文件夹内运行 pwd 命令以获取绝对路径。

步骤 3：重启并测试

1. 重启你的 AI 助手。
2. 尝试输入：“列出可用的苹果技术”。
3. 你应该会看到 4 个新工具可用。
4. 服务器在启动时会自动检查更新，并在有新版本可用时通知你。

🔧 故障排除

“0 个工具”或服务器无法启动

• 检查 Node.js 版本：确保你安装了 Node.js 18+（node --version）。
• 验证构建是否完成：确保运行 npm run build 后 dist/index.js 文件存在。
• 使用绝对路径：MCP 配置中的相对路径通常会失败。
• 检查配置语法：确保你的 JSON 配置有效。
• 完全重启：在更改配置后，关闭并重新打开你的 AI 助手。

直接测试服务器

# 导航到你的项目文件夹
cd /path/to/apple-doc-mcp

# 测试服务器是否无错误启动
node dist/index.js

你应该会看到：Apple Developer Documentation MCP server running on stdio

常见路径问题

# macOS/Linux - 获取绝对路径
pwd
# 示例输出: /Users/yourname/projects/apple-doc-mcp

# Windows
echo %cd%
# 示例输出: C:\Users\yourname\projects\apple-doc-mcp

💻 使用示例

配置完成后，只需自然地与你的 AI 助手对话即可。以下是一些示例：

浏览可用技术

"使用 apple-doc-mcp 列出所有当前的苹果框架"
"从苹果文档中获取最新可用的苹果技术"
"在苹果文档中搜索所有可用的框架"

探索框架

"使用 apple-doc-mcp 浏览 SwiftUI 框架结构"
"从苹果文档中获取当前的 UIKit 主题"
"在苹果文档中搜索 Foundation 框架的详细信息"

搜索特定 API

"在苹果的 SwiftUI 文档中搜索拖放 API"
"使用 apple-doc-mcp 在 ReplayKit 中查找 RPBroadcast* 类"
"在所有苹果框架中查找当前的 *View* 符号"
"使用苹果文档在 UIKit 中查找所有 *Controller 类"

获取详细文档

"从苹果获取最新的 SwiftUI View 协议文档"
"使用 apple-doc-mcp 查找 UIViewController 文档"
"在苹果的当前文档中搜索 NSURLSession 详细信息"

AI 将自动使用 MCP 工具来获取当前的苹果文档，并提供全面的答案。

🛠️ 可用工具

list_technologies

浏览所有可用的苹果框架和技术。

get_documentation

获取符号或框架的详细文档（自动检测类型）。

• path（必需）：文档路径（例如，"documentation/SwiftUI/View"）或框架名称（例如，"SwiftUI"）

示例：

{"path": "SwiftUI"}
{"path": "documentation/SwiftUI/View"}
{"path": "Foundation"}

search_symbols

使用高级过滤在苹果框架中搜索符号。

• query（必需）：支持通配符的搜索查询
• framework（可选）：在特定框架内搜索
• symbolType（可选）：按符号类型过滤（类、协议、结构体等）
• platform（可选）：按平台过滤（iOS、macOS 等）
• maxResults（可选）：最大结果数（默认值：20）

示例：

{"query": "RPBroadcast*"}
{"query": "*Controller", "framework": "UIKit"}
{"query": "*View*", "platform": "iOS", "maxResults": 5}

check_updates

检查 git 仓库是否有可用更新。

• 无需参数
• 显示当前分支状态、可用更新和更新说明
• 注意：服务器在启动时会自动检查更新并显示通知

🚨 故障排除

服务器无法启动

• 确保安装了 Node.js 18+。
• 验证 MCP 配置中的路径指向正确的 dist/index.js 位置。
• 检查 MCP 配置语法。
• 在更改配置后重启你的 AI 助手。

显示“0 个工具”

• 这通常意味着服务器启动不正常。
• 检查配置中的文件路径是否正确且为绝对路径。
• 确保包含 dist 目录 - 无需构建步骤。
• 尝试直接测试服务器：node /path/to/apple-doc-mcp/dist/index.js

未找到结果

• 尝试使用更宽泛的搜索词。
• 使用通配符模式："*View*" 而非 "View"。
• 移除过滤器以扩大搜索范围。

性能问题

• 首次搜索可能较慢（会构建缓存）。
• 后续搜索会快很多。
• 减少 maxResults 以加快响应速度。

🔧 技术细节

• 10 分钟缓存：避免 API 速率限制。
• 15 秒超时：确保可靠性能。
• 智能框架优先级排序：加快搜索速度。
• 优雅的错误处理：确保稳健运行。

📋 要求

• Node.js：18.0.0 或更高版本。
• 内存：运行期间约 50MB RAM。
• 网络：需要连接到苹果文档 API 的互联网连接。

🤝 贡献

发现了 bug 或想添加新功能？欢迎贡献！

1. 分叉仓库。
2. 创建功能分支。
3. 提交拉取请求。

详细指南请参阅 CONTRIBUTING.md。