codemap-mcp 1.3.2

CodeMap — Turn Your AI Agent Into a Semantic Dragon

dotnet tool install --global codemap-mcp --version 1.3.0

Stop feeding your AI agent raw source files. Give it a semantic index instead.

CodeMap is a Roslyn-powered MCP server that lets AI agents navigate C# codebases by symbol, call graph, and architectural fact — instead of brute-reading thousands of lines of source code. One tool call. Precise answer. No context flood.

Average token savings: 90%+ versus reading files directly.

---

The Problem

An AI agent working on a C# codebase without CodeMap does this:

Agent: I need to find who calls OrderService.SubmitAsync.
→ Read OrderService.cs       (3,600 tokens)
→ Read Controllers/...       (3,600 tokens)
→ Grep across src/           (another 3,600 tokens)
→ Maybe find it. Maybe not.

With CodeMap:

refs.find { symbol_id: "M:MyApp.Services.OrderService.SubmitAsync", kind: "Call" }
→ 220 tokens. Exact file, line, and excerpt for every call site. Done.

That's 93.9% fewer tokens for a task agents do dozens of times per session. On a real production codebase (100k+ lines), savings are 95–99%+.

---

What It Does

CodeMap builds a persistent semantic index from your solution file using Roslyn — the same compiler that powers Visual Studio. Supports both .sln (all Visual Studio versions) and .slnx (VS 2022 17.12+ / .NET SDK 9+) solution formats. The index captures:

• Every symbol (classes, methods, properties, interfaces, records)
• Every call relationship and reference (who calls what, where)
• Type hierarchy (inheritance chains, interface implementations)
• Architectural facts extracted from code: HTTP endpoints, config keys, DB tables, DI registrations, middleware pipeline, retry policies, exception throw points, structured log templates

All of this is exposed via 26 MCP tools that any MCP-compatible AI agent can call. Starting from v1.3, CodeMap also navigates DLL boundaries — lazily resolving NuGet and SDK symbols on first access, with optional ICSharpCode.Decompiler source reconstruction and cross-DLL call graphs.

---

The Transformation

Here's what changes when you give an agent CodeMap:

Without CodeMap	With CodeMap
grep -rn "OrderService" src/	symbols.search { query: "OrderService" }
Read 5 files to understand a method	symbols.get_context — card + source + all callees in one call
Manually trace call chains across files	graph.trace_feature — full annotated tree, one call
Hope grep finds the right interface impl	types.hierarchy — base, interfaces, derived types, instant
Read the whole file to find config usage	surfaces.list_config_keys — every IConfiguration access, indexed
Diff two commits by reading changed files	index.diff — semantic diff, rename-aware, architectural changes only

The agent stops reading your codebase and starts understanding it.

---

Showpiece: graph.trace_feature

The most powerful tool. Replaces 5–10 manual calls with one:

graph.trace_feature {
  "repo_path": "/path/to/repo",
  "entry_point": "M:MyApp.Controllers.OrdersController.Create",
  "depth": 3
}

Returns an annotated call tree with architectural facts at every node:

OrdersController.Create  [POST /api/orders]
  → OrderService.SubmitAsync
      → [Config: App:MaxRetries]
      → [DI: IOrderService → OrderService | Scoped]
      → Repository<Order>.SaveAsync
            → [DB: orders | DbSet<Order>]
            → [Retry: WaitAndRetryAsync(3) | Polly]

One query. Full feature flow. Every config key touched, every table written, every retry policy applied — surfaced automatically from the index.

---

Token Savings Benchmark

Measured across 24 canonical agent tasks on a real .NET solution:

Task	Raw Tokens	CodeMap	Savings
Find a class by name	3,609	248	93%
Get method source + facts	3,609	336	91%
Find all callers (refs.find)	3,609	220	94%
Caller chain depth=2	3,609	287	92%
Type hierarchy	3,609	200	94%
List all HTTP endpoints	3,609	360	90%
List all DB tables	3,609	169	95%
Workspace staleness check	3,609	62	98%
Baseline build (cache hit)	~30s Roslyn	~2ms pull	∞
Average			90.4%

Raw tokens = reading all source files. On production codebases (100k+ lines), savings reach 95–99%+.

Run it yourself:

dotnet test --filter "Category=Benchmark" -v normal

---

26 Tools Across Six Categories

Discover

Tool	What it does
symbols.search	FTS search by name, kind, namespace, or file path
code.search_text	Regex/substring search across source files — returns file:line:excerpt
symbols.get_card	Full symbol metadata + architectural facts + source code
symbols.get_context	Card + source + all callees with source — deep understanding in one call
symbols.get_definition_span	Raw source only, no overhead
code.get_span	Read any source excerpt by line range

Navigate

Tool	What it does
refs.find	All references to a symbol, classified (Call, Read, Write, Implementation…)
graph.callers	Depth-limited caller graph — who triggers this?
graph.callees	Depth-limited callee graph — what does this orchestrate?
graph.trace_feature	Full annotated feature flow with facts at every node
types.hierarchy	Base type, interfaces implemented, and all derived types

