repo-atlas-mcp

An MCP server that gives coding agents a graph of your codebase instead of a text search over it.

Grep finds a name. It cannot tell you who calls that function, what breaks if you change it, or whether any test reaches it. Those are relationship questions, so repo-atlas-mcp parses your repository with tree-sitter, loads the call and import structure into Neo4j, and exposes it to your agent as MCP tools.

▸ hotspots
  17 callers  stock_analyzer/base.py:54        is_num
  10 callers  stock_analyzer/data/market.py:144  get_row
   9 callers  stock_analyzer/base.py:12        Finding

▸ impact_of is_num
  21 production caller(s) across 11 file(s).
  ⚠ No test reaches this symbol on any call path — changes here are unguarded.

Why a graph

Reachability is transitive, and transitive questions are exactly what a graph database answers in one query and a text search cannot answer at all. impact_of walks every call path upstream of a symbol, partitions the callers into production code and tests, and tells you when nothing guards the change. That is the query that stops an agent from confidently editing shared code.

Requirements

Node.js 18+
A Neo4j instance. AuraDB Free is enough for repositories in the hundreds-of-thousands-of-lines range and costs nothing.

Setup

Create a free AuraDB instance, then note the connection URI and password it gives you.

Add the server to your MCP client:

{
  "mcpServers": {
    "repo-atlas": {
      "command": "npx",
      "args": ["-y", "repo-atlas-mcp"],
      "env": {
        "NEO4J_URI": "neo4j+s://xxxxxxxx.databases.neo4j.io",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

For Claude Code that goes in .mcp.json at your project root, or run:

claude mcp add repo-atlas -- npx -y repo-atlas-mcp

Then ask your agent to index the project once:

index this repo at /path/to/project

Re-indexing is incremental — unchanged files are skipped by content hash, so running it again after a few edits takes about as long as parsing the files you touched.

Tools

Tool	Question it answers
`index_repo`	Build or refresh the graph for a repository
`find_symbol`	Where is this function/class/method defined?
`who_calls`	What reaches this symbol, transitively?
`what_it_calls`	What does this symbol depend on, transitively?
`impact_of`	What breaks if I change this — and do any tests cover it?
`path_between`	How does control flow from A to B?
`hotspots`	Which symbols have the most distinct callers?
`module_map`	What does the top-level package structure depend on?
`list_repos`	What is indexed?
`drop_repo`	Remove a repository from the graph

Languages

Python, TypeScript, TSX, and JavaScript, via tree-sitter WASM grammars — no native compilation, so npx works on a clean machine without build tools.

How call resolution works, and where it is wrong

Resolving a call to a definition properly requires full type inference. This does something cheaper and tells you when it is guessing. What the call looks like decides how it is resolved:

self.foo() / this.foo() — resolves to foo on the enclosing class, else to a definition in the same file. This is the one method form that resolves precisely. Tier: local.

foo() — a bare call, very likely a repo-level function. Resolved against a definition in the same file (local), then in a file this one imports (imported), then repo-wide if three or fewer candidates exist (global).

something.foo() — the receiver's type is unknown. Accepted only when foo is defined exactly once in the whole repository and is not a well-known builtin name. Tier: receiver.

That last rule matters more than it looks. Without it, one repo method named get absorbs every dict.get() and response.get() in the codebase; on a real 26-file project it produced a phantom symbol with 59 callers, ranked as the most-called code in the project. The denylist in COMMON_METHOD_NAMES (get, add, update, join, map, read, …) is a heuristic, and it is consulted only for this weakest case — a bare get() still resolves normally.

Every CALLS edge stores which tier produced it, and the tools surface anything above local.

Known limitations, stated plainly:

Dynamic dispatch is invisible. getattr(obj, name)(), reflection, and dependency-injection wiring produce no edges.
Polymorphism is not modelled. Two classes with a run() method cannot be told apart, so calls on a non-self receiver to a name defined more than once are dropped rather than guessed.
Calls into third-party packages are dropped. Only symbols defined inside the repository become nodes.
Top-level code is attributed to a synthetic <module> symbol per file, so route registration and CLI wiring still appear in the graph rather than being discarded.
Repeated calls between the same pair collapse to one edge, which keeps the last line number seen.

The practical effect: the graph under-reports rather than over-reports. impact_of can miss a caller that goes through dynamic dispatch, so treat its output as a strong lead, not a proof — but a symbol it names really is a caller.

Graph model

(:Repo)-[:HAS_FILE]->(:File)-[:DEFINES]->(:Symbol)
(:File)-[:IMPORTS]->(:File)
(:Symbol)-[:CALLS {line, confidence}]->(:Symbol)

Symbol.isTest is set from the defining file's path, which is what lets impact_of separate covering tests from production callers.

Ranking in hotspots uses caller in-degree rather than PageRank, so it runs on AuraDB Free, which does not include the Graph Data Science library.

Development

npm install
npm run build
node scripts/smoke.mjs                 # parser check, no database needed
node scripts/bulk-parse.mjs /some/repo  # parse a real repo and report totals

License

MIT