codegraph-mcp

An MCP server that indexes a TypeScript/JavaScript codebase into a real call graph and import graph — using TypeScript's own type checker for symbol resolution, not regex or text matching — and exposes it to Claude (or any MCP client) as queryable tools.

Ask Claude things like:

• "What would break if I change queue.ts?"

• "Who calls createUser?"

• "Show me the dependency graph of this module."

Instead of Claude re-reading your whole codebase to answer, it gets a precise, structural answer from a pre-built graph.

No paid APIs, no paid services. Free npm registry / GitHub used only for testing against real-world code (see below).

Why this exists

Code-intelligence tools that build a persistent, queryable graph of a codebase are one of the fastest-moving categories in AI developer tooling right now — this is a scoped-down, honestly-documented version of that idea, built to demonstrate the underlying technique rather than compete with the production tools in that space (see Limitations below).

Related MCP server: ContextCache MCP

How it actually works (the part that matters)

Naive versions of this idea use regex or text matching to find function calls — which breaks constantly (a call inside a comment, a variable that happens to share a name with a function, an imported name that shadows a local one). This project instead uses the real TypeScript compiler API: it builds an actual ts.Program, asks the type checker to resolve every call expression to its true declaration, and only records an edge when that resolution succeeds.

This caught a real, non-obvious bug during development: when an identifier comes from an import { x } from "...", the checker initially returns an alias symbol pointing at the import binding itself, not the original declaration — resolving through that alias (checker.getAliasedSymbol) is what makes cross-file call resolution actually work. Without that step, only same-file calls would ever be found. See src/parser.ts for the fix.

Verified output

On a hand-written 3-file fixture (test/fixtures/sample-project) — full automated test suite, 20/20 passing, including cross-file resolution:

--- Call edges (the hard part: cross-file resolution via the type checker) ---
PASS: handleSignup calls createUser (CROSS-FILE — requires alias resolution)
PASS: main calls handleSignup (CROSS-FILE — requires alias resolution)
PASS: createUser calls hashPassword (same-file)
PASS: Exactly 3 call edges (no false positives)

--- Query engine ---
PASS: findCallers(createUser) returns exactly handleSignup
PASS: impactAnalysis(userService.ts) finds index.ts at depth 2 (TRANSITIVE, not direct)

20 passed, 0 failed

On a real, published open-source library (sindresorhus/p-queue, a well-known ~2,000-star npm package) — indexed live via the actual MCP tool call, not a script:

Indexed 5 file(s): 32 symbol(s), 7 call edge(s), 7 import edge(s).

with a correctly resolved summary — lowerBound (a binary-search helper) shown being called from within PriorityQueue.enqueue, and queue.ts correctly identified as the most depended-on file (3 dependents) — matching p-queue's actual architecture. This also caught a second real bug: p-queue's source uses ESM-style imports with explicit .js extensions (import x from './priority-queue.js') even though the real file on disk is .ts — extremely common in modern TypeScript/NodeNext projects. The resolver now handles that extension swap; see src/parser.ts.

Tools

Setup

git clone https://github.com/SiwarKhalfaoui/codegraph-mcp.git
cd codegraph-mcp
npm install
npm run build

As a standalone CLI (no Claude needed)

node build/cli.js index /path/to/some/project/src
node build/cli.js summary
node build/cli.js find-definition createUser
node build/cli.js impact src/queue.ts
node build/cli.js export-mermaid calls --out call-graph.mmd

Connect it to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/build/mcpServer.js"]
    }
  }
}

Or test directly without Claude Desktop using MCP Inspector:

npx @modelcontextprotocol/inspector node build/mcpServer.js

Development

npm run dev    # run the CLI directly with tsx, no build step
npm test       # full automated test suite against the fixture project

Architecture notes

• src/fileDiscovery.ts — walks the filesystem for source files, skipping node_modules/build output/tests, with cross-platform path normalization

• src/parser.ts — the core: builds a ts.Program, extracts every function/method/class declaration, then resolves every call expression and import specifier via the real type checker

• src/graphStore.ts — persists the graph as JSON, not SQLite. Deliberate tradeoff: a native SQLite binding needs platform-specific compilation (node-gyp), which is exactly the kind of cross-platform friction this project avoids. A repo-sized graph fits comfortably in memory as JSON — SQLite would be the right upgrade for very large monorepos, not for this scope.

• src/queries.ts — builds in-memory indices (by id, by name, adjacency lists) over the loaded graph and answers the actual questions

• src/mermaid.ts — visual export for human inspection

• src/mcpServer.ts — wraps the query engine as MCP tools

• src/cli.ts — same functionality as a standalone command-line tool

Known limitations (stated honestly)

• Single-language scope. TypeScript/JavaScript only — not the 158 languages some production code-intelligence tools support. This is a focused demonstration of the technique, not a general-purpose tool.

• Private class members (#method) aren't tracked yet. TypeScript's private-field syntax uses a different AST node type than regular method names; this project doesn't yet register or resolve calls to them.

• Static analysis only. Dynamic dispatch (calling a function stored in a variable that could point at several different implementations) isn't resolved — only calls the type checker can statically determine.

• JSON storage, not a real database. Fine at single-repo scale; wouldn't scale cleanly to a huge monorepo (see architecture notes above).

Possible extensions

• Support private class members (#foo) as trackable symbols

• Incremental re-indexing (only re-parse changed files) instead of a full rebuild every time

• A small web UI rendering the Mermaid export interactively instead of static text

License

MIT