Apple Doc MCP

🚀 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。