{
  "markdown": "# repo-cartographer\n\n> **Understand any codebase in 60 seconds.** An [MCP](https://modelcontextprotocol.io) server that turns any repository into an architecture diagram.\n\n![TypeScript](https://img.shields.io/badge/TypeScript-ESM-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![Version](https://img.shields.io/badge/version-1.0.0-blue) ![MCP](https://img.shields.io/badge/MCP-model--agnostic-brightgreen) [![Architecture](https://github.com/builditwithgk/repo-cartographer/actions/workflows/architecture.yml/badge.svg)](https://github.com/builditwithgk/repo-cartographer/actions/workflows/architecture.yml)\n\nPoint your LLM at a folder and get back an architecture map: languages, frameworks, entry points, modules, and an import graph — rendered as a [Mermaid](https://mermaid.js.org/) diagram you can drop into a PR, a doc, or an onboarding guide.\n\nIt 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.\n\n## Why it's different\n\n**The server extracts hard facts. The model does the reasoning.**\n\n`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.\n\nThat 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.\n\n## Example output\n\nRunning `generate_diagram` against **this repo** produces (a draft the model then refines):\n\n```mermaid\nflowchart TD\n    n0[\"src · 2 files\"]\n    n1[\"src/lib · library code · 9 files\"]\n    n2[\"src/resources · resource handlers · 1 file\"]\n    n3[\"src/tools · tool implementations · 4 files\"]\n    n0 --> n1\n    n0 --> n2\n    n0 --> n3\n    n1 --> n0\n    n3 --> n0\n    n3 --> n1\n```\n\nA self-contained, shareable HTML render is committed under [`examples/`](examples/) (both a high-level and a file-level [`detail`](examples/repo-cartographer-detail.html) view).\n\n## Install & run\n\nRequires Node.js 18+.\n\n```bash\n# Run directly (no install)\nnpx -y repo-cartographer\n\n# …or from source\ngit clone https://github.com/builditwithgk/repo-cartographer\ncd repo-cartographer\nnpm install\nnpm run build\nnode dist/index.js\n```\n\nThe server communicates over stdio; AI clients launch it that way. You can also use it directly from a terminal — see below.\n\n## Command line (no AI needed)\n\nThe 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.\n\n```bash\n# Draw a diagram — path in, architecture.html out\nnpx -y repo-cartographer map ./my-project\nnpx -y repo-cartographer map ./my-project --level detail -o docs/architecture\nnpx -y repo-cartographer map ./my-project --format dot   # Graphviz DOT instead of Mermaid\n\n# Enforce architecture rules (exits 1 on an error-level violation — use it in CI)\nnpx -y repo-cartographer check ./my-project --config .cartographer.yml\n```\n\nZip-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.\n\nTwo 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.\n\n`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:\n\n```yaml\n# .cartographer.yml\nrules:\n  forbidden:\n    - from: \"src/ui/**\"\n      to:   \"src/db/**\"\n      reason: \"UI must go through the service layer, not the DB directly.\"\n  cycles: error        # error | warn | off\n```\n\n**Adopting on an existing codebase?** Record today's violations as an accepted baseline, so only *new* ones fail the build:\n\n```bash\nnpx -y repo-cartographer check . --update-baseline   # writes .cartographer-baseline.json\n```\n\nCommit that file; later runs auto-detect it and pass unless a PR introduces a *new* violation.\n\n## Architecture governance in CI (GitHub Action)\n\nA composite action ([`action.yml`](action.yml)) runs `check` on every PR — failing the\nbuild on an error-level violation and posting a sticky comment with the diagram and\nany violations:\n\n```yaml\n# .github/workflows/architecture.yml\non: pull_request\npermissions: { contents: read, pull-requests: write }\njobs:\n  architecture:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: builditwithgk/repo-cartographer@v1\n        with: { path: ., config: .cartographer.yml }\n```\n\nThis repo dogfoods it in [`.github/workflows/architecture.yml`](.github/workflows/architecture.yml).\nFull design + phases: [docs/github-action.md](docs/github-action.md).\n\n## Use it with Claude Code\n\n```bash\nclaude mcp add repo-cartographer -- npx -y repo-cartographer\n```\n\nThen ask: *\"Use repo-cartographer to map ./my-project and draw me an architecture diagram.\"*\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"repo-cartographer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"repo-cartographer\"]\n    }\n  }\n}\n```\n\n## Use it with the OpenAI Agents SDK\n\nSame server, a different model — the whole point of MCP:\n\n```python\nimport asyncio\nfrom agents import Agent, Runner\nfrom agents.mcp import MCPServerStdio\n\nasync def main():\n    async with MCPServerStdio(\n        params={\"command\": \"npx\", \"args\": [\"-y\", \"repo-cartographer\"]},\n    ) as cartographer:\n        agent = Agent(\n            name=\"Cartographer\",\n            instructions=(\n                \"Use the repo tools to gather facts, then refine the draft \"\n                \"Mermaid diagram into a clean architecture map.\"\n            ),\n            mcp_servers=[cartographer],\n        )\n        result = await Runner.run(agent, \"Map ./my-project and explain its architecture.\")\n        print(result.final_output)\n\nasyncio.run(main())\n```\n\n## Tools & resources\n\n| Tool | What it returns |\n| --- | --- |\n| **`map_repo(path, level?, format?, outPath?)`** | **The one-shot flow.** Point it at a folder and get a downloadable architecture diagram (`architecture.html` + `.mermaid`/`.dot`) plus a facts summary and the draft source inline — in a single call. |\n| `scan_repo(path)` | Languages, frameworks, entry points, top-level modules (with role guesses), and a manifest summary — as JSON facts. |\n| `build_import_graph(path)` | Intra-repo import/require edges for JS/TS + Python. Nodes are files, auto-collapsed to module level for large repos. |\n| `generate_diagram(path, level?, format?)` | A **draft** diagram. `level` = `\"high\"` (modules, default) or `\"detail\"` (files grouped by module); `format` = `\"mermaid\"` (default) or `\"dot\"` (Graphviz). |\n| `render_diagram(source, outPath, format?)` | Writes a self-contained, styled `.html` (renders via CDN: Mermaid, or Viz for DOT) plus the raw `.mermaid`/`.dot` file. |\n\n| Resource | |\n| --- | --- |\n| `about://author` | Who built this and how to reach them (Markdown). |\n\n**Most of the time you just want `map_repo`** — \"path in, diagram out.\" Reach for the four granular tools only when you want to compose the steps yourself (e.g. let the model refine the diagram source between `generate_diagram` and `render_diagram`).\n\n## How it stays fast on big repos\n\n- **Languages:** JavaScript/TypeScript and Python (v1).\n- **Skips** `node_modules`, `.git`, `dist`, `build`, `venv`, `__pycache__`, `vendor`, and other build/dependency/cache directories (plus all hidden dirs).\n- **Caps** the number of files scanned and bytes read per file; **collapses** the import graph to directory level past a threshold. Anything capped is reported in the output — never dropped silently.\n- **No network calls** at scan time. (The rendered HTML pulls Mermaid from a CDN only when *you* open it in a browser.)\n- **Deterministic:** output is sorted and stable, so diagrams don't churn between runs.\n\n## Development\n\n```bash\nnpm run dev        # run from source with tsx\nnpm run build      # type-check + emit to dist/\nnpm test           # unit tests (node:test, no build step needed)\nnpm run typecheck  # type-check src/ and test/ together, no emit\n```\n\nTests cover the deterministic core — import resolution (JS/TS + Python), module\ncollapsing, cycle detection, rule globs, baseline diffing, Mermaid rendering and\nthe `check` end-to-end path. They run against `src/` via `tsx`, so there is no\nbuild step and no test framework dependency.\n\n## Author\n\nBuilt by **Gopi K Aitham** ([builditwithgk](https://github.com/builditwithgk)) — see `about://author`, or [scaleup-solutions.in](https://scaleup-solutions.in/). Available for freelance and contract work on AI, agent, and MCP tooling.\n\n## License\n\nMIT\n",
  "bytes": 9252,
  "sha": "a9407fb3d4fbad101596b37546d349435a41f5a52fbfb022013d4d223696b594",
  "repo_slug": "builditwithgk/repo-cartographer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_builditwithgk_repo_cartographe_451decf3/readme"
}