<!-- mcp-name: io.github.bbajt/codemap-mcp -->

CodeMap — Turn Your AI Agent Into a Semantic Dragon

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

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