Apple Doc Mcp

开发 TypeScript

🚀 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：克隆并构建

克隆此仓库：

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

安装依赖项：
```
npm install
```
构建服务器：
```
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：重启并测试

重启你的 AI 助手。
尝试输入：“列出可用的苹果技术”。
你应该会看到 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 或想添加新功能？欢迎贡献！

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

详细指南请参阅 CONTRIBUTING.md。

0 条评论
分类：开发