Xcode Index MCP

🚀 Xcode Index MCP

Empower Goose/Cursor to access your iOS/macOS project index via the Model Control Protocol (MCP) and IndexStoreDB. This offers comprehensive lists of function call sites to assist your agent with refactoring and code navigation.

🚀 Quick Start

🔍 Example prompt

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

📦 Installation

1. Install uv (Python package manager) and run uv sync

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

2. Build the Swift service (Xcode must be installed)

   cd swift-service
   swift build
   

   This step is essential as it provides the interface to Xcode's index.

3. Install in Agent of your choice

   ✨ Goose:

   Go to settings and add a custom extension. In the modal that pops up, under the command field, add this line:

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

   Note: Replace <USERNAME> with your actual system username.

   ✨ Cursor:

   Go to Settings > MCP > Add new global MCP server. Update mcp.json (typically located in your Cursor configuration directory) to look something like this:

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

   Note: Replace <USERNAME> with your actual system username.

4. Update .gooseHints or cursorRules in your project to tell your agent how to use the plugin. Replace the project name with the name of your project as it appears in the derived data folder.

Use tool `xcode-index-mcp` if available. Use project name <Your project name here>. The tool can locate call sites of functions, and function definitions from call sites. If you need a filepath to make a request, use `rg` to find the file and `rg -n` to find the line number. Use the absolute path when requesting symbols from a file.

For Cursor, you may want to add these instructions in their own rule file - at the time of writing I don't think cursor reads the MCP instructions field.

💻 Usage Examples

Basic Usage

The basic usage involves following the installation steps and then using the tool as described in the example prompt. For example, you can give commands like "Remove myParameter from the initializer on line 48 of MyViewController.swift. Use the Xcode Index MCP to ensure all references are updated."

🔧 Technical Details

The tool consists of two main components:

1. An MCP server in the src directory that handles communication with Goose/Cursor
2. A Swift service in the swift-service directory that interfaces with Xcode's index using Apple's IndexStoreDB package

When the MCP server calls 'load_index', the Swift service will look through Xcode's derived data directory for a project file. When found it will attempt to load the project's index. Queries are passed from the MCP server to the index through a subset of the methods provided in IndexStoreDB.

🧪 Running tests

To run tests for Swift, cd into swift-service and run swift test.