
CodeMap
io.github.bbajt由 GitHub 账号 bbajt 发布v1.4.0更新于 Oct 24, 2026
Roslyn-powered MCP server for C#/VB.NET. Query symbols, call graphs, and facts. 90%+ token savings.
概览
本地运行的 Roslyn 驱动 MCP 服务器,为 C#、VB.NET 和 F# 解决方案建立语义索引,让助手查询符号、调用图和架构信息。
- 可以做什么
- 搜索与读取代码:按名称、种类、命名空间或路径查找符号,执行文本或正则搜索,获取符号卡片、上下文、定义和行范围,并附带架构事实。导航关系:列出引用、调用者与被调用者图、功能调用链和类型层级,包括经接口分派的调用者。查看架构:汇总代码库,列出 HTTP 端点、配置键和 EF Core 表,并生成提交间的语义差异。管理工作区:为未提交的修改创建隔离覆盖层、增量刷新、列出和删除。管理索引:构建、列出、清理和移除基线,并报告与基线对应的 git 状态。
- 适用场景
- 适合助手在 .NET 解决方案上查找调用者、追踪功能流程,或梳理端点、配置键和数据库表,而不必通读整个文件。在大型 C#/VB.NET 代码库上收益最大,可减少反复 grep 和读文件造成的上下文消耗。
- 运行要求
- 以本地 stdio 进程运行,通过 .NET 全局工具 codemap-mcp 安装,需要 .NET 10 SDK。仓库中需有 .sln 或 .slnx 解决方案文件;全新克隆需先执行 dotnet restore 再建索引。可选设置 CODEMAP_CACHE_DIR 为绝对路径或以 ~/ 开头的路径,用于共享基线缓存。
安装
在 SourceWeft 中
- 打开 控制台中的 CodeMap,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
CodeMap — Turn Your AI Agent Into a Semantic Dragon
[NuGet] [NuGet Downloads] [.NET] [MCP Server] [C%23] [VB.NET] [F%23] [GitHub Stars] [License]
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#, VB.NET, and F# 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.
Install via Claude Code or manually
The fastest way to install is to paste the prompt below into a Claude Code shell. Claude will check your environment, install the tool, and register it as an MCP server — no manual steps needed.
Check whether .NET 10 SDK is installed by running
dotnet --version. If the reported version is below 10.0, install it: on Windows runwinget install Microsoft.DotNet.SDK.10, on macOS/Linux download from https://dotnet.microsoft.com/download/dotnet/10.0. Verify withdotnet --versiononce done. Once .NET 10 is confirmed, install CodeMap: ifcodemap-mcpis not yet installed rundotnet tool install --global codemap-mcp, otherwise rundotnet tool update --global codemap-mcpto get the latest version. Verify the binary is reachable withcodemap-mcp --version. Finally, register it as a global MCP server in Claude Code by runningclaude mcp add codemap-mcp codemap-mcp --scope userand confirm it appears in the output ofclaude mcp list.
Or install manually:
Requires .NET 10 (LTS). If you're working on a C# or VB.NET codebase you almost certainly have it already — check with dotnet --version.
Upgrading to v2.10.0
No re-index and no index format change. What you may notice:
index_cleanupandindex_remove_reponeedrepo_path. They delete data, so they no longer fall back to the only registered repo. Cleanup now protects the baseline of every workspace in every CodeMap process, and a baseline that is in use is never half-deleted (it's reported inskipped_in_use).- References from Blazor components, MVC views and Razor Pages are back (missing since v2.5.2).
graph_callers/refs_findon a service or model now include uses written in.razor/.cshtmlfiles. They appear when a baseline is next built (any new commit). - Idle memory is returned. After indexing, an idle server gives most of the build's memory back (nopCommerce: 2.9 GB → 1.1 GB after 2.5 minutes, 0.2 GB after 13 minutes).
config.jsonhas two keys,log_levelandshared_cache_dir.shared_cache_dirnow works (it was never read);budget_overridesis gone (it never had an effect). Unknown keys give one warning in the log. A relativeshared_cache_dirstops startup, as a relativeCODEMAP_CACHE_DIRdoes.- Boolean parameters sent as strings (
"include_code": "false") work instead of returningINTERNAL_ERROR.
Details: CHANGELOG [2.10.0].
Upgrading to v2.9.0: new tool names
Tool names use underscores now (symbols_search instead of the dotted form), because LLM APIs don't allow dots in tool names. Claude Code users see no change: Claude Code already showed mcp__codemap__symbols_search. The old dotted names keep working until v2.11.0 at the earliest, for clients and scripts that still send them. Each such call adds a note naming the new tool. If your project's CLAUDE.md contains the CodeMap block, refresh it from docs/CLAUDE-INSERT.MD.
Upgrading from v1.x
v2.0.0 uses a new binary storage engine (memory-mapped segments instead of SQLite). Your old .db baselines are not migrated — run index_ensure_baseline once per repo to rebuild. The old ~/.codemap/baselines/ folder is unused and can be deleted. The SQLite engine was removed in v2.1.0.
The Problem
An AI agent working on a C# codebase without CodeMap does this:
With CodeMap:
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 — auto-discovered when solution_path is omitted (prefers .slnx). Short commit SHAs are auto-expanded. 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 28 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.
Supported languages: C#, VB.NET, and F#. Mixed-language solutions (.sln / .slnx containing C#, VB.NET, and F# projects) are indexed in a single pass. All 28 MCP tools work identically for symbols from any language. C# and VB.NET use Roslyn's MSBuildWorkspace; F# uses FSharp.Compiler.Service (MSBuildWorkspace doesn't support .fsproj). F# architectural fact extractors (endpoints, DI, config) are not yet implemented — symbol search, call graphs, references, and type hierarchy all work.
Blazor / Razor (v2.5.0+): .razor components are indexed via the Razor source generator. ComponentBase-derived classes appear in symbols_search. @page routes surface in surfaces_list_endpoints with a PAGE HTTP method. [Inject] and [Parameter] properties emit dedicated RazorInject / RazorParameter facts. Since v2.10.0, code written in components, MVC views and Razor Pages is part of the reference graph: graph_callers on a service method shows the component or view that calls it. The generator's own scaffolding (tag-helper plumbing) is left out.
Multi-target projects (v2.5.1+): <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks> previously produced one extraction per TFM (3× duplication). CodeMap now collapses to a single extraction on the highest-ranked TFM, with ProjectDiagnostic.TargetFrameworks listing every TFM in the group. Symbol counts on heavily multi-targeted Blazor libraries drop 60–80%.
Interface-aware graph_callers (v2.6.0+): in DI-dispatched codebases (most production .NET) graph_callers on a concrete method silently under-reported because real call sites resolve through the registered interface. CodeMap now detects interface implementation at query time and surfaces an interface_implementation_hint listing the interface members and an estimated count of additional callers routed through them. Pass follow_interface: true to union those into the result (deduped by from_symbol). No baseline-format change, no re-index required. Handles both implicit and explicit interface implementations.
Indexing perf + correctness (v2.5.2): large reduction in indexing wall-clock by skipping auto-generated trees (*.g.cs, *.Designer.cs, files with <auto-generated>, paths under obj/), short-circuiting type-position identifier classification (typeof / generic args / base lists / attributes), and parallelizing Pass-2 reference & fact extraction across projects. Validated on a 9-repo Blazor corpus: Blazorise drops from 408 s → 95 s (−77 %), ant-design-blazor from 47 s → 25 s (−47 %), OrchardCore (single-target sentinel) from 131 s → 96 s (−27 %), and a 78-csproj distributed-database project (ByTech.Bedrock) indexes in 27 s with an 11.2× Pass-2 parallel speedup. Five query-correctness bugs also fixed: symbols_search browse-by-kinds now honours namespace / file_path / project_name filters; workspace-mode namespace filter is case-insensitive (matches committed mode); refs_find cache key includes resolution_state; workspace browse-by-kinds now includes overlay-new symbols; codemap_guide's decision table no longer advertises surfaces_list_di_registrations (which was never a registered tool).
The Transformation
Here's what changes when you give an agent CodeMap:
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:
Returns an annotated call tree with architectural facts at every node:
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:
Raw tokens = reading all source files. On production codebases (100k+ lines), savings reach 95–99%+.
Run it yourself:
28 Tools Across Six Categories
Discover
Navigate
Architecture
Workspace
Index Management
Repo
Workspace Mode — See Your Own Edits
CodeMap tracks uncommitted changes via an overlay index. Every agent session gets its own isolated workspace:
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? What works today:
- Each workspace is isolated: agents that use different
workspace_ids never see each other's edits workspace_listshows 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
What to know (measured in the multi-agent benchmark, docs/CODEMAP-MULTI-AGENT-SCALING-FINDINGS.md):
- One CodeMap process per agent. Each MCP client or sub-agent starts its own server, so memory grows with the number of agents: roughly 0.3–0.5 GB per process on small and medium solutions, 2.5–4 GB on large ones. Every process builds the same baseline itself the first time, and concurrent builds slow each other down. A shared host is the planned fix (ADR-048).
- A workspace can't be shared across processes. If another CodeMap process holds that
workspace_id, the call returnsWORKSPACE_IN_USE(retryable): retry, or give each agent its own ID. - Agents in fresh worktrees must restore first. A new clone or
git worktree addhas no restore output; rundotnet restorebeforeindex_ensure_baseline, or the index is incomplete (reported assemantic_level: partial, L-12). - Cleanup is safe across agents (v2.10.0).
index_cleanupnever removes a baseline that any agent's workspace uses, in any process, and never deletes a baseline another process has open.index_remove_reporefuses (WORKSPACE_IN_USE) while another process has a workspace open in the repo. - An idle process gives memory back (v2.10.0). Two minutes after indexing, the server compacts its heap; after 10 minutes without an overlay refresh it also drops the cached Roslyn solution (the next refresh reopens it). This lowers each process's idle cost; the per-process multiplication stays until the shared host.
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):
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:
or, in config.json (see Observability): { "shared_cache_dir": "/shared/codemap-cache" }.
index_ensure_baselinepulls from cache first (~2ms vs ~30s Roslyn build)- Auto-push after every new baseline build, except baselines this machine degraded (an unrestored checkout or a source generator that failed to load), since another machine would get an incomplete index
- Self-healing: corrupt cache entries are detected and overwritten
- Precedence:
CODEMAP_CACHE_DIR(whenever set; blank = disabled) >config.jsonshared_cache_dir> disabled. With neither, all cache ops are no-ops - Must be an absolute path or start with
~/; a relative value stops the server at startup (exit code 2), since it would resolve against the client's working directory
v2 Storage Engine — 10x Faster Queries
v2.0.0 replaces SQLite with a custom binary storage engine using memory-mapped segment files. The Roslyn extraction pipeline is unchanged — only the on-disk format is new.
Query speedup (measured across 15 query types on real repos):
Indexing speedup (Roslyn compilation dominates, but I/O is faster):
What changed:
- Baselines stored as contiguous packed binary segments (symbols, edges, files, facts) with mmap reads — no SQL parsing overhead
- Custom search index with tokenized FTS (CamelCase splitting, signature/documentation indexing)
- WAL-backed overlay for workspace mutations (same isolation model)
- Zero native DLL dependencies (no
e_sqlite3.dll)
Validated on 9+ repos including dotnet/roslyn (174K symbols, 768K references), dotnet/fsharp (157K symbols via FCS), and Bitwarden. Zero functional bugs. See docs/ENGINE-COMPARISON-RESULTS.MD for full data.
Self-Hosting Validated
CodeMap indexes its own 18-project solution (5,576 symbols, 20,960 references). All 28 tools verified against real-world architectural complexity. Self-hosting exposed and fixed cross-project reference bugs, CamelCase FTS edge cases, overlay StringId resolution issues, 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)
See the Install via Claude Code or manually section at the top for the one-paste Claude Code prompt and manual steps.
NuGet package: nuget.org/packages/codemap-mcp
Docker
-iis 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:
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.
Tip: Write XML Docs — CodeMap Uses Them
CodeMap indexes /// <summary> XML doc comments on all classes, methods, and
interfaces. They appear in symbols_get_card, symbols_get_context, and
symbols_search results — giving agents intent and context without reading
implementations.
When writing C# code with CodeMap enabled, always add XML doc comments.
This isn't just style — it directly improves every downstream query. Agents
using graph_trace_feature see annotated call trees that read like specs.
codemap_export includes docs in the portable context for other LLMs.
See docs/CODEMAP-AGENT-GUIDE.MD for the full agent workflow guide.
Architecture
Layer dependencies (enforced at build time — violations are build errors):
Observability
Every response includes:
- Per-phase timing —
cache_lookup_ms,db_query_ms,ranking_ms(sub-millisecond on v2) - Token savings — tokens saved and cost avoided vs raw file reading
- Semantic level —
Full/Partial/SyntaxOnly(index quality signal, see below) - Overlay revision — which workspace revision answered the query
- Workspace ID — which workspace context answered (null for committed mode)
When the level isn't Full, index_ensure_baseline's project_diagnostics says why, per project:
compiled: false: the project couldn't be compiled, so it was indexed syntactically.missing_restore_output: the checkout was never restored (fresh clone or git worktree) and packages, sometimes the framework too, are unresolved. Rundotnet restore, then rebuild the baseline (L-12).generator_load_failures: a source generator from a newer .NET SDK couldn't load, so its code (e.g. Razor components) is missing (L-11).
The same level is reported on every later query against that baseline (for baselines built by v2.8.2 or later; older ones don't record these fields).
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, read once at startup. It has two keys:
log_level:Trace,Debug,Information(default),WarningorError.shared_cache_dir: the shared baseline cache, used only whenCODEMAP_CACHE_DIRis unset.
Any other key (a typo, or budget_overrides, which never had an effect and was removed in v2.10.0) is
ignored with one warning in the log.
Data Directory (CODEMAP_HOME)
Everything above lives under one data root, ~/.codemap by default. Set CODEMAP_HOME to move it
(config, logs, store, _savings.json), for example per test run, CI job or sandbox. It must be an
absolute path or start with ~/; a relative value stops the server at startup (exit code 2).
Baselines are stored in <data root>/store/<repoId>/baselines/<commitSha>/ as binary segment files.
Overlays are in <data root>/store/<repoId>/overlays/<workspaceId>/. Use index_list_baselines to inspect
and index_cleanup to reclaim space.
Known Limitations & Coverage Gaps
CodeMap won't surface a hit in every situation a grep would. The most
common reasons are documented in docs/KNOWN-LIMITATIONS.md.
Top items to be aware of:
- Multi-target conditional symbols.
#if NET8_0-only types are invisible — extraction runs on the highest TFM only (L-01). - Legacy MVC
MapControllerRoute— convention-routed actions don't surface insurfaces_list_endpoints. Only attribute routing, minimal API, and Blazor@pageare extracted (L-02). - F# fact extractors not yet wired — F# gets symbols/refs/hierarchy
only; endpoints / DI / config / DB tables don't extract from
.fsprojyet (L-05). - Unrestored checkout — a fresh clone or git worktree has no
obj/project.assets.json, and CodeMap doesn't restore, so package references (sometimes the framework itself) are unresolved. It's reported (missing_restore_output,semantic_level: partial); rundotnet restorebeforeindex_ensure_baseline(L-12). - .NET SDK newer than CodeMap's Roslyn — that SDK's source generators
(e.g. Razor) may not load, and their output is missing. Reported as
generator_load_failures; update CodeMap (L-11). - Fresh clone with no build — Razor source-generator output may be
invisible until you
dotnet buildonce (L-08). - Razor markup-only uses —
@onclick="Save"and a component tag like<Greeting />produce no reference yet, and Razor references point at the generatedobj/…_razor.g.cslines, not the.razorfile (L-15).
When symbols_search returns nothing for code you can see in the
editor, scan KNOWN-LIMITATIONS first before falling back to grep.
Documentation
Build & Test
Performance Reference
What to expect when running CodeMap on your codebase. All v2 engine numbers (default since v2.0.0).
Indexing time by repo size
Subsequent runs on the same commit return immediately (already_existed: true). Incremental overlay refresh (after editing files) takes ~63ms.
Query response time (v2 engine)
Cold times scale with repo size (more symbols = more BFS/join work). Warm times are nearly flat across all repo sizes — L1 cache caps at 10,000 entries with LRU eviction.
Memory footprint (v2 engine)
mmap pages are demand-loaded by the OS — resident memory stays proportional to queries made, not total index size.
Process memory while idle (v2.10.0+)
The server process also holds what Roslyn used to build the index. Since v2.10.0 it gives that memory back
when idle: one compacting GC two minutes after indexing, and the cached solution for overlay refreshes is
dropped after 10 minutes without a refresh. Private memory of one idle server, measured
(PHASE-21-12, docs/benchmarks/phase-21-12/):
Each server logs MEMORY_SNAPSHOT lines (working set, private bytes, GC heap) to ~/.codemap/logs.
28 MCP tools. 90%+ token savings. Roslyn-grade semantics. C#, VB.NET, F#, Blazor/Razor. DLL boundary navigation. .sln + .slnx auto-discovery. v2.10.0 — safe destructive tools across agents, idle memory returned, Razor component and view references, honest config.json. Validated on dotnet/roslyn (174K symbols), dotnet/fsharp (157K symbols), and a 9-repo Blazor corpus including Blazorise, MudBlazor, ant-design-blazor, OrchardCore. Your agent deserves better than grep.
来源:README.MD,提交 1022f6f
工具
0版本历史
1- v1.4.0最新Sep 16, 2026
评分
已满足适用检查项的 40%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
请在仓库或注册中心条目中声明许可证。