🚀 Apple Doc MCP

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

🚀 快速开始

按照以下安装步骤完成安装配置后，你就可以自然地与 AI 助手交流，使用相关功能获取苹果文档信息。例如：

• 浏览可用技术："Use apple-doc-mcp to list all current Apple frameworks"
• 探索框架："Use apple-doc-mcp to browse SwiftUI framework structure"
• 搜索特定 API："Search Apple's SwiftUI docs for drag and drop APIs"
• 获取详细文档："Get the latest SwiftUI View protocol docs from Apple"

AI 会自动使用 MCP 工具来获取最新的苹果文档并提供全面的答案。

✨ 主要特性

• 🔍 智能搜索：支持通配符（*, ?），可在所有苹果框架中查找符号。
• 📚 框架浏览：可探索任意苹果框架结构（如 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 助手，让其使用 MCP 工具获取苹果文档信息：

"Use apple-doc-mcp to list all current Apple frameworks"
"Use apple-doc-mcp to browse SwiftUI framework structure"
"Search Apple's SwiftUI docs for drag and drop APIs"
"Get the latest SwiftUI View protocol docs from Apple"

高级用法

你可以根据不同工具的参数进行更精确的搜索，例如：

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

📚 详细文档

可用工具

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。