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