Repo Graph

by James-Chahwan

411 downloads

Not rated

GitHub

About

Structural graph memory for AI coding assistants. repo-graph maps your codebase entities, relationships, and feature flows so the model navigates to the right files instead of reading everything first. Tree-sitter, 20+ languages, frontend to backend and more, any MCP client.

Details

Author: James-Chahwan
Downloads: 411
Categories: Productivity, AI, Developer Tools

- Builds a structural graph of codebase entities and connections
- Supports 20+ languages and frameworks
- Provides 11 query tools (flow, trace, impact, neighbors, etc.)
- Reduces token usage and files read during AI reasoning
- Fast scanning with Rust + tree-sitter engine
- Generates ASCII graph views for navigation

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Repo Graph

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

From the repository

Install and run with uvx mcp-repo-graph --repo . (zero-install via uvx). Add it to any MCP client (Claude Code, Cursor, Windsurf, Codex, Gemini CLI, etc.) by configuring the MCP server with the same command.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "repo graph": {
            "repo-graph": {
                "command": "uvx",
                "args": [
                    "mcp-repo-graph",
                    "--repo",
                    "."
                ]
            }
        }
    }
}

McpServers

{
    "repo-graph": {
        "command": "uvx",
        "args": [
            "mcp-repo-graph",
            "--repo",
            "."
        ]
    }
}

Structural graph memory for AI coding assistants.Map your codebase. Navigate by structure. Read only what matters.

repo-graph gives LLMs a map of your codebase — entities, relationships, and flows — so they can navigate to the right files without reading everything first.

Instead 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.

It pays off most where that's hardest to do by hand:large repos, monorepos that span several languages, and multi-service systemswhere a feature's path crosses files, stacks, and service boundaries. On a small single-language project a model can just read the files — seeWhere it fits bestfor the honest sweet spot.

Or one command in your terminal wires up every agent you have:uvx mcp-repo-graph install(see Install).

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Same bug, same model, same prompt — the only difference is whether repo-graph is installed.

The task:fix a reversed comparison operator in a Go + Angular monorepo (566 nodes, 620 edges).

2.5x fewer tokens. ~9x faster. Same correct fix.

Both runs used identical conditions to keep the comparison fair:

- Same model: Claude Opus, 100% (no Haiku routing)
- 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."
- Fresh context: each run started from/clearwith no prior conversation
- 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
- No hints: the prompt describes the symptom, not the location — Claude has to findgroup_controller.go:57on its own

Without repo-graph, Claude greps for keywords, reads files, greps again, reads more files, and eventually narrows down to the bug. With repo-graph, Claude callstrace("groups"), gets back the exact handler function and file, reads it, and fixes it.

Browse pre-generated examplesfor FastAPI,Gin,Hono, and NestJS— real graph output you can inspect without installing anything.

LLMs working on code waste most of their context on orientation:

- Reading files that turn out to be irrelevant
- Missing connections between components in different languages
- Not knowing where a feature starts or what it touches
- Loading 50 files when 5 would do

This is expensive, slow, and gets worse as codebases grow.

repo-graph scans your codebase once and builds a graph of:

- Entities: modules, packages, classes, functions, routes, services, components
- Relationships: imports, calls, handles, defines, contains, cross-stack HTTP
- Flows: end-to-end paths from entry point to data layer

Then it exposes 6 MCP tools that let the LLM:
- Orient— "What languages are in this repo? What are the main features? Where is the graph blind?"
- Navigate— "Trace the login flow from route to database" / "What's the shortest path between UserService and the payments API?"
- Scope— "Which nodes matter for this bug?" / "Give me just the files I need for this fix"
- Assess— "What's the blast radius of changing this function?" / "What here is dead code?"

The LLM gets structural context in a few hundred tokens instead of reading thousands of lines.

repo-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:

- Size— enough files that reading the relevant ones blows the context budget.
- Complexity— rules, indirection, and layers, so "just read it" stops working.
- Cross-boundary reach— the answer spans files, languages, or services that a text search can't link.

- 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--repoat the monorepo root and a single graph spans every project.(The demo above is exactly this: Go + Angular in one repo.)
- Multi-service / polyrepo systems— drop the services under one directory and point--repoat it; the graph traces a feature across service boundaries in one call.
- Large single codebases— thousands of files where orientation itself is the cost.
- Unfamiliar or legacy code— where you don't yet know what touches what.

