This server turns a local codebase into an architecture map and answers questions about its structure and the impact of changes — all via local static scans (no server, no code execution).
Scan a repository into an architecture graph (scan_repository_graph): takes an absolute path plus optional maxDepth (default 6) and collapseUtils (default true); returns full graph JSON with nodes, edges, nested clusters, and metrics (hubs, dead-code hints, coupling, density, LOC).
Generate an interactive HTML map (generate_architecture_html): writes a self-contained HTML architecture diagram for a repo, with theme (dark/light/matrix) and outputPath (default ./repograph.html, relative to path); returns { success, filePath, nodeCount }.
Query blast radius / impact (query_impact_path): given a repo-relative changedFile, returns direct and transitive callers with BFS depths, affected clusters, and blast radius — useful before editing or deleting a file.
Ask Claude to use it: e.g. "scan my repository at /path and show the impact of changing src/core/graph.ts", or generate an architecture map before a refactor.
No setup needed: each tool performs its own fresh static scan (JS/TS, Python, Go, Rust), so no prior scan, account, or shared state is required; only HTML generation writes a file.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@repograph scan /home/me/project and show what depends on src/core/graph.ts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Turn any codebase into an interactive architecture map in 2 seconds. Zero server, full privacy, built for Claude & Claude Code.
👉 Try the interactive live demo (zustand's architecture, generated with one command)
Find the files that matter before changing the code. RepoGraph scans local imports, groups source files by directory and likely architectural layer, and writes an interactive HTML map. Directory clustering and utility folding help keep shared helpers from turning the view into a spiderweb. Three MCP tools let Claude inspect architecture and trace the impact of a proposed change.
“2 seconds” describes the quickstart experience, not a measured performance guarantee. Scan time and HTML size depend on the repository; a small map can be ~40 KB. No account, server, or configuration file is required.
npx repograph-cli .Open the printed file:///.../repograph.html link. Click a file to see its incoming callers in cyan and outgoing dependencies in red. Double-click directory boxes to collapse or expand them. Press f to fit the graph to the viewport. Search matches subsequences in full file paths; the minimap lets you jump around large graphs.
Node.js 18 or newer is required. Scanning stays on your machine. The HTML embeds your file paths and graph data, so treat it as repository information when sharing. Opening the interactive map downloads pinned Cytoscape/layout scripts from public CDNs; no source or graph data is sent by RepoGraph. The CDN scripts must be reachable on first opening. SVG, JSON, and Mermaid exports need no browser CDN scripts.
Related MCP server: contextflow-mcp
repograph [path] [options]
repograph mcp
Options:
-o, --output <file> Write to a file
--theme <theme> dark | light | matrix (default: dark)
--max-depth <n> Maximum directory nesting (default: 6)
--no-collapse-utils Show utility candidates immediately
--format <format> html | json | mermaid | svg (default: html)
-V, --version Show version
-h, --help Show helpThe path defaults to .. HTML defaults to ./repograph.html in your current working directory and prints its absolute file URL after writing. Other formats print to stdout unless --output is supplied. Output directories are created automatically. --max-depth 0 scans only root files.
npx repograph-cli ./my-app --output ./architecture.html --theme matrix
npx repograph-cli . --format json > graph.json
npx repograph-cli . --format mermaid --output architecture.mmd
npx repograph-cli . --format svg --output architecture.svg
npx repograph-cli . --max-depth 10 --no-collapse-utilsThe static SVG arranges files in entry → business → unknown → data → util columns. Mermaid exports preserve nested directory subgraphs. Both include utility candidates; HTML initially hides folded utilities and their edges.
RepoGraph is listed on the official MCP Registry as io.github.Karry1123/repograph. Registry-aware clients can install it by that name; the manual Claude setup below also works.
Add this entry to claude_desktop_config.json, merging it with existing servers:
{
"mcpServers": {
"repograph": {
"command": "npx",
"args": ["-y", "repograph-cli", "mcp"]
}
}
}Restart Claude Desktop, then ask: “Scan my repository at /absolute/path/to/project and show the impact of changing src/core/graph.ts.” Use an absolute repository path; the MCP server may start with a different working directory. Windows paths work too, for example F:\\RepoGraph in JSON.
claude mcp add repograph -- npx -y repograph-cli mcpAsk Claude to generate an architecture map before a refactor, or find all transitive callers of a module before editing it. MCP mode uses stdio for the protocol and writes errors only to stderr.
Tool | Arguments | Result |
|
| Full ArchitectureGraph JSON: nodes, edges, nested clusters, metrics. Use for structure and hub files. |
|
| Writes a self-contained interactive map; returns |
|
| Direct and transitive callers with BFS depth, affected clusters, blast radius. Use before editing or deleting a file. |
Each tool performs its own fresh static scan of path on every call, so no prior scan is needed. Tools are annotated readOnlyHint: true except generate_architecture_html, which writes one file.
For HTML generation, a relative outputPath is resolved against the repository path. An absolute output path is used directly. The tools use a utility fan-in threshold of 15. Missing changed files return an error with the closest matching IDs. transitiveDependents includes direct callers at depth 1; blastRadius counts unique affected files and excludes the changed file itself.
Each source file becomes a node with a forward-slash relative ID. Local imports become directed edges from importer to dependency. JavaScript and TypeScript use Babel, with a regex fallback for unsupported syntax. Repeated references of the same type are combined with an edge weight. External packages are dropped. Class inheritance through an imported binding gets an inheritance edge; import() gets a dynamic edge.
RepoGraph tries source extensions, directory index files, NodeNext .js → .ts equivalents, and a heuristic @/ → src/ alias. It does not execute code or load project-specific compiler plugins. Computed imports and custom aliases can be missed.
Layer | File or directory clues | Colour |
Entry | controller, route, router, handler, api, endpoint, cli, app, server, main; root index | Cyan |
Business | service, usecase, core, domain, logic, manager | Magenta |
Data | repo, repository, model, schema, entity, store, db, dao, migration | Amber |
Util | util, utils, helpers, common, shared, lib, constants, types, config; high fan-in | Slate |
Unknown | Everything else | Indigo |
Classification checks entry, business, data, then utility clues. It is an explainable filename heuristic, not a semantic judgement about your design. Clusters reflect the first two directory levels and retain nested parents.
Files with more than 12 incoming callers and at most two outgoing dependencies, or utility-like names, are folding candidates. CLI/API default to 12; MCP defaults to 15. Folded nodes and their edges stay in the graph data and impact analysis but disappear from the initial HTML view. “Show utilities” reveals them. Degree counts use unique neighboring files, not repeated imports.
Impact analysis performs a breadth-first search over reverse edges. It handles cycles, visits each file once, and records the shortest caller depth. The inspector lists direct callers and dependencies; the highlight traces both full transitive chains. If a cycle belongs to both chains, the dependency highlight takes precedence.
Dead-code warnings count files with no incoming local edges that do not look like entry points. Treat these as review hints: frameworks, reflection, external consumers, and dynamic loading can all create valid files with no static callers. Coupling factor is average unique out-degree; density is edges divided by n * (n - 1) (zero for fewer than two files). LOC counts nonblank source lines, including comments.
Language | Resolution |
JavaScript / TypeScript | ESM imports/re-exports, |
Python |
|
Go | Single imports and import blocks; paths under the root |
Rust |
|
Root and nested .gitignore rules are respected. RepoGraph skips dependency, build, cache, and editor directories, including node_modules, .git, dist, build, out, coverage, __pycache__, .venv, venv, .next, .nuxt, target, vendor, .idea, .vscode, and .cache. Symlinks are skipped to prevent cycles. Files larger than 1.5 MB and *.min.js are excluded. Test/spec files are excluded from the main graph, with their count retained as metrics.excludedTestFiles.
Python, Go, and Rust resolution is intentionally static and heuristic: workspace manifests, build tags, Python import hooks, Rust macros, and non-root Go modules are not evaluated. Only files included in the scan can become nodes or targets.
This table describes the tools' focus rather than a feature-completeness or performance benchmark. Check each project's current documentation for its full capabilities.
RepoGraph | Madge | CodeSee | Gitingest | |
Primary output | Local interactive HTML architecture map | Module dependency graphs | Code exploration and mapping platform | Repository text context |
Workflow | CLI + three MCP tools | Dependency analysis CLI/API | Platform workflow | Ingest code for LLM context |
Main emphasis | Layers, utility folding, caller impact | Module relationships and cycles | Collaborative code understanding | Shareable code context |
RepoGraph's approach | No server; embedded graph snapshot | Complementary dependency tooling | Different platform model | Complementary text-first tooling |
import { analyzeRepository } from 'repograph-cli/dist/src/api.js';
import { impactPath } from 'repograph-cli/dist/src/core/graph.js';
import { renderToHtml } from 'repograph-cli/dist/src/renderer/htmlTemplate.js';
const graph = await analyzeRepository('.', {
maxDepth: 6,
collapseUtils: true,
utilThreshold: 12,
});
const impact = impactPath(graph, 'src/api.ts');
const html = renderToHtml(graph, { theme: 'dark' });createServer() and startMcpServer() are exported from dist/src/index.js; importing the module does not start a transport. The graph data model lives in src/types.ts and ships with generated TypeScript declarations.
npm install
npm run build
node dist/bin/cli.js . --output demo/self.html
node dist/bin/cli.js . --format json
node dist/bin/cli.js . --format mermaidDuring development, use npm run dev -- .. On Windows PowerShell installations that block npm.ps1, use npm.cmd. Keep path IDs portable, avoid executing scanned code, and test resolution changes against a small repository containing the relevant imports. Include reproduction steps and the expected edges in bug reports or contributions.
MIT © 2026 Karry. See LICENSE.
TypeScript/JavaScript
Python
Go
Rust
Java/Kotlin (unlocks at 200 ⭐)
C# (300 ⭐)
PHP/Ruby (500 ⭐)
Monorepo workspace + tsconfig paths alias resolution (200 ⭐)
VS Code extension (1000 ⭐)
Star to vote, open a Language Support Request issue, and share the imports and project layout you need supported. These thresholds guide priorities rather than promise delivery dates.
Scan a local repository and write a single self-contained HTML file with an interactive architecture map: compound boxes per directory, nodes coloured by heuristic layer, click-to-highlight callers (cyan) and dependencies (red), fuzzy search, collapsible directories and a minimap. Use it when a person wants to look at or share the architecture; use scan_repository_graph when you need the data as JSON, or query_impact_path for the blast radius of one file. Returns { success: true, filePath, nodeCount } where filePath is the absolute path of the written file, which you can open in a browser. Every call performs its own fresh static scan of path; no prior scan is required. The HTML embeds the repository file paths and graph data, so treat it as repository information when sharing. The page loads pinned Cytoscape.js libraries from a public CDN when opened; nothing else leaves the machine.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the repository root to scan, e.g. "/home/me/project" or "C:/dev/project". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths. | |
| theme | No | Colour theme of the generated page: "dark" (slate background, default), "light", or "matrix" (black and green). | dark |
| outputPath | No | Where to write the HTML file. Default "./repograph.html". A relative value is resolved against `path` (the repository root); an absolute value is used as-is, e.g. "/tmp/arch.html". Parent directories are created. | ./repograph.html |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds real context beyond annotations: it writes a file to disk, performs a fresh static scan on every call (no prior scan needed), embeds repository file paths so the artifact should be treated as repo information, and loads pinned Cytoscape.js from a CDN on open. However, it does not state overwrite behavior for an existing outputPath or any failure modes, which matters for a tool whose annotations declare readOnlyHint=false but destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the capability, then routing, then return value, then behavioral caveats. Dense but every sentence carries distinct information; the embedded feature list is the only slightly heavy part.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description documents the return shape ({ success, filePath, nodeCount }), explains that filePath is an absolute path openable in a browser, and covers the scanning and CDN behavioral model. An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (including the path absolute-path guidance and outputPath resolution rules) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (scan + write) and resource (single self-contained HTML architecture map) with concrete feature enumeration. It explicitly distinguishes itself from scan_repository_graph (JSON data) and query_impact_path (blast radius), so an agent can route without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use ('when a person wants to look at or share the architecture') and names both alternatives with the exact condition selecting each. Nothing about tool selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a local repository and report which files would be affected by changing one file: a breadth-first search over reverse import edges. Returns { changedFile, directDependents, transitiveDependents: [{ id, depth }], affectedClusters, blastRadius } where depth 1 means a direct importer, affectedClusters lists the directories touched, and blastRadius counts unique affected files excluding the changed file. Use it before editing, renaming or deleting a file to see who depends on it; use scan_repository_graph when you need the full graph, or generate_architecture_html for a visual. Every call performs its own fresh static scan of path; no prior scan is required. If changedFile is not found, the result is an error that lists the closest matching file ids so you can retry. Static analysis only: dynamic or computed imports and custom path aliases may be missed, and external packages are not tracked.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the repository root to scan, e.g. "/home/me/project" or "C:/dev/project". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths. | |
| changedFile | Yes | The file whose callers you want, as a repository-relative path with forward slashes, e.g. "src/core/graph.ts" or "pkg/server/handler.go". An absolute path inside the repository is also accepted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), and the description still adds real behavior: each call performs a fresh static scan so no prior scan is needed, missing changedFile yields an error with closest matching ids, and static analysis limits (dynamic/computed imports, aliases, external packages) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and algorithm, then the return shape, then alternatives, then caveats — a sensible ordering with no filler sentences. It is dense and multi-clause, which costs it the top mark, but nothing is redundant given the absent output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description supplies the full return shape including field meanings ('depth 1 means a direct importer', blastRadius excluding the changed file). Combined with the disclosed limitations and error behavior, an agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics: `path` is rescanned every call (fresh-scan contract) and `changedFile` failure mode returns near-match ids. It does not, however, restate the path-format expectations, which the schema already handles well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('report which files would be affected by changing one file') plus the algorithm ('breadth-first search over reverse import edges'). The title's 'blast radius' concept is operationalized, so an agent can distinguish this from the two siblings without reading their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('before editing, renaming or deleting a file') and names both alternatives with their selecting conditions: scan_repository_graph for the full graph, generate_architecture_html for a visual. Exclusions are stated, not inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a local repository and return its architecture graph as JSON: one node per source file (id, layer, cluster, in/out degree, lines of code), import edges between files, nested directory clusters, and metrics (totalFiles, totalEdges, density, couplingFactor, deadCodeCount, foldedUtilityCount). Use it to understand how a codebase is organised, find hub files, or feed graph data into further analysis. Use query_impact_path instead when you only need the callers of one file, and generate_architecture_html when a human wants a visual map. Every call performs its own fresh static scan of path; no prior scan is required. Reads the local filesystem only, executes nothing, and sends nothing over the network. Supports TypeScript/JavaScript, Python, Go and Rust; external packages are dropped, test files are excluded, and layer labels (entry/business/data/util/unknown) are filename heuristics, not semantic judgements.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the repository root to scan, e.g. "/home/me/project" or "C:/dev/project". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths. | |
| maxDepth | No | Maximum directory nesting depth to scan below the root. Integer, default 6. Use 0 to scan only files in the root directory; raise it for deeply nested monorepos. | |
| collapseUtils | No | Whether to mark high fan-in utility files (more than 15 callers and at most two dependencies, or utility-like names such as utils/helpers/types/config) as folded. Boolean, default true. Folded nodes stay in the graph data with isFolded: true; set false to treat every file equally. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: every call performs a fresh static scan with no prior scan required, reads only the local filesystem, executes nothing and makes no network calls. It also discloses language support, that external packages are dropped and tests excluded, and that layer labels are filename heuristics rather than semantic judgements — a material caveat for interpreting results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and output shape, and every clause carries information (alternatives, freshness, safety, language scope, heuristic caveat). It is a single dense paragraph, so the caveats are harder to scan than they would be if separated, but there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so by enumerating node fields, edges, clusters, and named metrics. Combined with freshness, safety, and language-scope statements, an agent has everything needed to call it correctly and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining that folded utility nodes remain in the data with isFolded:true and that layer/cluster labels are heuristics. It does not add syntax guidance for maxDepth or path beyond what the schema already says, so it stops short of a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Scan a local repository and return its architecture graph as JSON') and enumerates the return structure (nodes, edges, clusters, metrics). It distinguishes itself from both siblings by name and by what distinguishes them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit use cases ('understand how a codebase is organised, find hub files, or feed graph data into further analysis') and names the alternatives with the conditions that select them: query_impact_path for callers of one file, generate_architecture_html for a human-facing visual map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
generate_architecture_html3 fields changedInput schema / properties / outputPath / descriptionAdded value: +"Where to write the HTML file. Default \"./repograph.html\". A relative value is resolved against `path` (the repository root); an absolute value is used as-is, e.g. \"/tmp/arch.html\". Parent directories are created."Input schema / properties / path / descriptionAdded value: +"Absolute path to the repository root to scan, e.g. \"/home/me/project\" or \"C:/dev/project\". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths."Input schema / properties / theme / descriptionAdded value: +"Colour theme of the generated page: \"dark\" (slate background, default), \"light\", or \"matrix\" (black and green)."query_impact_path2 fields changedInput schema / properties / changedFile / descriptionAdded value: +"The file whose callers you want, as a repository-relative path with forward slashes, e.g. \"src/core/graph.ts\" or \"pkg/server/handler.go\". An absolute path inside the repository is also accepted."Input schema / properties / path / descriptionAdded value: +"Absolute path to the repository root to scan, e.g. \"/home/me/project\" or \"C:/dev/project\". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths."scan_repository_graph3 fields changedInput schema / properties / collapseUtils / descriptionAdded value: +"Whether to mark high fan-in utility files (more than 15 callers and at most two dependencies, or utility-like names such as utils/helpers/types/config) as folded. Boolean, default true. Folded nodes stay in the graph data with isFolded: true; set false to treat every file equally."Input schema / properties / maxDepth / descriptionAdded value: +"Maximum directory nesting depth to scan below the root. Integer, default 6. Use 0 to scan only files in the root directory; raise it for deeply nested monorepos."Input schema / properties / path / descriptionAdded value: +"Absolute path to the repository root to scan, e.g. \"/home/me/project\" or \"C:/dev/project\". Relative paths resolve against the MCP server process working directory, which is usually not the project, so prefer absolute paths."v0.1.1generate_architecture_htmlquery_impact_pathscan_repository_graphScored across 3 tools
Each tool produces a clearly different artifact: full graph JSON, a rendered HTML visual, or a reverse-dependency blast radius for one file. Descriptions explicitly cross-reference each other ('use X when you need Y'), so misselection is very unlikely.
All three names follow a strict verb_noun snake_case pattern (scan_repository_graph, generate_architecture_html, query_impact_path) with unambiguous verbs.
Three tools is on the lean side but each covers a genuinely distinct output mode (data, visualization, targeted analysis) with no filler. The narrow scope is intentional and coherent rather than anemic.
The surface covers the core lifecycle: extract graph, export it, and analyze impact of a change, including error recovery hints for unknown files. Minor gaps exist (e.g. no tool to query a single node's details or filter/cluster views without pulling the whole graph), but the full graph output makes these workable.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
