# Xcode Index MCP

Gives Goose/Cursor access to your iOS/macOS project index through the Model Control Protocol (MCP) and IndexStoreDB. This provides exhaustive lists of function call sites to help your agent with refactoring and code navigation.

## Example prompt

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

## How to use

1. Install `uv` (Python package manager) and run `uv sync`
    ```bash
    brew install uv
    cd /path/to/this/repo
    uv sync
    ```

2. Build the Swift service (Xcode must be installed)
    ```bash
    cd swift-service
    swift build
    ```
    This step is required 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:

    ```bash
    /Users/<USERNAME>/Development/xcode-index-mcp/.venv/bin/xcode-index-mcp
    ```
    Note: Replace `<USERNAME>` with your actual system username, or with the correct path xcode-index-mcp on your machine.

    The rest should look something like this:

    <img src="goose-config-screenshot.png" width="400">

    ### 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:
    
    ```json
        {
            "mcpServers": {
                "Xcode Index MCP": {
                    "command": "/Users/<USERNAME>/Development/xcode-index-mcp/.venv/bin/xcode-index-mcp"
                }
            }
        }
    ```
    Note: Replace `<USERNAME>` with your actual system username, or with the correct path xcode-index-mcp on your machine.

    ### Claude Code:

    Run this command in the terminal to add the mcp to Claude Code
    ```bash
    claude mcp add xcode-index-mcp -- /Users/<USERNAME>/Development/xcode-index-mcp/.venv/bin/xcode-index-mcp
    ```
    Note: Replace `<USERNAME>` with your actual system username, or with the correct path xcode-index-mcp on your machine.

4. Update `.gooseHints`, `cursorRules`, or `CLAUDE.MD`  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](https://github.com/block/xcode-index-mcp/blob/main/src/xcode_index_mcp/server.py#L14-L52) in their own rule file - at the time of writing I don't think cursor reads the MCP `instructions` field.

## Running tests

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

## How it works

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](https://github.com/swiftlang/indexstore-db/blob/main/Sources/IndexStoreDB/IndexStoreDB.swift).