MCP Server

MCP Server

Cartograph exposes all five queries as Model Context Protocol tools over stdio. Any MCP-compatible client — Claude Code, Codex, opencode — can call them without loading the codebase into context.

---

Setup for Claude Code

Step 1 — Index your repository (run once, re-run to refresh):

cartograph --repo /path/to/your/repo index

Step 2 — Add to your MCP config.

For a project-scoped setup, create or edit .claude/mcp_servers.json in your project root:

{
  "mcpServers": {
    "cartograph": {
      "command": "/path/to/cartograph/target/release/cartograph",
      "args": [
        "--repo", "/path/to/your/repo",
        "--db", "/path/to/your/repo/.cartograph/db.sqlite",
        "serve"
      ]
    }
  }
}

Or using cargo run (slower startup, good during development):

{
  "mcpServers": {
    "cartograph": {
      "command": "cargo",
      "args": [
        "run", "--release",
        "--manifest-path", "/path/to/cartograph/Cargo.toml",
        "--",
        "--repo", "/path/to/your/repo",
        "--db", "/path/to/your/repo/.cartograph/db.sqlite",
        "serve"
      ]
    }
  }
}

For a global setup, use ~/.claude/mcp_servers.json with the same format.

Step 3 — Verify. Restart Claude Code. The tools should appear in the tool list. You can ask Claude: "Use cartograph_hotspots to show me the most connected files".

---

Setup for Emberloom Sparks

If you're running Emberloom Sparks, add Cartograph to the MCP registry in config.toml:

[[mcp.servers]]
name    = "cartograph"
command = "/path/to/cartograph/target/release/cartograph"
args    = ["--repo", "/path/to/your/repo", "--db", "/path/to/your/repo/.cartograph/db.sqlite", "serve"]

Sparks agents can then call mcp:cartograph:cartograph_blast_radius, etc. before making changes to understand impact.

---

Tools

cartograph_blast_radius

Show all entities affected by changes to the given entity, by traversing the dependency graph outward.

Input:

Parameter	Type	Required	Default	Description
entity	string	yes	—	File path or entity name (e.g. src/store/graph.rs)
depth	integer	no	3	Max traversal depth (capped at 10)

Example call:

{
  "name": "cartograph_blast_radius",
  "arguments": {
    "entity": "src/store/graph.rs",
    "depth": 4
  }
}

Example output:

ENTITY                                   DEPTH      EDGE
------------------------------------------------------------
src/query/blast_radius.rs                1          imports
src/query/hotspots.rs                    1          imports
src/main.rs                              2          imports
src/lib.rs                               2          imports

---

cartograph_dependencies

Show direct dependencies of an entity (one hop, upstream or downstream).

Input:

Parameter	Type	Required	Default	Description
entity	string	yes	—	File path or entity name
direction	string	no	"downstream"	"downstream" = what this depends on; "upstream" = what depends on this

Example call:

{
  "name": "cartograph_dependencies",
  "arguments": {
    "entity": "src/lib.rs",
    "direction": "upstream"
  }
}

Example output:

ENTITY                                   KIND
--------------------------------------------------
src/main.rs                              File

---

cartograph_co_changes

Show files that historically co-change with the given entity. Results are sorted by confidence, highest first.

Input:

Parameter	Type	Required	Default	Description
entity	string	yes	—	File path or entity name

Example call:

{
  "name": "cartograph_co_changes",
  "arguments": {
    "entity": "src/store/schema.rs"
  }
}

Example output:

ENTITY                                   CONFIDENCE
-------------------------------------------------------
src/store/graph.rs                       1.00
src/query/blast_radius.rs                0.62
src/historian/cochange.rs                0.50

Confidence 1.0 = the most frequently co-changed pair in the repo. Useful for identifying implicit coupling not captured in the import graph.

---

cartograph_who_owns

Show code ownership for an entity based on git blame. Useful for routing reviews or knowing who to ask about a change.

Input:

Parameter	Type	Required	Default	Description
entity	string	yes	—	File path or entity name

Example call:

{
  "name": "cartograph_who_owns",
  "arguments": {
    "entity": "src/historian/commits.rs"
  }
}

Example output:

OWNER                          CONFIDENCE
---------------------------------------------
alice@example.com              1.00
bob@example.com                0.45

---

cartograph_hotspots

Show the most highly-connected files in the codebase — highest combined in-degree + out-degree in the dependency graph. Good for understanding which files are highest-risk to change.

Input:

Parameter	Type	Required	Default	Description
limit	integer	no	20	Number of results (capped at 500)

Example call:

{
  "name": "cartograph_hotspots",
  "arguments": {
    "limit": 10
  }
}

Example output:

ENTITY                                   CONNECTIONS
-------------------------------------------------------
src/store/graph.rs                       24
src/lib.rs                               18
src/main.rs                              14
src/query/mod.rs                         11

---

Input validation

The server applies these checks before executing any tool:

• entity must be provided and non-empty
• entity must be ≤ 1024 characters
• entity must not contain .. (path traversal blocked)
• depth is capped at 10
• limit is capped at 500

Invalid inputs return an error string rather than crashing the server.

---

Transport

Cartograph uses stdio transport — the same process that receives MCP frames on stdin sends responses on stdout. Logs go to stderr only. This is the production-ready transport supported by Claude Code, Codex, and opencode.

SSE and WebSocket transports are not currently supported.