CodeCartographer MCP server

CodeCartographer

Understand an unfamiliar codebase with an AI agent — and get a validated spec you can rebuild from. CodeCartographer turns a repository into layered architecture, behavioral contracts, defect findings, and a language-agnostic reimplementation spec, with each phase validated before the next one runs. Works with Pi, Claude Code, Cursor, Codex, or any MCP-capable agent.

●  CodeCartographer
├─ ✓  architecture phase    ⟳ 25 · 76 tool uses · 1.0M tokens · 4m28s
├─ ✓  defect-scan-mech.     ⟳ 39 · 91 tool uses · 2.4M tokens · 7m05s
└─ ⠹  contracts phase       ⟳ 11 · 37 tool uses · 335.1k tokens · 40.1s
       ⎿ extracting behavioral contracts from server/index.ts…

Why CodeCartographer

Asking an LLM to "analyze this repo" loses context halfway through, hallucinates findings, and leaves no artifact the next session can pick up. CodeCartographer fixes three things:

1. The filesystem is the memory, not the conversation. Each phase writes a smaller, templated, evidence-tagged artifact to .codecarto/findings/. Later phases re-read the specific upstream files they need. A new session — or a context compaction — picks up from status.yaml without losing progress.

1. Every phase attests to its own completion, and the gate holds it to that. Each output ends with a ## Validation table where the phase marks every completion criterion PASS, PARTIAL, or FAIL with evidence. Validation parses that table, cross-checks the findings' evidence/action pairing and the declared secondary outputs, and refuses to advance on a FAIL, a missing output, or a verdict it cannot read. It does not re-judge the criteria itself — that is the model's honest self-assessment plus two mechanical checks, which is exactly what a later phase can hold the earlier one to.

1. The output is a spec, not a chat log. The final reimplementation-spec.md is language-agnostic, module-inventoried, and carries acceptance scenarios plus known unknowns. Hand it to another agent to rebuild from.

Every finding is tagged with an evidence level: observed fact, strong inference, portability hazard, external-behavior claim, or open question.

At a glance

Shortened. The full README is on GitHub.