Architecture

Tool	What it does
codemap.summarize	Full codebase overview: endpoints, DI, config, DB, middleware, logging
codemap.export	Portable context dump (markdown/JSON, 3 detail levels) for any LLM
index.diff	Semantic diff between commits: symbols added/removed/renamed, API changes
surfaces.list_endpoints	Every HTTP route (controller + minimal API) with handler and file:line
surfaces.list_config_keys	Every IConfiguration access with usage pattern
surfaces.list_db_tables	EF Core entities + [Table] attributes + raw SQL table references

Workspace

Tool	What it does
workspace.create	Isolated overlay for in-progress edits
workspace.reset	Clear overlay, back to baseline
workspace.list	All active workspaces with staleness, SemanticLevel, and fact count
workspace.delete	Remove a workspace
index.refresh_overlay	Re-index changed files incrementally (~63ms)

Index Management

Tool	What it does
index.ensure_baseline	Build the semantic index (idempotent, cache-aware)
index.list_baselines	All cached baselines with size, age, and commit
index.cleanup	Remove stale baselines (dry-run default)

Repo

Tool	What it does
repo.status	Git state + whether a baseline exists for current HEAD

---

Workspace Mode — See Your Own Edits

CodeMap tracks uncommitted changes via an overlay index. Every agent session gets its own isolated workspace:

1. index.ensure_baseline   → index HEAD once
2. workspace.create        → agent gets isolated overlay
3. Edit files on disk
4. index.refresh_overlay   → re-indexes only changed files (~63ms)
5. Query with workspace_id → results include your in-progress code

Three consistency modes:

• Committed — baseline index only (default, no workspace needed)
• Workspace — baseline + your uncommitted edits merged
• Ephemeral — workspace + virtual file contents (unsaved buffer content)

---

Multi-Agent Supervisor Support

Running multiple agents in parallel? CodeMap has you covered:

• Each agent gets its own isolated workspace — no cross-contamination
• workspace.list shows every workspace: IsStale, SemanticLevel, fact count
• Stale detection fires when a workspace's base commit diverges from HEAD
• Supervisor can inspect, clean up, or re-provision any agent's workspace

---

Self-Healing Under Broken Builds

When a file doesn't compile, CodeMap doesn't drop references. It stores unresolved edges with syntactic hints. When compilation succeeds again (after a fix), a resolution worker automatically upgrades them to fully-resolved semantic edges.

refs.find returns both. Filter with resolution_state: "resolved" if you need certainty.

---

DLL Boundary Navigation

CodeMap resolves DLL symbols lazily on first agent access — NOT_FOUND at a DLL boundary triggers automatic extraction rather than a dead end.

Two levels, both permanent (cached in baseline DB):

Level	Trigger	What you get	Cost
1 — Metadata stub	Any NOT_FOUND query	Method signatures, XML docs, type hierarchy	~1–5ms (once)
2 — Decompiled source	symbols.get_card with include_code: true	Full reconstructed C# source via ICSharpCode.Decompiler	~10–200ms (once)

After Level 2, cross-DLL call graph edges are extracted so graph.callees and graph.trace_feature traverse INTO and THROUGH DLL code seamlessly.

source discriminator in symbols.get_card response:

• "source_code" — symbol is from your own source
• "metadata_stub" — Level 1 only (decompilation unavailable)
• "decompiled" — Level 2 source reconstructed and ready

graph.trace_feature applies a max_lazy_resolutions_per_query budget (default 20) when encountering previously-unseen DLL types to bound decompilation latency.

---

Shared Baseline Cache

Index once, reuse everywhere — across machines, CI, Docker containers:

export CODEMAP_CACHE_DIR=/shared/codemap-cache

• index.ensure_baseline pulls from cache first (~2ms vs ~30s Roslyn build)
• Auto-push after every new baseline build
• Self-healing: corrupt cache entries are detected and overwritten
• Zero config when CODEMAP_CACHE_DIR is unset — all cache ops are no-ops

---

Self-Hosting Validated

CodeMap indexes its own 17-project solution (5,112 symbols, 23,540 references). All 26 tools verified against real-world architectural complexity. Self-hosting exposed and fixed cross-project reference bugs, CamelCase FTS edge cases, and multi-line SQL extraction gaps. Every tool in this README was tested against the codebase that implements it.

---

Installation

.NET Global Tool — NuGet (recommended)

dotnet tool install --global codemap-mcp --version 1.3.0
codemap-mcp --version

Requires .NET 9 runtime. Install it from dot.net if needed.

NuGet package: nuget.org/packages/codemap-mcp

Self-Contained Binary (no .NET required)

Build from source — produces a single executable, batteries included:

# Linux/macOS
./scripts/build-release.sh 1.3.0

# Windows PowerShell
.\scripts\build-release.ps1 1.3.0

