{
  "markdown": "# repo-graph\n\n[![repo-graph MCP server](https://glama.ai/mcp/servers/James-Chahwan/repo-graph/badges/card.svg)](https://glama.ai/mcp/servers/James-Chahwan/repo-graph)\n\n**Structural graph memory for AI coding assistants.** Map your codebase. Navigate by structure. Read only what matters.\n\nrepo-graph gives LLMs a map of your codebase — entities, relationships, and flows — so they can navigate to the right files without reading everything first.\n\nInstead of flooding an LLM's context window with your entire codebase (or hoping it guesses right), repo-graph builds a lightweight graph of what exists, how things connect, and where the entry points are. The LLM queries the graph, finds the minimal set of files it needs, and reads only those.\n\nIt pays off most where that's hardest to do by hand: **large repos, monorepos that span several languages, and multi-service systems** where a feature's path crosses files, stacks, and service boundaries. On a small single-language project a model can just read the files — see [Where it fits best](#where-it-fits-best) for the honest sweet spot.\n\n**Install in one click:**\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=repo-graph&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-repo-graph%22%2C%22--repo%22%2C%22.%22%5D%7D)\n[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=repo-graph&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-repo-graph%22%2C%22--repo%22%2C%22.%22%5D%7D&quality=insiders)\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=repo-graph&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtY3AtcmVwby1ncmFwaCIsIi0tcmVwbyIsIi4iXX0%3D)\n\nOr one command in your terminal wires up every agent you have: `uvx mcp-repo-graph install` (see [Install](#install)).\n\n## Demo\n\nhttps://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a\n\nhttps://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883\n\nSame bug, same model, same prompt — the only difference is whether repo-graph is installed.\n\n**The task:** fix a reversed comparison operator in a Go + Angular monorepo (566 nodes, 620 edges).\n\n| | Without repo-graph | With repo-graph |\n|---|---|---|\n| **Tokens used** | 75,308 | 29,838 |\n| **Time to fix** | 4m 36s | ~30s |\n| **Files explored** | ~15 (grep, read, grep, read...) | 2 (trace lookup + handler file) |\n| **Outcome** | Found and fixed the bug | Found and fixed the bug |\n\n**2.5x fewer tokens. ~9x faster. Same correct fix.**\n\n### How the test was run\n\nBoth runs used identical conditions to keep the comparison fair:\n\n- **Same model**: Claude Opus, 100% (no Haiku routing)\n- **Same prompt**: *\"Groups that were created recently are showing as closed, and old groups show as open. This is backwards — new groups should be open for members to join. Find and fix the bug.\"*\n- **Fresh context**: each run started from `/clear` with no prior conversation\n- **No other tools**: CLAUDE.md, plugins, hooks, and all other MCP servers were removed for both runs — the only variable was whether repo-graph was installed\n- **No hints**: the prompt describes the symptom, not the location — Claude has to find `group_controller.go:57` on its own\n\nWithout repo-graph, Claude greps for keywords, reads files, greps again, reads more files, and eventually narrows down to the bug. With repo-graph, Claude calls `trace(\"groups\")`, gets back the exact handler function and file, reads it, and fixes it.\n\n> Browse [pre-generated examples](examples/) for [FastAPI](examples/fastapi/), [Gin](examples/gin/), [Hono](examples/hono/), and [NestJS](examples/nestjs/) — real graph output you can inspect without installing anything.\n\n## The problem\n\nLLMs working on code waste most of their context on orientation:\n\n- Reading files that turn out to be irrelevant\n- Missing connections between components in different languages\n- Not knowing where a feature starts or what it touches\n- Loading 50 files when 5 would do\n\nThis is expensive, slow, and gets worse as codebases grow.\n\n## How repo-graph solves it\n\nrepo-graph scans your codebase once and builds a graph of:\n\n- **Entities**: modules, packages, classes, functions, routes, services, components\n- **Relationships**: imports, calls, handles, defines, contains, cross-stack HTTP\n- **Flows**: end-to-end paths from entry point to data layer\n\nThen it exposes 6 MCP tools that let the LLM:\n\n1. **Orient** — \"What languages are in this repo? What are the main features? Where is the graph blind?\"\n2. **Navigate** — \"Trace the login flow from route to database\" / \"What's the shortest path between UserService and the payments API?\"\n3. **Scope** — \"Which nodes matter for this bug?\" / \"Give me just the files I need for this fix\"\n4. **Assess** — \"What's the blast radius of changing this function?\" / \"What here is dead code?\"\n\nThe LLM gets structural context in a few hundred tokens instead of reading thousands of lines.\n\n## Where it fits best\n\nrepo-graph earns its keep when a codebase is bigger or more tangled than the model can hold in its head at once. The payoff scales with three things:\n\n- **Size** — enough files that reading the relevant ones blows the context budget.\n- **Complexity** — rules, indirection, and layers, so \"just read it\" stops working.\n- **Cross-boundary reach** — the answer spans files, languages, or services that a text search can't link.\n\nStrong fits:\n\n- **Monorepos** — a frontend calling a backend across a language boundary. repo-graph links the HTTP call to the route it hits and the handler behind it — the one thing grep structurally can't do. Point `--repo` at the monorepo root and a single graph spans every project. *(The demo above is exactly this: Go + Angular in one repo.)*\n- **Multi-service / polyrepo systems** — drop the services under one directory and point `--repo` at it; the graph traces a feature across service boundaries in one call.\n- **Large single codebases** — thousands of files where orientation itself is the cost.\n- **Unfamiliar or legacy code** — where you don't yet know what touches what.\n\nWhere it *doesn't* pull its weight: a **small, single-language repo with a clear task**. The model can just read the files — grep wins and the graph is overhead. Don't reach for it to shave tokens, either: the MCP layer is a fixed per-turn cost, so on easy tasks it can cost *more*. The token win shows up only when it heads off a grep-read-grep spiral (like the demo above). What it reliably buys you is **correct, complete, cross-boundary answers in a few calls** on code too big or too interconnected to fit in context — yours or the model's. (Don't want the MCP layer at all? [Skip it](#use-it-without-mcp) and call the engine directly.)\n\n## Use it without MCP\n\nThe MCP server is the zero-config path, but the graph isn't tied to it. The engine ships as a plain Python wheel — `pip install repo-graph-py` — so you can build the graph and call the same answer primitives directly, from a script or your own tooling, with **none of the per-turn MCP cost**:\n\n```python\nimport repo_graph_py as rg\n\ng = rg.generate(\".\")                            # or rg.load_from_gmap(rg.default_gmap_dir(\".\"))\nprint(g.blast_radius(\"checkout\", \"both\"))       # ranked, located, live-filtered — JSON\nprint(g.cross_stack_trace(\"notifications\"))     # feature path across the stack, mechanism-labelled\nprint(g.resolve(open(\"error.log\").read()))      # stacktrace / test / diff → the nodes that matter\nprint(g.coverage())                             # where extraction is partial (grep those)\n```\n\nSame graph, same answers — just without the tool schemas in your context. It's the same Rust engine ([glia](https://github.com/James-Chahwan/glia)) the MCP server wraps; `repo-graph-py` is its published wheel. Good for CI checks, batch analysis, or wiring the graph into your own agent.\n\n## Supported languages\n\n| Language | Detection | What it extracts |\n|----------|-----------|-----------------|\n| **Go** | `go.mod` | Packages, functions, HTTP routes (gin/echo/chi/stdlib), imports |\n| **Rust** | `Cargo.toml` | Crates, modules, structs, traits, functions, routes (Actix/Rocket/Axum) |\n| **TypeScript** | `tsconfig.json` / `package.json` | Modules, classes, functions, import relationships |\n| **React** | `react` in `package.json` | Components, hooks, context providers, React Router routes, fetch/axios calls, flows |\n| **Angular** | `@angular/core` in `package.json` | Components, services, guards, DI injection, HTTP calls, feature flows |\n| **Vue** | `vue` in `package.json` | SFCs, composables, Vue Router routes, fetch/axios calls |\n| **Python** | `pyproject.toml` / `setup.py` / `requirements.txt` | Packages, modules, classes, functions, routes (Flask/FastAPI/Django) |\n| **Java/Kotlin** | `pom.xml` / `build.gradle` | Packages, classes, routes (Spring/JAX-RS/Ktor/WebFlux/Micronaut) |\n| **Scala** | `build.sbt` | Packages, objects/classes/traits, routes (Play/Akka HTTP/http4s) |\n| **Clojure** | `project.clj` / `deps.edn` | Namespaces, defn/defprotocol/defrecord, routes (Compojure/Reitit) |\n| **C#/.NET** | `.csproj` / `.sln` | Namespaces, classes, routes (ASP.NET/Minimal API) |\n| **Ruby** | `Gemfile` / `.gemspec` | Files, classes, modules, Rails routes |\n| **PHP** | `composer.json` | Namespaces, classes, interfaces, routes (Laravel/Symfony) |\n| **Swift** | `Package.swift` / `.xcodeproj` | Files, types (class/struct/enum/protocol/actor), Vapor routes |\n| **C/C++** | `CMakeLists.txt` / `Makefile` / `meson.build` | Sources, headers, classes, structs, enums, namespaces, includes |\n| **Dart/Flutter** | `pubspec.yaml` | Modules, classes, widgets, go_router/shelf routes |\n| **Elixir/Phoenix** | `mix.exs` | Modules, functions, Phoenix router scopes + routes |\n| **Solidity** | `.sol` files / `foundry.toml` / `hardhat.config.*` | Contracts, interfaces, libraries, events, inheritance |\n| **Terraform** | `.tf` files | Modules, resources, variables, outputs, module sources |\n| **SCSS** | `.scss` files present | File-level bloat analysis |\n\nCross-cutting extractors (work across all languages):\n\n- **Data sources** — DB/cache/queue/blob/search/email client detection\n- **CLI entrypoints** — Python click, JS commander/yargs, Go cobra, Rust clap\n- **gRPC** — service/method definitions from `.proto` files\n- **Queue consumers** — Celery, Dramatiq, BullMQ, Sidekiq, Oban, NATS\n- **Cross-stack HTTP** — frontend `fetch`/`axios` calls linked to backend routes\n\nMultiple languages can match one repo (e.g., Go backend + Angular frontend + SCSS). Each contributes its nodes and edges into a single unified graph.\n\n## Install\n\n### One command\n\n```bash\nuvx mcp-repo-graph install\n```\n\nThis detects the AI coding agents you have installed (Claude Code, Claude Desktop,\nCursor, Windsurf, VS Code, Codex, Gemini CLI, opencode, Kiro), writes each one's\nMCP config, and adds a short usage block to its instructions file so the agent\nreaches for the graph before it greps. Where the agent supports it, it also grants\nauto-allow so repo-graph tools don't prompt on every call.\n\nIt's safe to re-run, and `uvx mcp-repo-graph uninstall` reverses everything\n(config, instructions, permissions) while leaving your graph data in place.\n\n```bash\nuvx mcp-repo-graph install --agents all          # every supported agent, not just detected\nuvx mcp-repo-graph install --scope user          # your global config, not this project\nuvx mcp-repo-graph install --dry-run             # show what it would write, change nothing\nuvx mcp-repo-graph install --yes                 # no prompt (scripts and CI)\nuvx mcp-repo-graph install --print-config cursor # print one agent's config, write nothing\n```\n\n### Manual, per client\n\nIf you'd rather wire it up yourself, the package name **is** the run command.\n`uvx mcp-repo-graph` just works. No prior `pip install`, nothing to keep on\n`PATH`. This is the same command VS Code, Cursor, and the MCP registry use under\nthe hood.\n\n**Requirements:** Python 3.11+, and [`uv`](https://docs.astral.sh/uv/) if you use the\n`uvx` path. Prebuilt wheels ship for the Rust engine on Linux (x86_64, aarch64),\nmacOS (Intel + Apple Silicon), and Windows (x86_64) — no Rust toolchain needed.\n\n### Claude Code\n\n```bash\nclaude mcp add repo-graph -- uvx mcp-repo-graph --repo .\n```\n\n(`--repo .` points the graph at the current project; use an absolute path to pin it.)\n\n### VS Code\n\nOne command — adds the server to your user config:\n\n```bash\ncode --add-mcp '{\"name\":\"repo-graph\",\"command\":\"uvx\",\"args\":[\"mcp-repo-graph\",\"--repo\",\"${workspaceFolder}\"]}'\n```\n\nOr click **Install** on the [MCP gallery](https://code.visualstudio.com/mcp) entry,\nor add it to `.vscode/mcp.json` manually (see below).\n\n### Cursor / any MCP client — manual config\n\nAdd this to your client's MCP config (`.mcp.json`, `.cursor/mcp.json`,\n`.vscode/mcp.json`, or `~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"repo-graph\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-repo-graph\", \"--repo\", \"/path/to/your/project\"]\n    }\n  }\n}\n```\n\nPrefer a persistent install? `pip install mcp-repo-graph` (or `uv tool install\nmcp-repo-graph`) puts a `mcp-repo-graph` / `repo-graph` command on your `PATH`; then\nuse `\"command\": \"mcp-repo-graph\"` in the config above.\n\n**`--repo` also accepts a git URL.** Point it at any public repo without cloning\nfirst — it shallow-clones and maps it (requires `git`):\n\n```bash\nuvx mcp-repo-graph --repo https://github.com/org/repo\n```\n\n## Quick start\n\n### 1. Initialise the target repo (optional)\n\n```bash\nuvx --from mcp-repo-graph repo-graph-init --repo /path/to/your/project\n# or, if installed:  repo-graph-init --repo /path/to/your/project\n```\n\nThis generates the graph, writes `.mcp.json` and CLAUDE.md instructions, and gets your\nAI assistant ready to use repo-graph. If you used the one-liners above, you can skip\nthis — the server builds the graph on first connect.\n\n### 2. Use it\n\nThe AI assistant now has access to all 6 tools. Example queries it can answer:\n\n- *\"What does this codebase do?\"* → `orient` tool\n- *\"Trace the checkout flow\"* → `trace` tool\n- *\"What would break if I change UserService?\"* → `impact` tool\n- *\"Which nodes are relevant to this bug?\"* / *\"Here's a stacktrace — where do I look?\"* → `find` tool\n- *\"Show me that function's source\"* → `read` tool\n- *\"Give me the full graph context cheaply\"* → `orient full=true`\n- *\"Rebuild after a big refactor\"* → `refresh` tool\n\n### 3. Freshness (automatic)\n\nThe graph stays current on its own. While the server is running it watches the repo\nand does an incremental rebuild a moment after you save, so a structural question\nright after an edit reflects the change with no manual `refresh`. On top of that, the\ngraph refreshes on cold start whenever the source tree changed since the cached\n`.gmap` was written, so it's never stale when your assistant connects.\n\nThe watcher is on by default. Set `REPO_GRAPH_WATCH=0` to disable it (the cold-start\nrefresh still applies). It needs the `watchdog` package, which ships as a dependency.\n\nWant the cache pre-built and committed so teammates and CI get it too? Add the\npre-commit hook automatically:\n\n```bash\nuvx mcp-repo-graph install --agents none --git-hook\n```\n\nThat installs a marker-fenced `pre-commit` hook that refreshes the graph and stages\n`.ai/repo-graph/` on every commit. `uvx mcp-repo-graph uninstall` removes it again.\n\n> **Tip:** If you don't want graph data in version control, add `.ai/repo-graph/` to `.gitignore` and skip the hook — the watcher and cold-start refresh keep it fresh locally.\n\n## MCP tools reference\n\nrepo-graph exposes **6 tools** — one natural verb each, backed by a Rust engine primitive.\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `orient` | `seed` *(optional)*, `full`, `budget` | The first call on a repo: node/edge counts, detected kinds, entry points, and a **blind-spots** note flagging which languages/edges are under-linked (so you grep those deliberately). `seed=<node>` → scoped map; `full=true` → whole-repo dense map |\n| `find` | `query`, `expand`, `kind`, `top_k`, `budget` | Turn any text into the ranked nodes that matter — a symbol/keyword, or a pasted stacktrace / failing-test id / diff (resolved to the code it implicates). `expand=true` fans out to the surrounding neighbourhood. Every row carries `path:line` |\n| `impact` | `nodes` *(comma-separated)*, `direction`, `depth`, `live_only`, `top_k`, `budget` | Blast radius: what a change affects (`forward`) or depends on / is used by (`backward`), as a ranked, located closure — each row with the edge `via` reason and a `⊘` when the engine finds it unreachable (likely dead). Pass several nodes for a whole-diff radius |\n| `trace` | `from_node`, `to_node` *(optional)*, `depth`, `budget` | One arg: a feature end-to-end across the stack, each hop labelled with its mechanism (call / HTTP / queue / event) and cross-service hops marked. Two args: the shortest path between two nodes |\n| `read` | `node` *(comma-separated)*, `context_lines`, `budget` | A node's exact source, sliced from its file by the graph's line span, plus a `context:` footer (HTTP method, cross-stack callers, covering tests, governing docs). Comma-separate to batch-read a ranked set |\n| `refresh` | `repo_path` *(optional)*, `full` | Rebuild the graph (incremental by default — only changed files re-parse). `repo_path` retargets a different path or git URL; `full=true` forces a clean reparse. Routine edits are auto-picked-up by the file watcher |\n\nMost tools also take a `budget` (max chars) so a result fits a small-model context window.\n\n> These 6 collapsed from an earlier 13 once the engine (v0.4.18) grew answer-shaped primitives — `blast_radius`, `cross_stack_trace`, `resolve`, `coverage` — that return complete, ranked, located, live-filtered results in one call. Fewer tools = less fixed per-turn overhead and less agent confusion.\n\n## How it works\n\n`mcp-repo-graph` is a thin Python MCP server that wraps **glia**, a Rust engine.\n\n1. **Parse** — per-language tree-sitter parsers extract raw nodes and unresolved references\n2. **Extract** — cross-cutting extractors layer on HTTP routes, data sources, CLI entrypoints, gRPC services, queue consumers\n3. **Resolve** — graph builder resolves intra-repo references; cross-graph resolvers link stacks (frontend HTTP calls → backend routes, etc.)\n4. **Store** — merged graph lands in `.ai/repo-graph/` as a zero-copy `.gmap` (rkyv + mmap) plus JSON projections for portability\n5. **Serve** — the MCP server loads the graph into memory and exposes the 6 tools\n\nThe Rust engine lives in its own [`glia`](https://github.com/James-Chahwan/glia) repo; `mcp-repo-graph` is the MCP-facing thin wrapper.\n\n## Config (optional escape hatch)\n\nIf auto-detection misses a weird layout, drop `.ai/repo-graph/config.yaml` in the target repo:\n\n```yaml\nskip:\n  - legacy       # directory basenames excluded from the walk\n  - scratch\n\nroots:           # explicit roots heuristics miss — added on top of auto-detection\n  - path: apps/weird-layout\n    kind: python\n  - path: services/custom\n    kind: go\n```\n\n`kind` values: `go`, `rust`, `python`, `typescript`, `react`, `vue`, `angular`, `java`, `scala`, `clojure`, `csharp`, `ruby`, `php`, `swift`, `c_cpp`, `dart`, `elixir`, `solidity`, `terraform`. `config.json` works too if you prefer.\n\n## Graph data format\n\nGenerated files live in `.ai/repo-graph/` inside the target repo:\n\n- **`nodes.json`** — `[{id, type, name, file_path, confidence, ...}, ...]`\n- **`edges.json`** — `[{from, to, type}, ...]`\n- **`flows/*.yaml`** — named feature flows with ordered step sequences and `kind` (`http`/`page`/`cli`/`grpc`/`queue`)\n- **`state.md`** — human-readable snapshot for quick orientation\n\nCommon edge types: `imports`, `defines`, `contains`, `uses`, `calls`, `handles`, `handled_by`, `exports`, `includes`, `tests`, cross-stack HTTP links.\n\n## Privacy Policy\n\nrepo-graph runs on your machine and is built to keep your code there. Full text: [PRIVACY.md](PRIVACY.md).\n\n- **Telemetry / analytics:** None. No tracking, no update checks, no phone-home.\n- **Data collection & sharing:** None. Your source code and graph data are never sent to repo-graph, its author, or any third party.\n- **Local processing & storage:** Scanning and graph-building happen locally; the graph is cached in your project's `.ai/repo-graph/` directory and stays on your device.\n- **Network access — only two cases, both user-initiated:**\n  1. *Installation* — `uvx`/`pip` downloads the package and its prebuilt engine wheel from PyPI.\n  2. *Git-URL targets* — if you pass a git URL to `--repo`, repo-graph runs `git clone` against the URL **you** specified; nothing is sent to repo-graph or its author. A local `--repo` path (the default) makes zero network calls.\n- **Data retention:** The local cache persists until you delete it — fully under your control.\n- **Contact:** [GitHub issues](https://github.com/James-Chahwan/repo-graph/issues)\n\n## License\n\nMIT\n\n## Support\n\nIf repo-graph saved you time, consider buying me a coffee.\n\n<p align=\"center\">\n  <a href=\"https://buymeacoffee.com/polycrisis\">\n    <img src=\"docs/bmc-qr.png\" alt=\"Buy Me a Coffee\" width=\"200\">\n  </a>\n  <br>\n  <a href=\"https://buymeacoffee.com/polycrisis\">buymeacoffee.com/polycrisis</a>\n</p>\n\n<!-- mcp-name: io.github.James-Chahwan/repo-graph -->\n",
  "bytes": 21553,
  "sha": "a08475bee060ba3d57445af389ab64220a8ab55f92abbff933882da66043d93e",
  "repo_slug": "james-chahwan/repo-graph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_james_chahwan_repo_graph_eb6d153d/readme"
}