CodeCartographer — Claude Code MCP server: map any codebase
Turns an unfamiliar repository into layered architecture, behavioral contracts and a reimplementation spec. Each phase is validated before the next one starts.
claude mcp add codecartographer -- npx -y codecartographer-piWhat CodeCartographer does
The server walks an agent through phases: architecture, defect scan, behavioral contracts, protocols, porting, and a reimplementation spec. Every phase drops a templated artifact into .codecarto/findings/ instead of leaving results in the chat. A fresh session or a context compaction resumes from status.yaml.
Before moving on, the pipeline checks the phase. Each output carries a ## Validation table where the phase marks its criteria PASS, PARTIAL or FAIL with supporting notes, and two mechanical checks compare the evidence against the actions and the declared secondary outputs. A FAIL, a missing file or an unreadable verdict stops the run. The model grades itself, and the checks keep that honest.
The final reimplementation-spec.md is language-agnostic and lists modules, acceptance scenarios and open questions. Hand it to another agent to rebuild from. Running it needs Node.js 20 or newer, since the package starts through npx.
What it helps with
- map an unfamiliar repository into layers
- catch defects before users hit them
- extract behavioral contracts from server code
- produce a spec for rebuilding in another language
- keep analysis progress across context compaction
Example prompts for the agent
- Run the CodeCartographer pipeline over this repo and show me the architecture
- Start the defect scan phase and write findings to
.codecarto/findings/ - Build
reimplementation-spec.mdfrom the finished phases
How to install CodeCartographer
Platform CLI
claude mcp add codecartographer -- npx -y codecartographer-piPlatform CLI
codex mcp add codecartographer -- npx -y codecartographer-piConfig file
{
"mcpServers": {
"codecartographer": {
"command": "npx",
"args": [
"-y",
"codecartographer-pi"
]
}
}
}Config file
{
"servers": {
"codecartographer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codecartographer-pi"
]
}
}
}Platform CLI
gemini mcp add codecartographer npx -y codecartographer-piStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about CodeCartographer
How do I install CodeCartographer in Claude Code?
Run claude mcp add codecartographer -- npx -y codecartographer-pi. The server then shows up to the agent over MCP.
What does CodeCartographer do?
It runs a repository through analysis phases and stores the results under .codecarto/. You end up with a spec you can rebuild the code from.
What do I need to run it?
Node.js 20 or newer, because the package launches via npx. The authors recommend the Pi extension for interactive work; the MCP server is for agents such as Claude, Codex or Cursor.
