🚀 Apple Doc MCP

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

🚀 快速开始

按照以下步骤完成安装配置后，你就可以自然地与 AI 助手交流，获取苹果开发者文档的相关信息。

✨ 主要特性

• 🔍 智能搜索：支持通配符（*, ?），可在所有苹果框架中查找符号。
• 📚 框架浏览：可探索任意苹果框架结构，如 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. 尝试输入：“List available Apple technologies”。
3. 你应该能看到 4 个新工具。
4. 服务器启动时会自动检查更新，如有新版本会通知你。

💻 使用示例

基础用法

配置完成后，自然地与 AI 助手交流即可。以下是一些示例：

浏览可用技术

"Use apple-doc-mcp to list all current Apple frameworks"
"Get the latest available Apple technologies from Apple's docs"
"Search Apple documentation for all available frameworks"

探索框架

"Use apple-doc-mcp to browse SwiftUI framework structure"
"Get current UIKit topics from Apple documentation"
"Search Apple docs for Foundation framework details"

搜索特定 API

"Search Apple's SwiftUI docs for drag and drop APIs"
"Use apple-doc-mcp to find RPBroadcast* classes in ReplayKit"
"Look up current *View* symbols across Apple frameworks"
"Find all *Controller classes in UIKit using Apple docs"

获取详细文档

"Get the latest SwiftUI View protocol docs from Apple"
"Use apple-doc-mcp to look up UIViewController documentation"
"Search Apple's current docs for NSURLSession details"

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 仓库是否有可用更新。

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

🔧 技术细节

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

📚 详细文档

📋 变更日志

1.0.1 更新

• 🎯 智能回退系统：当搜索框架而非符号（如 "SwiftUI"）时，服务器现在会提供有用的框架信息和正确使用指南。
• 🔧 工具整合：从 4 个工具精简为 4 个专注工具：
  • list_technologies - 浏览所有苹果框架。
  • get_documentation - 获取符号或框架文档（自动处理两种情况）。
  • search_symbols - 使用通配符和过滤器进行搜索。
  • 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 以加快响应速度。

📋 要求

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

🤝 贡献

如果你发现了 bug 或想添加新功能，欢迎贡献代码！

1. 分叉仓库。
2. 创建功能分支。
3. 提交拉取请求。 详细指南请参阅 CONTRIBUTING.md。