cross-repo-graph

A local MCP server that gives coding agents a code graph across all repositories of a project: classes, methods, calls and imports inside each repo, and the links between repos. Those links are HTTP calls from client to endpoint, service addresses from config, and NuGet/npm packages. Every link carries file:line evidence on both sides.

The question it answers best is "who breaks if I change this API?". Grep misses calls whose URL is assembled from config (_settings.HolidayServiceUrl + year) or that go through generated clients. The linker resolves both, and it separates calls that really exist (used) from clients that are only declared (declared-only).

How it works

cross-repo-graph index                       cross-repo-graph serve
  project folder                               stdio (default) or --http <port>
   ├─ repo A ─┐ Graphify (AST, no LLM)          ├─ list_repos
   ├─ repo B ─┤──────────► per-repo graphs      ├─ query_graph / get_node / get_neighbors / shortest_path
   └─ repo C ─┘ cross-repo linker               ├─ dependencies        (between repos, file:line)
                     │                          └─ architecture_hubs   (central classes of a repo)
                     ▼
   .ai/.index/  graph.json · links.json · repos.json      ◄── read by the server, hot-reloaded

• Indexer. It finds every git repo one or two levels below the project folder and skips worktrees/. It runs Graphify on each repo (AST only, .gitignore respected), merges the graphs, then adds cross-repo links. A repo is re-extracted only when its HEAD or uncommitted changes differ from the last run, so an unchanged project re-indexes in about 2 s. Output files are replaced atomically, and a lock stops concurrent runs.

• Server. It is read-only. It loads the graph once and reloads it when graph.json changes, and every answer fits a token budget. It does not read or search file contents: agents already have their own file tools.

• Nothing leaves the machine. No LLM, no network at run time (uv downloads Graphify once).

The linker currently understands ASP.NET Core (C#, F#, minimal API), Angular/TypeScript HTTP clients, ng-openapi-gen, NSwag, Refit, appsettings*.json, environment*.ts and Vite/CRA .env.<environment> files (public prefixes only). For other stacks you still get the per-repo AST graph.

Related MCP server: rpg-encoder

Requirements

• Node.js 22+

• uv on PATH (winget install astral-sh.uv, brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh). The indexer runs Graphify through uvx --from graphifyy==0.9.66. Set CRG_GRAPHIFY to use a graphify executable you already have.

Usage

# in the project folder (the one that contains the repos)
npx -y cross-repo-graph index                 # → .ai/.index/
npx -y cross-repo-graph serve                 # MCP over stdio

# options
cross-repo-graph index --project <dir> --index <dir> [--force] [--hosts hosts.json]
cross-repo-graph serve --index <dir> [--http 3917] [--host 127.0.0.1]

--hosts takes { "timetracking.example.com": "timetracking-api" } entries for services whose host the linker can't attribute on its own.

Claude Code

claude mcp add --scope local code-graph -- npx -y cross-repo-graph serve --index "<project>/.ai/.index"

With the agent-playbook code-graph plugin, the server and a SessionStart re-index hook are set up per project automatically.

Docker / shared instance

serve --http <port> speaks stateless Streamable HTTP on /mcp (plus /healthz). Use it when several sessions or people should share one process, or when the graph is large.

Tools

Development

npm install
npm test          # unit tests (node:test via tsx)
npm run build     # → dist/

License

Apache-2.0. The graph query semantics are ported from Graphify (Apache-2.0); see NOTICE.