# Swift Index Store Mcp

> An MCP server that gives AI agents semantic code navigation that Xcode provides via Cmd+Click and Find Usages. Built on Apple's IndexStoreDB library, which reads the index data that Xcode generates during builds.

- **Type:** MCP server
- **Install:** `agentstack add mcp-hpatel-lincoln-swift-index-store-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hpatel-lincoln](https://agentstack.voostack.com/s/hpatel-lincoln)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hpatel-lincoln](https://github.com/hpatel-lincoln)
- **Source:** https://github.com/hpatel-lincoln/swift-index-store-mcp

## Install

```sh
agentstack add mcp-hpatel-lincoln-swift-index-store-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# IndexStoreMCP

An MCP server that gives AI agents semantic code navigation for Xcode projects. Instead of relying on `grep` and file reading, agents can look up symbols by name, find definitions and references by USR, trace protocol conformances and overrides, and get structural outlines of files — the same navigation that Xcode provides via Cmd+Click and Find Usages.

Built on Apple's [IndexStoreDB](https://github.com/swiftlang/indexstore-db) library, which reads the index data that Xcode generates during builds.

## When is this useful?

- **Large codebases** where `grep` returns too much noise. Symbol lookup by USR is exact — no false matches from comments, strings, or similarly named symbols.
- **Refactoring** — find all protocol conformances, method overrides, and extensions before changing a type or interface. `relatedOccurrences` answers "what will break?" in one call.
- **Navigating unfamiliar code** — agents can trace call graphs and jump between definitions and references the same way a developer uses Cmd+Click in Xcode, instead of guessing at file structure.
- **Reducing context window usage** — `symbolsInFile` returns a structural outline (names, kinds, line numbers) without reading the entire source file. For large files this keeps the agent's context focused.
- **Cross-dependency navigation** — the index includes symbols from your project's Swift package dependencies, not just your own source files.

For small projects, `grep` and file reading are usually fast enough. This MCP pays off as project size and complexity grow.

## Prerequisites

- **macOS 14+**
- **Xcode** installed (provides `libIndexStore.dylib`)
- The target project must have been **built in Xcode** at least once so the index store exists in DerivedData

## Setup

### Build

```sh
git clone https://github.com/hpatel-lincoln/swift-index-store-mcp.git
cd swift-index-store-mcp
swift build -c release
```

The binary is at `.build/release/IndexStoreMCP` inside the cloned directory.

### Configure your MCP client

Claude Code

```sh
claude mcp add index-store-mcp /path/to/swift-index-store-mcp/.build/release/IndexStoreMCP
```

Claude Desktop / Cursor / other MCP clients

Add to your MCP configuration file:

```json
{
  "mcpServers": {
    "index-store-mcp": {
      "command": "/path/to/swift-index-store-mcp/.build/release/IndexStoreMCP"
    }
  }
}
```

### Configuring your agent

Adding the MCP server makes the tools *available*, but agents will often default to `grep` unless instructed otherwise. Add the following to your project's `CLAUDE.md` (or equivalent agent instructions file) to encourage the agent to use the index:

```markdown
## Xcode Navigation (index-store-mcp)

This project has the index-store-mcp server configured. Use it for code navigation
instead of grep when working with Swift/Objective-C source files.

### When to use
- Finding where a symbol is defined, referenced, or called
- Tracing protocol conformances, method overrides, or extensions
- Getting a structural outline of a file before reading it
- Disambiguating symbols with common names (e.g., init, configure, handle)
- Identifying a symbol's type or kind (class, protocol, enum, method, property)
- Navigating into symbols defined in package dependencies

### Workflow
1. Call `loadIndex` with the workspace/project path once at the start of a session
2. Use `searchSymbol` (exact name, preferred) or `searchSymbolPattern` (fuzzy/partial,
   use longer patterns to reduce noise) to find USRs
3. Use `getOccurrences` or `relatedOccurrences` with a USR to find all usage sites
4. Use `symbolAtPosition` when you're reading a file and need the USR at a specific position
5. Use `symbolsInFile` to get a file's structure without reading the full source
6. Call `refreshIndex` after a build to pick up changes
```

## Tools (invoked by the agent)

### loadIndex

Must be called first. Loads the Xcode index for a project.

```
workspacePath: "/path/to/MyApp.xcworkspace"
```

Accepts `.xcworkspace`, `.xcodeproj`, or a bare directory (for Swift packages opened in Xcode).

### searchSymbol

Looks up a symbol by its exact name as it appears in source code. Returns one or more USRs (Unified Symbol Resolutions) that uniquely identify the symbol.

```
name: "viewDidLoad"
```

### searchSymbolPattern

Fuzzy search when you only know a partial name. Supports subsequence matching — `mvc` finds `MyViewController`, `vdl` finds `viewDidLoad`.

```
pattern: "mvc"
```

### symbolAtPosition

Returns the symbol at a specific file location. More precise than `searchSymbol` when the name is ambiguous (e.g., `init`).

```
file: "/path/to/MyFile.swift", line: 42, column: 10
```

### getOccurrences

Given a USR, returns every location where that symbol is defined, referenced, or called. Supports role filtering (`definition`, `reference`, `call`, etc.).

```
usr: "s:13MyApp0A14ViewControllerC"
```

### relatedOccurrences

Finds structural relationships: protocol conformances, method overrides, type extensions. Essential before refactoring a protocol or base class.

```
usr: "s:13MyApp0A8ProtocolP"
```

### symbolsInFile

Returns a structural outline of all symbols defined in a file — names, kinds, USRs, and line numbers.

```
file: "/path/to/MyFile.swift"
```

### refreshIndex

Polls for index changes after a build. Call this when query results may be stale.

## Typical agent workflow

```
loadIndex(workspacePath: "/path/to/MyApp.xcworkspace")
  → "Index loaded"

searchSymbol(name: "AppDelegate")
  → [{ usr: "s:5MyApp0A8DelegateC", kind: "class", location: "AppDelegate.swift:3" }]

getOccurrences(usr: "s:5MyApp0A8DelegateC", roles: ["reference"])
  → [{ file: "main.swift", line: 12, role: "reference" }, ...]

symbolsInFile(file: "/path/to/AppDelegate.swift")
  → [{ name: "AppDelegate", kind: "class", line: 3 },
     { name: "application(_:didFinishLaunchingWithOptions:)", kind: "instanceMethod", line: 5 }, ...]
```

## How it works

When Xcode builds a project, the compiler writes symbol index data to `DerivedData/Index.noindex/DataStore`. IndexStoreMCP reads this data through IndexStoreDB and exposes it over the [Model Context Protocol](https://modelcontextprotocol.io) via stdio transport.

The server discovers DerivedData automatically by checking:
1. Custom DerivedData location from Xcode preferences
2. A `DerivedData` folder next to the workspace (relative mode)
3. The default `~/Library/Developer/Xcode/DerivedData`

System framework symbols (UIKit, Foundation, etc.) are filtered out by default. Pass `includeSystem: true` to any tool to include them.

## Testing

See [TESTING.md](TESTING.md).

## License

IndexStoreMCP is released under the MIT License. See [LICENSE](LICENSE) for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hpatel-lincoln](https://github.com/hpatel-lincoln)
- **Source:** [hpatel-lincoln/swift-index-store-mcp](https://github.com/hpatel-lincoln/swift-index-store-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hpatel-lincoln-swift-index-store-mcp
- Seller: https://agentstack.voostack.com/s/hpatel-lincoln
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.