Outputs dist/win-x64/, dist/linux-x64/, dist/osx-arm64/. Drop the binary anywhere and run it — no runtime, no SDK, no install step. No trimming (Roslyn uses runtime reflection).

Docker

docker build -t codemap-mcp .
docker run -i \
  -v /path/to/your/repo:/repo:ro \
  -v /path/to/cache:/cache \
  codemap-mcp

-i is required — MCP uses stdio transport. Without it the container gets immediate EOF.

Uses the .NET SDK base image (~800MB) because MSBuildWorkspace needs MSBuild at runtime for index.ensure_baseline. Mount a cache volume (-v /path/to/cache:/cache) to avoid rebuilding the index on every container start.

---

Connect to Your AI Agent

Claude Code (Claude Desktop / claude.ai)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap-mcp"
    }
  }
}

Any MCP-Compatible Client

CodeMap speaks standard MCP over stdin/stdout (JSON-RPC 2.0). Any MCP client works.

CLAUDE.md Integration

Drop the instruction block from docs/CLAUDE-INSERT.MD into your project's CLAUDE.md to wire up automatic CodeMap usage for any Claude agent working on that project. The block includes the session startup sequence, a tool substitution decision table, and the "refresh before grep" rule that keeps agents in semantic mode.

---

Architecture

Your Git repo              CodeMap Server
     │                          │
     │  repo_path               │
     ├─────────────────────────►│ GitService         (repo identity, HEAD SHA)
     │                          │      │
     │  solution.sln/.slnx      │      ▼
     ├─────────────────────────►│ RoslynCompiler     (MSBuildWorkspace → full semantic model)
     │                          │      │
     │                          │      ▼
     │                          │ Extractors         (Symbols + Refs + TypeRelations + Facts)
     │                          │      │
     │                          │      ▼
     │                          │ BaselineStore      (SQLite WAL + FTS5, one DB per commit)
     │                          │      │        ↕
     │                          │      │   SharedCache  (file-based, optional)
     │                          │      ▼
     │  your uncommitted edits  │      ▼
     ├─────────────────────────►│ OverlayStore       (SQLite per workspace, incremental)
     │                          │      │
     │                          │      ▼
     │                          │ MergedQueryEngine  (baseline + overlay, transparent merge)
     │                          │      │
     │  MCP tool call           │      ▼
     ├─────────────────────────►│ McpServer          (stdio JSON-RPC 2.0, 26 tools)
     │                          │      │
     │  JSON response           │      ▼
     │◄─────────────────────────│ ResponseEnvelope   (answer + evidence + timing + token savings)

Layer dependencies (enforced at build time — violations are build errors):

CodeMap.Core      ← zero dependencies (domain types + interfaces)
CodeMap.Git       ← Core (LibGit2Sharp)
CodeMap.Roslyn    ← Core (Roslyn 5.x + MSBuildWorkspace)
CodeMap.Storage   ← Core (SQLite + WAL + FTS5)
CodeMap.Query     ← Core + Storage (query engine + cache + overlay merge)
CodeMap.Mcp       ← Core + Query (MCP tool handlers)
CodeMap.Daemon    ← ALL (DI composition root, the executable)

---

Observability

Every response includes:

• Per-phase timing — cache_lookup_ms, db_query_ms, ranking_ms
• Token savings — tokens saved and cost avoided vs raw file reading
• Semantic level — Full / Partial / SyntaxOnly (index quality signal)
• Overlay revision — which workspace revision answered the query

Structured logs to ~/.codemap/logs/codemap-{date}.log (daily rotation, JSON lines). Cumulative savings to ~/.codemap/_savings.json (persists across restarts). Config at ~/.codemap/config.json (log level, cache dir, budget overrides).

---

Documentation

Doc	What's in it
docs/CLAUDE-INSERT.MD	Copy-paste block for CLAUDE.md — wires up agent to use CodeMap
docs/CODEMAP-AGENT-GUIDE.MD	Full agent operating guide: startup, refresh, query patterns, common mistakes
docs/DEVELOPER-GUIDE.MD	How to add tools, extractors, storage methods
docs/ARCHITECTURE-WALKTHROUGH.MD	Request traces, data model, decision log
docs/API-SCHEMA.MD	Every type definition and MCP tool contract
docs/SYSTEM-ARCHITECTURE.MD	Component design, DB schema, query model

---

Build & Test

# Build (zero warnings enforced)
dotnet build -warnaserror

# Fast unit tests
dotnet test --filter "Category!=Integration&Category!=Benchmark"

# Integration tests (requires MSBuild)
dotnet test --filter "Category=Integration"

# Token savings benchmark
dotnet test --filter "Category=Benchmark" -v normal

# Performance microbenchmarks (BenchmarkDotNet)
cd tests/CodeMap.Benchmarks && dotnet run -c Release

---

26 MCP tools. 90%+ token savings. Roslyn-grade semantics. DLL boundary navigation. .sln + .slnx support. v1.3.0. Your agent deserves better than grep.