CodeCartographer MCP server

by HuginnIndustries·io.github.HuginnIndustries/codecartographer·v0.26.0

No reviews yet

Turn an unfamiliar codebase into validated architecture, contracts, and a reimplementation spec.

A91/100grade A

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

A91/100

full report

Adoption

Growing

4 stars2.6k downloads/wk

Reviews

Write one

Nobody has reviewed CodeCartographer yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

CodeCartographer tools (22, 1 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

codecarto_amend
Apply a post-pipeline amendment from .codecarto/scratch/amendments/<name>.yaml to workflow/status.yaml: close open questions resolved on evidence after the pipeline completed and retire finished post-pipeline backlog items, under the same lock completion uses. Writes an amendment closeout and THREAD_LOG entry. Refused while the pipeline is incomplete — mid-pipeline resolutions belong in the phase
codecarto_broadside
Broad-Side: fire a cheap batch reconnaissance scan at a repository via the OpenRouter Batch API. Six lenses (architecture, api, security, defect, conventions, porting) run as asynchronous single-turn prompts with structured JSON schemas; results land in .codecarto/broadside/<run>/ as JSON plus markdown, with an optional cross-lens synthesis report. Works on any git repository — no CodeCartographer
codecarto_complete
Mark a phase complete. Requires the phase output's validation to be PASS or PASS WITH GAPS and applies the phase handoff at scratch/handoffs/<phase>.yaml. Atomically updates status.yaml under a file lock, appends one THREAD_LOG.md entry, and writes the phase's closeout: the handoff's closeout_content (plus its decisions) overwrites the canonical <date>-<phase>.md when supplied; otherwise a stub is
codecarto_config
Show the effective merged CodeCartographer configuration (library.path, library.namespace, publish_confirm, llm_steer_next_phase) and whether the library marker was found. Pass cwd to include workspace-level config in the merge.
codecarto_dashboard
Regenerate .codecarto/dashboard.html from the current workspace state.
codecarto_guide
Return the instructions for driving this server: the status/next/execute/validate/complete loop, the phase-handoff contract, pipeline selection, executor choice, and recovery. Call this first when you have not run a CodeCartographer pipeline before. Takes no workspace.
codecarto_init
Initialize a CodeCartographer workspace (.codecarto/) in a target repository. Copies the packaged framework template and writes a fresh status.yaml for the chosen pipeline. If .codecarto/ already exists, pass force: true to back up the existing workspace to .codecarto-backup-TIMESTAMP/ and create a fresh one. Warning: backing up moves all existing findings, handoffs, usage data, closeouts, and pha
codecarto_library_init
Initialize a CodeCartographer library at the given path: create the directory, write the .codecarto-library marker, and write the library.path into the user-global config. Idempotent — safe to re-run on an existing library. Pass a namespace to create a namespaced (shared) library.
codecarto_library_list
List entries in a CodeCartographer library, optionally filtered by namespace, tag, slug, or source_repo. The library is identified by library_path (absolute) or by cwd's config.yaml. Flags entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); repair is manual.
codecarto_library_reindex
Regenerate index.yaml and INDEX.md for a CodeCartographer library from filesystem state. Use after manual edits or to resolve a git merge conflict on index.yaml. Also reports entries whose versions disagree about source_repo (merged by a slug collision before publish refused cross-project appends); the index files are not changed and repair is manual.
codecarto_list_skills
List available post-pipeline skills installed in the workspace, plus the Broad-Side reading guide when it is present (that one is not pipeline-gated).
codecarto_next
Return the prompt text for the next eligible CodeCartographer phase. The host should feed this prompt back to the agent or display it to the user.
codecarto_open
Activate an existing CodeCartographer workspace without resetting state. Returns the current pipeline and phase.
codecarto_phase
Return the prompt text for a specific CodeCartographer phase, even if it is not the next eligible phase. Used to revisit a phase or to bypass DAG order intentionally.
codecarto_publishwrite action
Publish a reimplementation-spec to a CodeCartographer library. Identified by library_path (absolute) or cwd's config.yaml. Content-hash idempotent — re-publishing identical spec bytes updates metadata in place rather than bumping the version. Required: source_repo, headline, and either spec (inline) or spec_path (absolute file). Slug derives from source_repo if not provided. If the library is name
codecarto_refresh_scaffold
Refresh a workspace's framework-owned files (GUIDE.md, templates/, workflow pipelines and VALIDATE.md, skills/, findings SKILL and README stubs) from the packaged template — the action every scaffold-staleness warning instructs. Never touches project state (status.yaml), user config (workflow/config.yaml, usage log), findings outputs, scratch/, closeouts/, or the orchestrator files (CONVENTIONS.md
codecarto_skill
Return the prompt text for a post-pipeline skill (only callable after all phases are complete). Use codecarto_status to confirm completion first. One name is exempt from the completion gate: "broadside" returns the reading guide for a Broad-Side batch reconnaissance run, which is meant to be read before or during the pipeline and works without a workspace.
codecarto_status
Show the current CodeCartographer phase, active pipeline, and progress for a target repository.
codecarto_switch_pipeline
Switch the active pipeline in-place without losing findings, handoffs, usage data, or phase progress. Phases that exist in both the old and new pipelines preserve their completion status. Phases unique to the new pipeline start as pending. Pass a pipeline alias (e.g. lite, full, synthesis) or a workflow/*.yaml path.
codecarto_usage
Show cumulative and per-phase token usage from local phase runs.
codecarto_validate
Read the ## Validation table a phase wrote at the end of its primary output — the phase's own PASS/PARTIAL/FAIL per completion criterion — apply two cross-checks (findings evidence/action pairing; declared secondary outputs present), and return PASS/PASS WITH GAPS/FAIL/MISSING plus the parsed rows. It does not judge the criteria itself. If phase is omitted, validates the next eligible phase.
codecarto_vision
Generate a structured vision brief from raw product text using the guided interview skill. Returns a prompt the host should feed to its agent to write inputs/vision.md. Requires a synthesis workspace (run codecarto_init with the synthesis pipeline first).

Public scan report

scanner v0.1.5 · 2026-09-19 · same rubric, same numbers if you re-run it

no findings

Code scan122 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitylocal package, no credentials required12/15
Maintenancelast push 1 days ago15/15
Maintainer identityregistry namespace matches repository owner7/10

Overall 91/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

What the publisher says

From the CodeCartographer repository's README, as published. We do not edit it. Read it on GitHub

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:

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.

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.

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.

Nothing above is checked by us. What we check is on the safety report.

Install directly

Runs npx -y codecartographer-pi on your machine. Read the scan report first; the gateway never runs local packages.

claude mcp add codecartographer -- npx -y codecartographer-pi

Add to Cursor

CodeCartographer: common questions

Is CodeCartographer MCP server safe?: Yes, by our scan: it is graded A (91/100). Read the CodeCartographer safety report
How do I install CodeCartographer?: It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.
Does CodeCartographer need an API key?: Not as far as the registry entry and our scan can tell: no credentials are declared or required.
Is CodeCartographer maintained?: The last commit was 2 days ago (2026-09-18). The latest release is v0.26.0.