CodebaseCartographer

Local, evidence-backed codebase intelligence for safer changes.

CodebaseCartographer is a local Model Context Protocol (MCP) server and command-line tool for understanding an unfamiliar repository before changing it. It statically parses supported source files, builds a graph of modules, classes, functions, imports, and resolved local calls, and supplements that graph with local Git history when available.

It gives an MCP client such as Codex concrete repository evidence for questions like:

• What calls this function, and what does it call?
• Which modules and tests are likely affected by a proposed change?
• Where are the dependency cycles, highly connected files, or likely orphan modules?
• Who has changed this area recently, and which files tend to change with it?

CodebaseCartographer does not execute the repository it analyzes or make application-level network calls. Analysis, Git inspection, and optional caching all happen on the local machine.

Why use it

Reading files one at a time is slow and makes it easy to miss indirect dependencies. CodebaseCartographer creates a structured, inspectable starting point before a plan or edit is made.

For example, before changing PaymentService.process_refund, you can ask an MCP client to trace its callers and callees, identify related modules, inspect local Git context, and recommend tests. The response is based on the graph and reports its coverage and uncertainty, rather than presenting a guess as a fact.

The result is useful for:

• Change planning: estimate the static blast radius of a function or module change.
• Repository onboarding: identify key modules, boundaries, ownership, and hotspots without manually opening every file.
• Architecture review: surface candidate cycles, bottlenecks, tightly coupled modules, dead functions, large classes, and orphan files.
• Incident investigation: locate definitions and trace static relationships around an error, component, or code path.

How it works

flowchart LR
    repo_source["Approved local repository"] --> static_parser["Static parser"]
    repo_source --> git_history["Local Git history"]
    static_parser --> evidence_map["Code graph with coverage and provenance"]
    git_history --> evidence_map
    evidence_map --> mcp_interface["Local MCP server or CLI"]
    mcp_interface --> consumer["Developer or MCP client"]

Loading

The graph is static evidence, not runtime proof. Framework wiring, reflection, dependency injection, dynamic imports, and dynamic dispatch can be unresolved. CodebaseCartographer preserves that distinction in its results: unresolved and ambiguous mean it could not prove a single local target, not that a relationship does not exist.

Requirements

• Python 3.11 or newer
• pipx for the recommended installation method
• Git is optional, but enables Git context, hotspot analysis, co-change data, and safe cache reuse

Install

Install the runtime

If needed, install pipx and make its application directory available on your PATH:

python -m pip install --user pipx
python -m pipx ensurepath

Open a new terminal, install CodebaseCartographer, and verify that the MCP launcher is available:

pipx install "git+https://github.com/vikky781/codebase-cartographer.git"
python -c "import shutil; assert shutil.which('cartographer-mcp'), 'cartographer-mcp is not on PATH'"

For local development, clone the repository and install the development extras:

git clone https://github.com/vikky781/codebase-cartographer.git
cd codebase-cartographer
python -m pip install -e ".[dev]"

Install the Codex plugin

Add this repository as a Codex plugin marketplace, restart the desktop app, then install Codebase Cartographer Local from Plugins:

codex plugin marketplace add vikky781/codebase-cartographer --ref main
codex plugin marketplace list

The plugin launches the installed cartographer-mcp executable over local standard input/output. If the desktop host does not inherit your PATH, configure the MCP server with the launcher’s absolute path. See local MCP setup and troubleshooting for Codex, Claude Code, and Antigravity configuration details.

Quick start

Start a fresh MCP-client session for the repository you want to inspect, then ask it to analyze an absolute path:

Use CodebaseCartographer to analyze this repository:
C:\absolute\path\to\my-repository

First summarize coverage and warnings. Then explain the architecture,
the most important modules, and what I should inspect before making changes.

Call analyze_repo first in every new server session. Re-run it after meaningful repository changes so the graph reflects current source and Git state.

For a large repository, analyze only the area you are changing:

Analyze C:\absolute\path\to\my-repository with scope "src/payments".
Clearly label the result as partial and do not infer facts about files outside that scope.