Where itdoesn'tpull its weight: asmall, 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 costmore. The token win shows up only when it heads off a grep-read-grep spiral (like the demo above). What it reliably buys you iscorrect, complete, cross-boundary answers in a few callson code too big or too interconnected to fit in context — yours or the model's. (Don't want the MCP layer at all?Skip itand call the engine directly.)

The 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, withnone of the per-turn MCP cost:

import repo_graph_py as rg g = rg.generate(".") # or rg.load_from_gmap(rg.default_gmap_dir(".")) print(g.blast_radius("checkout", "both")) # ranked, located, live-filtered — JSON print(g.cross_stack_trace("notifications")) # feature path across the stack, mechanism-labelled print(g.resolve(open("error.log").read())) # stacktrace / test / diff → the nodes that matter print(g.coverage()) # where extraction is partial (grep those)

Same graph, same answers — just without the tool schemas in your context. It's the same Rust engine (glia) the MCP server wraps;repo-graph-pyis its published wheel. Good for CI checks, batch analysis, or wiring the graph into your own agent.

Cross-cutting extractors (work across all languages):

- Data sources— DB/cache/queue/blob/search/email client detection
- CLI entrypoints— Python click, JS commander/yargs, Go cobra, Rust clap
- gRPC— service/method definitions from.protofiles
- Queue consumers— Celery, Dramatiq, BullMQ, Sidekiq, Oban, NATS
- Cross-stack HTTP— frontendfetch/axioscalls linked to backend routes

Multiple languages can match one repo (e.g., Go backend + Angular frontend + SCSS). Each contributes its nodes and edges into a single unified graph.

This detects the AI coding agents you have installed (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI, opencode, Kiro), writes each one's MCP config, and adds a short usage block to its instructions file so the agent reaches for the graph before it greps. Where the agent supports it, it also grants auto-allow so repo-graph tools don't prompt on every call.

It's safe to re-run, anduvx mcp-repo-graph uninstallreverses everything (config, instructions, permissions) while leaving your graph data in place.

uvx mcp-repo-graph install --agents all # every supported agent, not just detected uvx mcp-repo-graph install --scope user # your global config, not this project uvx mcp-repo-graph install --dry-run # show what it would write, change nothing uvx mcp-repo-graph install --yes # no prompt (scripts and CI) uvx mcp-repo-graph install --print-config cursor # print one agent's config, write nothing

If you'd rather wire it up yourself, the package nameisthe run command.uvx mcp-repo-graphjust works. No priorpip install, nothing to keep onPATH. This is the same command VS Code, Cursor, and the MCP registry use under the hood.

Requirements:Python 3.11+, and uvif you use theuvxpath. Prebuilt wheels ship for the Rust engine on Linux (x86_64, aarch64), macOS (Intel + Apple Silicon), and Windows (x86_64) — no Rust toolchain needed.

claude mcp add repo-graph -- uvx mcp-repo-graph --repo .

(--repo .points the graph at the current project; use an absolute path to pin it.)

One command — adds the server to your user config:

code --add-mcp '{"name":"repo-graph","command":"uvx","args":["mcp-repo-graph","--repo","${workspaceFolder}"]}'

Or clickInstallon theMCP galleryentry, or add it to.vscode/mcp.jsonmanually (see below).

Add this to your client's MCP config (.mcp.json,.cursor/mcp.json,.vscode/mcp.json, or~/.claude.json):

{ "mcpServers": { "repo-graph": { "command": "uvx", "args": ["mcp-repo-graph", "--repo", "/path/to/your/project"] } } }

Prefer a persistent install?pip install mcp-repo-graph(oruv tool install mcp-repo-graph) puts amcp-repo-graph/repo-graphcommand on yourPATH; then use"command": "mcp-repo-graph"in the config above.

--repoalso accepts a git URL.Point it at any public repo without cloning first — it shallow-clones and maps it (requiresgit):

uvx mcp-repo-graph --repo https://github.com/org/repo

1. Initialise the target repo (optional)

uvx --from mcp-repo-graph repo-graph-init --repo /path/to/your/project # or, if installed: repo-graph-init --repo /path/to/your/project

This generates the graph, writes.mcp.jsonand CLAUDE.md instructions, and gets your AI assistant ready to use repo-graph. If you used the one-liners above, you can skip this — the server builds the graph on first connect.

The AI assistant now has access to all 6 tools. Example queries it can answer:

- "What does this codebase do?"→orienttool
- "Trace the checkout flow"→tracetool
- "What would break if I change UserService?"→impacttool
- "Which nodes are relevant to this bug?"/"Here's a stacktrace — where do I look?"→findtool
- "Show me that function's source"→readtool
- "Give me the full graph context cheaply"→orient full=true
- "Rebuild after a big refactor"→refreshtool

The graph stays current on its own. While the server is running it watches the repo and does an incremental rebuild a moment after you save, so a structural question right after an edit reflects the change with no manualrefresh. On top of that, the graph refreshes on cold start whenever the source tree changed since the cached.gmapwas written, so it's never stale when your assistant connects.

The watcher is on by default. SetREPO_GRAPH_WATCH=0to disable it (the cold-start refresh still applies). It needs thewatchdogpackage, which ships as a dependency.

Want the cache pre-built and committed so teammates and CI get it too? Add the pre-commit hook automatically:

uvx mcp-repo-graph install --agents none --git-hook

That installs a marker-fencedpre-commithook that refreshes the graph and stages.ai/repo-graph/on every commit.uvx mcp-repo-graph uninstallremoves it again.

Tip:If you don't want graph data in version control, add.ai/repo-graph/to.gitignoreand skip the hook — the watcher and cold-start refresh keep it fresh locally.

repo-graph exposes6 tools— one natural verb each, backed by a Rust engine primitive.

Most tools also take abudget(max chars) so a result fits a small-model context window.

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.

mcp-repo-graphis a thin Python MCP server that wrapsglia, a Rust engine.
- Parse— per-language tree-sitter parsers extract raw nodes and unresolved references
- Extract— cross-cutting extractors layer on HTTP routes, data sources, CLI entrypoints, gRPC services, queue consumers
- Resolve— graph builder resolves intra-repo references; cross-graph resolvers link stacks (frontend HTTP calls → backend routes, etc.)
- Store— merged graph lands in.ai/repo-graph/as a zero-copy.gmap(rkyv + mmap) plus JSON projections for portability
- Serve— the MCP server loads the graph into memory and exposes the 6 tools

The Rust engine lives in its owngliarepo;mcp-repo-graphis the MCP-facing thin wrapper.

If auto-detection misses a weird layout, drop.ai/repo-graph/config.yamlin the target repo:

skip: - legacy # directory basenames excluded from the walk - scratch roots: # explicit roots heuristics miss — added on top of auto-detection - path: apps/weird-layout kind: python - path: services/custom kind: go

kindvalues:go,rust,python,typescript,react,vue,angular,java,scala,clojure,csharp,ruby,php,swift,c_cpp,dart,elixir,solidity,terraform.config.jsonworks too if you prefer.

Generated files live in.ai/repo-graph/inside the target repo:

- nodes.json—[{id, type, name, file_path, confidence, ...}, ...]
- edges.json—[{from, to, type}, ...]
- flows/.yaml— named feature flows with ordered step sequences andkind(http/page/cli/grpc/queue)
- state.md— human-readable snapshot for quick orientation

Common edge types:imports,defines,contains,uses,calls,handles,handled_by,exports,includes,tests, cross-stack HTTP links.

repo-graph runs on your machine and is built to keep your code there. Full text:PRIVACY.md.

- Telemetry / analytics:None. No tracking, no update checks, no phone-home.
- Data collection & sharing:None. Your source code and graph data are never sent to repo-graph, its author, or any third party.
- 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.
- Network access — only two cases, both user-initiated:
- Installation—uvx/pipdownloads the package and its prebuilt engine wheel from PyPI.
- Git-URL targets*— if you pass a git URL to--repo, repo-graph runsgit cloneagainst the URLyouspecified; nothing is sent to repo-graph or its author. A local--repopath (the default) makes zero network calls.

If repo-graph saved you time, consider buying me a coffee.

Persistent memory for any AI assistant. Zero token cost until recall. Stores memories in local SQLite, ranks by 6-factor scoring, returns results 79% smaller than JSON. Works with Claude, ChatGPT, Grok, Cursor, Windsurf, and any MCP client.

An MCP server which brings Jotform to your AI client or LLM

After Effects MCP is a full-featured automation bridge that connects AI clients (like VS Code, Claude Desktop, and Claude Code) to Adobe After Effects through MCP, enabling scripted control of compositions, layers, effects, keyframes/graph easing, presets, markers, audio levels, waveform analysis, and effect discovery via a live bridge panel.

Project management your AI can actually run — connect Claude, ChatGPT, Cursor & Codex to one board over MCP.

Compare LLM cost & latency on one prompt, translate PDF keeping layout, cited research, make PPTX

AIOProductOS spine over MCP — customers, revenue, feedback, work, analytics on one typed record.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

1. Initialise the target repo (optional)

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7