# James-Chahwan/repo-graph [Health: Active]

**Category:** 🧬 Biology & Bioinformatics  
**Repository:** https://github.com/James-Chahwan/repo-graph  
**GitHub Stars:** 87  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/james-chahwan-repo-graph

## Description
Structural graph map of any codebase for AI coding assistants. Scans entities, relationships, and feature flows across 13 languages so LLMs navigate by structure instead of grepping through everything.

## Tools
Capabilities this server exposes over MCP:

- **orient** — Get the lay of the land — ALWAYS the first call on a codebase. With no arguments: a counts + entry-points overview plus a `blind spots` note flagging which (language, edge-kind) extractions are partial so you know where to fall back to grep. With `seed=<node>`: the dense structural map scoped to that node's neighbourhood. With `full=true`: the whole-repo dense map (the full context dump). Orient first, then `find` to jump to nodes, `impact` for blast radius, `trace` for flows.
- **find** — Turn any text into the ranked nodes that matter — the on-ramp to the graph. A symbol or keyword returns matching nodes; a pasted stacktrace / failing-test id / diff is resolved to the code it implicates and ranked by relevance. Set `expand=true` to fan out to the surrounding neighbourhood (spreading activation). Every row carries `path:line`, so `read` the top hits directly — no grep.
- **impact** — Blast radius in one call: fan out from one or more nodes to everything they affect (forward) or depend on / are used by (backward), returned as a complete, deduped, Personalized-PageRank-ranked, located closure. Each row carries `path:line`, the edge `via` reason it's in scope, and a `⊘` when the engine finds it unreachable from any entry point (likely dead). Structural import/containment fan-out is excluded — no noise. Depth-1 in both directions is a node's immediate neighbours. Pass several comma-separated nodes to assess a whole diff at once.
- **trace** — Follow the code across boundaries. One argument: trace a feature end-to-end — the ordered path from entry through the stack, each hop labelled with its mechanism (call / HTTP / queue / event / data), crossing service boundaries (frontend→backend). Two arguments: the shortest path between two specific nodes, hop by hop. This is where the graph beats reading many files — it knows the cross-stack links grep can't see.
- **read** — Return the source code for one or more nodes, sliced from their files by the graph's line spans. Use after `find`/`impact` to read the exact code without grepping — comma-separate several node names to read the whole ranked set in a single call. Each node is a code block headed by its qname and `path:start-end`, plus a `context:` footer with structural facts the source alone doesn't show: HTTP method, cross-stack callers, covering tests, and intent/decision/constraint cells when present.
- **refresh** — (Re)build the structural graph with tree-sitter AST parsing across 20 languages, running the cross-stack resolvers (HTTP, gRPC, GraphQL, WebSocket, queues, events, CLI). Incremental by default — only changed files re-parse — so it's cheap to call after edits; set `full=true` to force a clean reparse. Accepts a local path or a git URL (cloned on demand). Call after a major refactor; routine edits are picked up automatically by the file watcher.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What James-Chahwan/repo-graph MCP server does

James-Chahwan/repo-graph turns a repository into a navigable graph for AI coding assistants. The graph represents entities such as modules, packages, classes, functions, routes, services, and components, along with relationships including imports, calls, containment, handlers, and cross-stack HTTP links. It also records feature paths from entry points through application layers and toward data access.

The result is a structural alternative to starting every investigation with broad file searches. Agents can identify relevant nodes, inspect their surrounding structure, follow a feature across service boundaries, and retrieve only the source spans associated with those nodes. This is most useful for large repositories, monorepos, and systems composed of multiple languages or services.

## How it works

The graph is created with tree-sitter AST parsing and additional resolvers for HTTP, gRPC, GraphQL, WebSocket, queues, events, and command-line flows. `refresh` accepts a local path or a Git URL and can clone a repository on demand. Incremental refresh is the default: changed files are reparsed, while `full=true` forces a clean rebuild. A file watcher updates the graph as routine edits occur.

A typical investigation starts with `orient` to see repository counts, entry points, and extraction blind spots. An agent can then use `find` to turn a symbol, keyword, stack trace, failing-test identifier, or diff into ranked graph nodes. `impact` evaluates affected or dependent nodes, while `trace` follows an end-to-end path or finds the shortest route between two nodes. Finally, `read` returns source slices for selected nodes and adds structural context such as callers, tests, HTTP methods, and available intent or constraint information.

## Setup and configuration

The package can be run with `uvx mcp-repo-graph --repo .` or installed with `pip install mcp-repo-graph`. The command `uvx mcp-repo-graph install` configures the available agents from one terminal command. VS Code and Cursor provide direct MCP installation links using the same `uvx` command and the current repository as `--repo .`.

The server uses a local repository path or Git URL as its input. Its graph cache is stored under `.glia/graph/`, and the cache is rebuilt automatically when the graph format requires it. The MCP server exposes the six tools `orient`, `find`, `impact`, `trace`, `read`, and `refresh`.

## Tools and capabilities

- `orient` returns an overview, entry points, and parser blind spots. A seed limits the map to a node neighborhood; `full=true` returns the full repository map.
- `find` ranks matching nodes and can expand into their neighborhoods. Results include `path:line` locations.
- `impact` calculates a deduplicated forward or backward closure, ranks results, identifies the relationship bringing each result into scope, and can mark nodes unreachable from entry points. Multiple comma-separated nodes support diff-level analysis.
- `trace` follows feature flows through calls, HTTP, queues, events, and data links, or finds a shortest path between two nodes.
- `read` retrieves source for one or more graph nodes using their recorded line spans and includes structural context.
- `refresh` performs incremental or full graph builds from local paths or Git URLs.

## Limitations and notes

Extraction coverage varies by language and relationship type. `orient` reports partial `(language, edge-kind)` coverage so an agent can decide when to fall back to grep. On large impact queries, the default response is an overview with top results and grouped areas or files; `scope`, `offset`, or `full=true` can be used to drill in or retrieve every row. Small, single-language projects may gain less from graph-based navigation than larger or cross-stack repositories.

_Full upstream README: https://allmcps.com/mcp/james-chahwan-repo-graph/readme_