Xcode Index MCP

🚀 Xcode Index MCP

Xcode Index MCP 藉助模型控制協議（MCP）和 IndexStoreDB，讓 Goose/Cursor 能夠訪問你的 iOS/macOS 項目索引。它能提供詳盡的函數調用位點列表，助力你的智能助手進行代碼重構和導航。

🚀 快速開始

🔍 示例提示

"從 MyViewController.swift 文件第 48 行的初始化方法中移除 myParameter。使用 Xcode Index MCP 確保所有引用都得到更新。"

📦 安裝指南

1. 安裝 uv（Python 包管理器）並運行 uv sync

   brew install uv
   cd /path/to/this/repo
   uv sync
   

2. 構建 Swift 服務（必須安裝 Xcode）

   cd swift-service
   swift build
   

   這一步是必需的，因為它提供了與 Xcode 索引的接口。
3. 在你選擇的智能助手中安裝
   • Goose： 進入設置並添加自定義擴展。在彈出的對話框中，在 command 字段添加以下內容：

     uv run /Users/<USERNAME>/Development/xcode-index-mcp/.venv/bin/xcode-index-mcp
     

     注意：請將 <USERNAME> 替換為你實際的系統用戶名。
   • Cursor： 進入 Settings > MCP > Add new global MCP server。更新 mcp.json（通常位於 Cursor 配置目錄），使其內容如下：

     {
         "mcpServers": {
             "Xcode Index MCP": {
                 "command": "uv",
                 "args": ["run", "/Users/<USERNAME>/Development/xcode-index-mcp/.venv/bin/xcode-index-mcp"]
             }
         }
     }
     

     注意：請將 <USERNAME> 替換為你實際的系統用戶名。
4. 更新項目中的 .gooseHints 或 cursorRules 告知你的智能助手如何使用該插件。將項目名稱替換為派生數據文件夾中顯示的項目名稱。

   若可用，使用工具 `xcode-index-mcp`。使用項目名稱 <Your project name here>。該工具可以定位函數的調用位點，以及從調用位點定位函數定義。若需要文件路徑來發起請求，使用 `rg` 查找文件，使用 `rg -n` 查找行號。請求文件中的符號時使用絕對路徑。
   

   對於 Cursor，你可能需要在其規則文件中添加這些說明 —— 在撰寫本文時，我認為 Cursor 不會讀取 MCP 的 instructions 字段。

💻 使用示例

基礎用法

你可以按照上述步驟完成安裝和配置，然後在 Goose 或 Cursor 中使用 Xcode Index MCP 來輔助代碼重構和導航。例如，根據示例提示進行代碼修改：

"Remove `myParameter` from the initializer on line 48 of `MyViewController.swift`. Use the Xcode Index MCP to ensure all references are updated."

🔧 技術細節

該工具主要由兩個組件組成：

1. src 目錄下的 MCP 服務器，負責與 Goose/Cursor 進行通信。
2. swift-service 目錄下的 Swift 服務，使用 Apple 的 IndexStoreDB 包與 Xcode 的索引進行交互。

當 MCP 服務器調用 load_index 時，Swift 服務會在 Xcode 的派生數據目錄中查找項目文件。找到後，它會嘗試加載項目的索引。查詢會通過 IndexStoreDB 提供的部分方法從 MCP 服務器傳遞到索引。

🧪 運行測試

若要運行 Swift 測試，進入 swift-service 目錄並運行 swift test。

cd swift-service
swift test