codegraph-mcp

本地 MCP 服务器，为 Claude Code（CLI 和 VS Code 扩展）提供可查询的代码库模型——定义了哪些内容、谁调用了什么、什么依赖什么，以及早期会话中决定了什么。没有它，代理每次都得通过 grep 和逐文件阅读重新发现你的架构；有了它，结构性问题就能得到结构性回答：

• 更安全的变更 ——在动函数之前，代理能看到它的影响范围（analyze_impact）、每个调用点（find_callers）、每个提及位置（find_references）以及每个依赖模块（who_imports），而不是去编辑任何 grep 恰好浮出的内容。

• 更快的定位 ——一次 repo_map 调用按导入中心性绘制项目地图；find_symbol 和 semantic_search（“auth token 在哪里验证”）直接定位到正确的代码上。

• 连续性 —— save_note / recall_notes 跨会话（每个仓库）承载决策和注意事项（gotchas）。

• 更便宜的探索 —— 基于以上原因，代理读取的是签名而不是整个文件（file_skeleton、read_symbol），透明代理在连接层面压缩对话历史。 usage_stats 报告实测节省量。

100% 可移植：纯 JavaScript + WASM 语法解析器。无 node-gyp，无原生编译。npm install 在 Windows、macOS 和 Linux 上行为完全一致。

暴露给代理的工具

理解与导航

变更安全

聚焦阅读

记忆与操作

支持的语言：JavaScript、TypeScript、TSX、Python、Go、Rust、Java、Ruby、C、C++、C#、PHP、GDScript。索引器无法提取的文件会被统计并在 repo_map 中报告，因此部分覆盖范围始终可见。

Related MCP server: MCP Context Manager

安装

需要 Node.js ≥ 20 和 Claude Code。Windows / macOS / Linux 相同：

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

就是这样——install 命令会替你运行 claude mcp add，该服务器在 CLI 和 VS Code 扩展中都能工作（它们共享 MCP 配置）。用 claude mcp list 或 Claude Code 中的 /mcp 验证。

服务器索引 它启动时所在的目录（Claude Code 会在项目目录中启动 MCP 服务器），或通过 --root / CODEGRAPH_ROOT 指定的路径。要限制为单个项目而非用户范围，请在那个项目中添加 .mcp.json：

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

卸载：node bin/codegraph-mcp.js uninstall。

零配置

无需 CLAUDE.md 文件或提示词调整：服务器通过 MCP instructions 字段内置了使用指南（“在修改函数之前先运行 analyze_impact，使用 find_symbol 而非 grep，在读取文件前先 file_skeleton，……”），Claude Code 在连接时会自动将其注入代理上下文。安装、注册、完成。

透明代理（保证节省）

上面的 MCP 工具只有在代理选择使用它们时才能节省 token。代理透明化层则以另一种方式工作——它像 ContextForge 一样，位于 Claude Code 和 Anthropic API 之间，并压缩流量，无论代理行为如何：

• 历史去重：当对话包含相同的工具结果（同一文件读取两次、重复命令输出）时，第一次之后每次出现都会被替换为短 stub，然后请求才离开你的机器。第一次出现保持完整，因此模型不会丢失任何实际可用的信息——并且提示前缀缓存被保留（仅新尾部会被重写，因此去重永远不会导致旧轮次缓存未命中）。

• 陈旧读取骨架化：当文件被读取、编辑、再次读取时，历史中较早的完整副本会被替换为其 tree-sitter 骨架（带行范围的导入 + 声明）；最新的读取保持完整原文。非代码文件会退化为头部 + 尾部截断。变换是内容的纯函数，因此并发请求产生完全相同的元数据，提示缓存在一次重写后重新稳定下来。

• 提示词落地：your message 在到达模型之前就被转换——这是安全的方式。词条永远不会被重写；相反地，代理会附加一个明确标注的、关于该消息中提到的标识符的可验证事实块（种类、file:lines、来自元数据的一行文档）。模型起步时就能定向，无需浪费多次工具往返去发现同样的事实。仅精确大小写匹配会落地，只有最新的消息才会获得新的块，且块会被 memoized，因此历史记录能保持字节级稳定，有利于提示缓存。

• 认证头原样透传（API key 或 OAuth）。代理无法解析的任何内容都会原样转发。流式（SSE）会被管道传输。

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

对于 VS Code 扩展，运行代理并通过项目或全局设置将扩展指向它：

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

累计节省量会记录在 ~/.codegraph/proxy-stats.json 中，并在启动时打印。

CLI 用法

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

架构地图（.codegraph/html）是分层、C4 风格的项目视图，完全由索引推导：

• 概览 —— 子系统卡片（顶层目录），卡片之间有加权导入边，并有自动推导的起始点（中心、入口、最大模块）；

• 子系统 —— 一个目录下的文件，带有导入边和折叠的相邻子系统；点击一个文件可追踪依赖与反向依赖，再次点击可逐级深入；

• 文件 —— 其符号（符号）有文件内调用箭头、以及可作为导航列的导入者和被导入者。

每一层都描述目的，而不仅是结构：描述从代码自身的文档中提取（文件与符号的文件文档字符串、README.md / __init__.py / index.* 的文件夹和仓库本身），并展示在目录卡片、提示条和侧栏中。

各层支持深链接（#d=src、#f=src/proxy.js）、/ 搜索、Esc 返回上层、拖拽平移、滚轮缩放。自包含 HTML、离线可用。

仪表盘（--no-open 只写文件）会生成到 .codegraph/dashboard.html：本地化 token 节省量、各工具使用次数、索引语言和下载量最多的文件。静态 HTML，无服务端，支持明暗主题。代理也可以请求时通过 usage_stats 与 dashboard=true 生成。

工作原理

• 文件使用 tree-sitter WASM 语法（tree-sitter-wasms 包）解析，通过 web-tree-sitter — 无平台特定二进制文件。

• 提取器对每个 AST 遍历一次，收集定义、调用边和每种语言的导入（src/languages.js）。

• 图持久化到目标仓库内的 .codegraph/index.json；刷新为增量（mtime+size）并有并发限制，保证查询速度。

• 跳过 node_modules、构建输出文件、压缩文件、简化根 .gitignore 规则生效。

• semantic_search 使用本地 embedding 模型（all-MiniLM-L6-v2，通过 transformers.js，可选 依赖）。首次使用时下载约 25MB 到 ~/.codegraph/models，并缓存每个仓库的符号向量于 .codegraph/vectors.bin。离线时或没有该依赖。

请把 .codegraph/ 添加到项目根目录 .gitignore 中（它是缓存与你的私有笔记）。

许可证

MIT