A scoped analysis is intentionally partial. Its response sets is_partial and records analysis_scope, coverage, and warnings; conclusions about files outside the scope require a broader analysis.

MCP tools

Tool	Purpose
analyze_repo	Parse a repository and build or load its graph. Returns coverage, entity and edge counts, languages, health candidates, and warnings. Call this first.
search_graph	Find matching modules, classes, or functions and inspect their immediate graph neighbors.
trace_flow	Traverse static caller and callee relationships in a forward, backward, or bidirectional direction.
find_issues	Identify static candidates for circular dependencies, dead functions, large classes, bottlenecks, orphan files, and coupling.
get_metrics	Report structural importance, centrality, static line span, coupling, ownership, and Git hotspots.
visualize	Generate Mermaid architecture, dependency, layer, call-flow, and Git-hotspot diagrams.
get_git_context	Return local authorship, commit history, file age, and co-change context for an analyzed file.

Typical prompts:

Goal	Prompt
Understand a repository	“Analyze this repository, summarize its architecture, and identify the modules I should learn first.”
Plan a change	“Before changing PaymentService.process_refund, trace callers and callees, identify affected modules and tests, show Git context, and separate facts from unknowns.”
Investigate a failure	“Search for InvalidStateError, trace the surrounding static flow in both directions, and identify the most relevant files to inspect.”
Review design risk	“Find cycle, coupling, bottleneck, and orphan-file candidates. State which findings need runtime validation.”
Understand ownership	“Show Git context for src/payments/service.py: recent authors, commits, and frequently co-changed files.”

Command-line interface

The same analysis engine is available without an MCP client:

cartographer analyze /absolute/path/to/repository --scope src --no-cache

Query commands load the repository specified by --repo before running:

cartographer --repo /absolute/path/to/repository search PaymentService --type class
cartographer --repo /absolute/path/to/repository trace PaymentService.process_refund --direction both
cartographer --repo /absolute/path/to/repository issues
cartographer --repo /absolute/path/to/repository metrics summary

Run cartographer --help or cartographer <command> --help for the full command reference.

Supported analysis

Source files	Analysis depth	Important boundary
Python (.py)	Tree-sitter parsing of entities and imports, with conservative local call resolution	Dynamic dispatch and framework wiring can still be missed.
JavaScript, TypeScript, TSX	Tree-sitter parsing with conservative ES-module import and call evidence	CommonJS, dynamic module loading, decorators, and injection are not fully resolved.
Java, Go, Rust, Ruby, PHP, C/C++, C#, Swift, Kotlin, Scala	Regex-based declaration and import inventory	No dependable call graph; treat results as an exploratory index.

complexity currently means the static line span of a Tree-sitter entity. It is not cyclomatic complexity and should not be used as a defect-risk score.

Interpreting results

• Static issue findings are candidates, not verdicts. Confirm framework routes, callbacks, reflection, generated code, runtime configuration, and plugin wiring before acting.
• unresolved or ambiguous does not mean absent. It means static analysis could not prove one local target.
• Git context depends on local history. Shallow clones cannot provide reliable long-term ownership or co-change evidence.
• Partial scans are partial. Check analysis_scope, is_partial, coverage, and warnings before drawing broad conclusions.

Privacy and cache behavior

• Source parsing, graph construction, and Git inspection run locally.
• CodebaseCartographer does not execute the analyzed application or make application-level API calls.
• By default, a valid full-repository analysis may be cached at .cartographer_cache/graph_cache.json inside the analyzed repository.
• Cache reuse is skipped for a dirty or untracked Git working tree, and the response explains why.
• Use use_cache=false through MCP or --no-cache through the CLI to avoid both reading and writing the graph cache.
• MCP tool responses are delivered to the configured host and model. Review that host’s data settings before analyzing sensitive code.

Development

Run formatting and tests before contributing:

ruff check src tests
python -m pytest tests/ -v --tb=short

See CONTRIBUTING.md for contribution guidelines, SECURITY.md for the security policy, and docs/LOCAL_MCP.md for MCP installation and troubleshooting.

License

CodebaseCartographer is released under the MIT License.