Apple Doc MCP

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