CodeMap MCP — v3.0.0

Read-Only Repository Intelligence for Engineering Teams

CodeMap is a Model Context Protocol (MCP) server that connects to any Python Git repository, reads the code structure, and delivers deep engineering insights on demand — without making a single change to the codebase.

---

Quick Start

1. Install dependencies

pip install mcp networkx anthropic pyyaml

2. Set your API key (for LLM-powered prose output)

export ANTHROPIC_API_KEY=sk-ant-...

Structural output (Mermaid diagrams, tables, blast radius, dead code, etc.) works without an API key. The LLM is only used for natural-language prose summaries.

3. Configure your MCP client (Claude Desktop example)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "python",
      "args": ["/absolute/path/to/codemap_mcp/server.py"]
    }
  }
}

4. Ask questions

• "Give me a roadmap of the payments folder" → generate_roadmap
• "How is process_payment triggered?" → generate_roadmap with question
• "Find all classes named View" → search_symbol
• "Show me the file tree" → discover_structure
• "Show me the content of payments/services.py" → read_file
• "Explain this Python traceback" → explain_error
• "What does this PR change?" → explain_pr

---

MCP Tools (6 Total)

Tool	Description
discover_structure	Walk repo, return structured file tree with stats
read_file	Return raw content of a single file (path-validated)
search_symbol	Search for classes/functions/imports via AST (case-insensitive)
generate_roadmap	Full roadmap: prose + key files table + Mermaid + interactive HTML map
explain_error	Parse Python traceback and explain the error with local code context
explain_pr	Analyse a git diff: changed symbols, blast radius, affected HTTP routes

All tools are read-only. No file in the target repository is ever created, modified, or deleted. Temporary analysis files (HTML maps) are written to .codemap_temp/ only.

---

What generate_roadmap Produces

A single call generates a complete engineering report including:

Section	Description
HTTP Entry Points	Django / Flask / FastAPI route table
Key Files	File size + role table
Call Chain	BFS call graph with conditional edge labels (if, else, try/except)
Blast Radius	Symbols that would be affected if the scope changes
Git Ownership	git blame author summary per file
Git History	Recent commit activity per file
Import Graph	File-level import cycles + most-imported modules
Glossary	Auto-generated symbol dictionary from docstrings
Onboarding Checklist	How to run the project (detects Django/FastAPI/Celery)
Dead Code Detector	Functions defined but never called anywhere
Test Coverage Map	Static coverage % without running tests
Data Flow Tracing	Where a named field (e.g. user_id) is produced, saved, read, and sent
Feature Dependency Graph	Package-level circular dependency detection
Interactive HTML Map	Self-contained Cytoscape.js call graph (saved to .codemap_temp/)
Mermaid Diagram	Copy-pasteable call graph diagram

---

Optional Configuration

Place a .codemap.yaml in your repository root:

ignore:
  - tests/
  - migrations/
  - __pycache__/
  - .venv/

entry_hints:
  - manage.py
  - app/main.py

feature_map:
  payments: payments/
  auth: accounts/
  notifications: notifications/

max_file_size_kb: 200
max_depth: 15

# Override the Claude model used for LLM prose (optional)
llm_model: claude-sonnet-4-20250514

CodeMap works correctly without this file — it auto-ignores __pycache__, .git, and .venv.

---

Architecture

server.py               ← MCP entry point — registers 6 tools
config.py               ← .codemap.yaml loader with smart defaults

tools/
  discover.py           ← discover_structure tool
  read_file.py          ← read_file tool
  search_symbol.py      ← search_symbol tool
  generate_roadmap.py   ← generate_roadmap tool (orchestrates full pipeline)
  explain_error.py      ← explain_error tool
  explain_pr.py         ← explain_pr tool (V3 — PR diff impact analysis)

analysis/
  ast_parser.py         ← Python ast module — symbols, imports, call edges, conditions
  call_graph.py         ← Depth-limited BFS/DFS with conditional edge labels
  file_walker.py        ← os.walk + pathlib (read-only, ignore rules)
  url_scanner.py        ← Django / Flask / FastAPI route scanner
  import_graph.py       ← File-level import dependency graph + cycle detection
  signal_scanner.py     ← Django signal connect/receiver scanner
  blast_radius.py       ← Impact set calculator for changed symbols
  ownership.py          ← git blame author mapping per file
  git_context.py        ← git log recent commit history per file
  remote_repo.py        ← git clone to temp dir (context manager, auto cleanup)
  glossary.py           ← Auto-glossary from docstrings
  checklist.py          ← Onboarding checklist (detects Django/FastAPI/Celery)
  dead_code.py          ← Unreferenced symbol detector
  test_coverage.py      ← Static test coverage map (no runtime needed)
  data_flow.py          ← Field-level data flow tracer (produce/db_write/read/send)
  feature_dependency.py ← Package dependency graph + circular import detection (V3)
  utils.py              ← Shared query-analysis helpers

llm/
  summarizer.py         ← Anthropic Claude API + timeout/retry + configurable model
  prompts.py            ← All prompt templates

output/
  markdown.py           ← Markdown formatting helpers
  mermaid.py            ← Mermaid diagram generator
  html_map.py           ← Interactive Cytoscape.js HTML map generator (V3)

tests/
  test_codemap.py       ← 51+ unit tests covering all modules

---

Running Tests

PYTHONPATH=. python3.11 -m unittest discover -s tests -v

---

Features by Version

V1 — Core

• Python repositories only
• Conditional call tracing: if/else, try/except, while, assert
• Dynamic call detection with explicit [DYNAMIC CALL] flagging
• Django / Flask / FastAPI HTTP route scanning
• Depth-limited BFS traversal (max 20 hops)
• Structural output (Mermaid + tables) works without LLM API key

V2 — Engineering Context

• Django signal scanner
• Celery async task detection (.delay() / .apply_async())
• Blast radius analyser
• Git ownership mapping (git blame)
• Git history context (git log)
• Remote repository support (auto-clone + cleanup)
• Glossary generator
• Onboarding checklist
• Dead code detector
• Static test coverage map
• Data flow tracer

V3 — Visual & Impact Analysis

• Interactive HTML call graph (Cytoscape.js, dagre layout, searchable)
• Feature/package dependency graph with circular dependency detection
• PR diff impact analysis (explain_pr) — git diff → blast radius + affected routes

---

Limitations

Since CodeMap operates strictly via read-only static AST analysis (no runtime execution), it has the following constraints:

• Instance Method Calls: service.create() is resolved as "service.create" — it cannot be linked to PaymentService.create without runtime type information.
• Dynamic Variable Dispatch: func = select_func(); func() cannot be statically resolved.
• Third-Party Libraries: External package methods are listed as callees but not traced inside their source code.
• Test Coverage: The static coverage map uses name matching (not runtime instrumentation), so it may over- or under-count compared to pytest-cov.

---

CodeMap MCP v3.0.0 — Read-only repository intelligence for engineering teams.