Apple Doc MCP

这是一个模型上下文协议（MCP）服务器，它提供了直接在您的AI编码助手中访问Apple开发者文档的无缝途径。

注意： 大家好，感谢您关注这个MCP！由于我一直在定期维护它，因此构建和改进它以适应不同平台并添加新功能变得非常昂贵（代币并不便宜）。如果您觉得这个MCP有用，我非常感激您点击上面的❤️ 赞助按钮进行赞助。任何贡献都是受欢迎的！谢谢。

📋 更新日志

新的符号搜索！感谢@christopherbattlefrontlegal 和 @Indading 的赞助！你们很棒。请尽可能地贡献，我的目标是每月获得100美元，这样我至少可以资助一个专门用于此项目的Claude代码账户。

• 1.9.1

  • 将缓存文档移动到.cache/目录以保持仓库整洁
  • 将MCP日志路由到stderr，以保持协议stdout的干净（这曾导致Codex符号搜索出现问题）

• 1.8.9

  • 重大修复：解决了关键缓存不一致问题，使符号搜索结果更加可靠
  • 重大修复：实现了有状态的LocalSymbolIndex，消除了每次搜索时重建索引的需求
  • 重大修复：修复了符号搜索中的技术过滤问题，现在仅在选定的技术内进行搜索
  • 重大修复：修复了搜索返回其他Apple框架（如EnergyKit）的无关结果的问题
  • 增加了通配符搜索支持（* 和 ? 模式），以实现灵活的符号发现
  • 增加了本地符号索引，以实现快速缓存搜索和持久状态管理
  • 增强了错误消息，提供动态技术建议和逐步指导
  • 改进了分词处理，支持camelCase/PascalCase（GridItem → grid, item, griditem）
  • 增强了搜索，提高了分词和评分效果
  • 搜索现在显示已索引的符号总数，并保持一致的计数
  • 修复了技术选择持久性问题
  • 修复了硬编码的服务器版本，改为从package.json动态读取
  • 增加了get_version工具，以暴露版本信息
  • 增加了技术感知的符号索引，防止跨框架污染
  • 增强了智能检测特定符号名称的搜索回退逻辑
  • 改进了错误消息，直接建议使用get_documentation查找已知符号
  • 增加了结果验证，以检测并警告无关搜索结果
  • 更新了工具描述，澄清何时使用搜索与直接文档查找
  • 增强了搜索处理器，使用持久符号索引
  • 增加了缓存验证和清理逻辑，以提高可靠性

• 1.6.2

  • 修复了硬编码的服务器版本，改为从package.json动态读取
  • 增加了get_version工具，以暴露版本信息
  • 动态路径解析 - 不再使用硬编码路径
  • 修复了缓存位置，使用MCP目录而不是污染home/工作目录
  • 修复了教程和非框架内容检索（示例应用、更新等）
  • 改进了复合词（如GridItem）的搜索分词处理
  • 增强了模糊匹配和大小写不敏感支持的搜索评分
  • 扩展了搜索索引覆盖范围，以实现更好的符号发现
  • 增加了不同类型内容的路径验证

• 1.5.1（重大更新！）

  • 现在已在npm上发布！有人已经将其上传为apple-doc-mcp，无法联系到他们，所以我不得不将其重命名为apple-doc-mcp-server，感谢随机用户！
  • 引入了按技术缓存、强制框架选择以及引导发现/搜索流程。
  • 现在不会轰炸文档服务器，所有技术在首次调用后都会被缓存，使得每次搜索都非常高效！
  • 使用多个搜索回退确保找到您需要的内容，如果失败，它会使用正则表达式在整个技术范围内搜索并仍然给出建议！
  • 它现在会询问哪个文档更相关！虽然模糊搜索非常基础，但它确实非常有效！
  • 在许多方面简化了MCP，我现在只是在踢自己！
  • 处理程序现在位于'src/server/handlers/'中，因此每个工具都易于阅读和进化，而无需触及入口点。
  • 这本应是版本1.0.0，但仍有一些小问题，请报告它们。

• 1.0.2 - 完全删除，因为AI合并时没有彻底检查，对此表示歉意。

• 1.0.1 – 初始发布。

快速开始

"使用apple mcp选择swiftui搜索tabbar"

配置您的MCP客户端（示例）：

使用npx（推荐）：

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

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 

或者使用带有构建文件的node：

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

对于本地开发：

pnpm install
pnpm build

🔄 典型工作流

1. 浏览目录：
   • discover_technologies { "query": "swift" }
   • discover_technologies { "page": 2, "pageSize": 10 }
2. 锁定一个框架：
   • choose_technology { "name": "SwiftUI" }
   • current_technology
3. 在活动框架内搜索：
   • search_symbols { "query": "tab view layout" }
   • search_symbols { "query": "Grid*" }（通配符搜索）
   • search_symbols { "query": "*Item" }（查找所有项目）
4. 查看文档：
   • get_documentation { "path": "TabView" }
   • get_documentation { "path": "documentation/SwiftUI/TabViewStyle" }

搜索技巧

• 从广泛的角度开始（例如："tab"，"animation"，"gesture"）。
• 尝试同义词（"sheet" vs "modal"，"toolbar" vs "tabbar"）。
• 使用通配符（"Grid*"，"Item"，"Lazy"）进行灵活匹配。
• 使用多个关键词（"tab view layout"）以缩小结果范围。
• 如果没有任何结果，请使用不同的关键词重新运行discover_technologies或选择另一个框架。
• 缓存现在位于.cache/目录中，以避免杂乱。

🧰 可用工具

• discover_technologies – 浏览/筛选框架前选择一个。
• choose_technology – 设置活动框架；在搜索文档之前必需。
• current_technology – 显示当前选择和快速下一步操作。
• search_symbols – 在活动框架内进行模糊关键词搜索，支持通配符。
• get_documentation – 查看符号文档（允许相对名称）。
• get_version – 获取当前MCP服务器版本信息。

🚀 高级特性

可靠的符号搜索

• 持久索引：在搜索之间保持状态的符号索引，以实现一致的结果
• 通配符支持：使用*匹配任意字符，使用?匹配单个字符
• 智能分词：自动处理camelCase/PascalCase（GridItem → grid, item, griditem）
• 技术过滤：仅在选定框架内进行搜索，以避免无关结果
• 缓存性能：具有框架特定缓存的快速本地搜索
• 回退搜索：当本地索引有限时使用框架引用
• 缓存验证：对损坏或无效缓存文件的强大错误处理

增强的错误消息

• 明确指导：未选择技术时提供明确的逐步说明
• 动态建议：显示可用技术和确切命令
• 快速入门示例：SwiftUI和UIKit特定的工作流程
• 专业格式：清晰、有用的错误消息，带有表情符号和结构

⚠️ 当前限制

• 有限的符号覆盖率：搜索依赖于缓存的框架数据和引用，而非全面的符号下载
• 无后台下载：由于稳定性问题，全面的符号下载器目前已被禁用
• 框架特定：每个技术都有自己的缓存和索引
• 缓存依赖：搜索质量取决于可用的缓存框架数据