builditwithgk/repo-cartographer

> **Understand any codebase in 60 seconds.** An MCP server that turns any repository into an architecture diagram.
Point your LLM at a folder and get back an architecture map: languages, frameworks, entry points, modules, and an import graph — rendered as a Mermaid diagram you can drop into a PR, a doc, or an onboarding guide.
It is **model-agnostic**. It speaks the Model Context Protocol over stdio, so it works with Claude Code, Claude Desktop, Cursor, Cline, Copilot, or the OpenAI Agents SDK — no Claude-specific dependency.
Why it's different
**The server extracts hard facts. The model does the reasoning.**
repo-cartographer never tries to "understand" your code semantically. It parses deterministic facts — file tree, import edges, manifests, framework detection, entry points — and hands your LLM structured JSON plus a **draft** diagram. Your model turns those facts into the final narrative and a refined diagram.
That split keeps the server small, fast, testable, and portable — and it means the diagram is grounded in what's actually in the repo, not hallucinated.
Example output
Running generate_diagram against **this repo** produces (a draft the model then refines):
A self-contained, shareable HTML render is committed under examples/ (both a high-level and a file-level detail view).
Install & run
Requires Node.js 18+.
The server communicates over stdio; AI clients launch it that way. You can also use it directly from a terminal — see below.
Command line (no AI needed)
The same binary is dual-mode: with no arguments it's the MCP server; with a subcommand it's a plain CLI for humans and CI.
Zip-friendly: if you point it at an extracted "Download ZIP" folder (repo-main/ wrapper and all), it detects the wrapper and maps the real repo root — noted in the output, never silent.
Two output notations, one strategy: **Mermaid because that's where people read it** (GitHub renders it natively in PR comments and READMEs), **DOT because that's what their tools eat** (pipe it into Graphviz, Backstage, or anything else: dot -Tsvg architecture.dot). Both come with the same shareable HTML page and role-colored modules. When the repo has a .cartographer.yml, its diagram: section supplies the defaults for --level, --format and -o; explicit flags always win.
check reads a rules file and flags **forbidden cross-boundary imports** and **dependency cycles** — deterministically, no LLM involved, so it's safe to gate a merge:
**Adopting on an existing codebase?** Record today's violations as an accepted baseline, so only *new* ones fail the build:
Commit that file; later runs auto-detect it and pass unless a PR introduces a *new* violation.
Architecture governance in CI (GitHub Action)
A composite action (action.yml) runs check on every PR — failing the
build on an error-level violation and posting a sticky comment with the diagram and
any violations:
This repo dogfoods it in .github/workflows/architecture.yml.
Full design + phases: docs/github-action.md.
Use it with Claude Code
Then ask: *"Use repo-cartographer to map ./my-project and draw me an architecture diagram."*
Claude Desktop