Graphlens Mcp

graphlens-mcp

一个免费的 MIT 许可 MCP 服务，为编码 Agent（Claude Code、Cursor 及兼容客户端）提供项目的语义代码图——符号、跨文件调用、引用、导入和跨语言边界。

Agent 不再从头到尾读取文件，也不再通过 grep 搜索名称，而是浏览代码结构：谁调用了这个函数、它依赖什么、如果我更改它的签名，会有什么地方出问题。它是 graphlens 分析引擎之上的一层轻量运行时：graphlens 提供机制（解析、稳定的节点身份、解析器）；graphlens-mcp 负责存储、保持最新状态以及面向 Agent 的接口。

📖 文档： https://neko1313.github.io/graphlens-mcp/

状态：早期阶段。核心导航功能可用；请参阅已知限制。

为什么

编码 Agent 以缓慢的方式探索代码结构——使用 grep、glob，一次读取一个文件——在真正开始工作前，手动重建调用路径。其动机与其他代码上下文工具相同：让 Agent 不再使用 grep。 graphlens 的独特之处在于它的实现方法。

大多数工具通过构建自己的代码模型来解决这个问题——用启发式方法拼凑出一个临时代码图，每种工具对代码库的映射方式都略有不同，而且没有哪个模型具有权威性。graphlens 选择了相反的路线：它基于语言自身真正的分析引擎构建——rust-analyzer、gopls、TypeScript 编译器、捆绑的 ty 类型引擎——也就是业界已经信赖的 LSP 级工具。这能生成稳定、真实的项目图景（谁实际调用了什么，涵盖多个文件和语言），而非定制的近似结果。稳定的基础也便于继续构建：为变更中的关键部分附加上下文，自动提取语义集群，并可靠地回答影响分析问题。

这一基础就是 graphlens 引擎——负责解析、稳定的节点身份和解析器。graphlens-mcp 是其上面向 Agent 的智能层，说实话，也是一个展示如何使用该引擎的实例：它持久化代码图（因此无需将所有内容都保存在内存中），在其上添加语义与聚类层，在你编辑时保持内容最新，并通过导航工具和捆绑的技能向 Agent 提供接口。基于这个实例，它正逐渐发展为一个自给自足的系统——以行业巨头为参照，致力于提供稳定、可复现的结果：有些方面更出色，有些方面稍逊，但会坦诚说明（请参阅对比情况）。

对比情况

graphlens-mcp 附带一套可复现的 A/B 基准测试（benchmarks/），让同一个 Agent 分别使用三个可互换的代码上下文 MCP 服务——graphlens、semble（语义搜索）和 codegraph（图索引）——并加入一个无工具对照组，衡量各服务相较于模型自身记忆的增益。测试覆盖真实的 Go / Rust / Python / TypeScript 代码库，并根据预先设定的标准答案 确定性地评分（不使用 LLM 评判），按简单查找和困难影响分析／跨文件问题分层，同时报告准确率和 Token／工具调用／费用成本——因为准确率相同时，成本更低的一方胜出。

📊 结果（10 个代码库 · 3 个模型，从强到确实较弱 · 约 2,400 次评分运行 — 完整细分、显著性检验和复现步骤见 文档：基准测试）：

	简单问题准确率	困难问题准确率	困难问题 Token 数（中位数）	困难问题完成率
graphlens	0.980 – 1.000	0.899 – 0.921	22.4k – 34.1k	每个模型均 ≥ 0.959
codegraph	0.912 – 0.990	0.655 – 0.939	23.2k – 70.0k	在最弱模型上降至 0.765
semble	0.647 – 0.961	0.555 – 0.850	21.6k – 74.9k	在最弱模型上降至 0.688
无（对照组）	0.366 – 0.681	0.453 – 0.685	0.1k – 0.9k	—

只看准确率会掩盖账单上真正重要的数字：每项任务花费的 Token 数。无论驱动模型强弱，graphlens 在困难问题上的 Token 开销都保持稳定（22k–34k）；codegraph 和 semble 在最弱模型上则飙升至 70k 以上，是 graphlens 上限的两倍多，答案却更差，而非更好。只有 graphlens 能始终明显优于无工具对照组，并且在每个模型档位都保持 0.95 以上的完成率：在测试过的最弱模型（gpt-oss-20b）上，它的困难问题准确率仍有 0.900，Token 开销约为 codegraph 的一半。按任务匹配的成对 Wilcoxon 符号秩检验确认，较弱模型上的差距具有统计显著性，并非少数离群任务造成——各模型的 p 值和效应量见 notebook。

安装

需要 Python ≥ 3.13（此要求继承自 graphlens）。

uv tool install graphlens-mcp      # or: pipx install graphlens-mcp

Python 语言分析开箱即用（ty 类型引擎作为依赖项提供）。其他语言可立即解析；安装相应工具链后，即可启用完整的跨文件语义分析（TypeScript 需要 Node，Go 需要 Go 工具链，等等）。如果没有相应工具链，该语言会标记为 degraded，而不会阻止 init。

快速开始（两条命令）

uv tool install graphlens-mcp        # 1. install
cd your-project && graphlens-mcp init  # 2. index + configure your agent

init 会检测项目语言，将代码索引到本地图中，在 Agent 配置中写入 MCP 服务条目，并安装导航技能。你不需要自行运行 serve——Agent 会根据配置启动它。重启 Agent，然后提出类似 “如果我更改 create_order 的签名，会有什么影响？” 的问题。

命令

命令	功能
graphlens-mcp init	检测语言 → 检查工具链 → 完整索引 → 配置 Agent → 安装技能
graphlens-mcp serve	通过 stdio 启动 MCP 服务。由 Agent 启动，而非你手动启动
graphlens-mcp status	显示检测到的语言、工具链状态以及图的大小／新鲜度
graphlens-mcp reindex	强制完整重建（例如，安装新工具链后）
graphlens-mcp remove	从 Agent 中注销，并可通过 --purge-db 删除本地图

init 的实用选项：--root <dir>、--agent claude_code --agent cursor（可重复指定）、--no-agent、--no-skills、--db <path>。

图存储在 <project>/.graphlens/graph.db（SQLite）中。这是可重新生成的缓存，可安全删除；reindex 会重建它。请将 .graphlens/ 添加到 VCS 忽略规则中（内置的 init 流程假定该目录不会提交）。

支持的语言

语言	引擎	开箱即用
Python	ty（随附）	立即支持完整语义
TypeScript	Node 桥接	未安装 Node 时为 degraded；安装 Node 后支持完整语义
Go	Go 工具链	未安装工具链时为 degraded
Rust	SCIP / rust-analyzer	未安装工具链时为 degraded
PHP	PHP 解析器	未安装工具链时为 degraded

graphlens-mcp status 会报告各语言的实际解析器状态。缺少工具链时，该语言会报告为 degraded（已解析结构，但调用和类型未完全解析），并给出安装提示——这绝不会阻止 init。

Agent 工具

三个工具——符号或文件所需的一切都会以可导航的图 节点 返回，而不是无法进一步操作的 grep 结果。每个响应都带有图质量状态（ok | degraded），避免 Agent 将不完整的答案误认为完整答案；还带有 indexing 标志（后台重新索引运行时为 true，此时边可能暂时不完整）。

工具	用途
search	按名称、内容或含义查找代码——唯一入口。返回带签名的图节点（通常无需后续调用即可回答问题）。内容按字面匹配，而非按正则表达式匹配。使用 path_glob 限定范围（例如 "tests/*"、"*.ts"、"!tests/*" 用于排除子树）；设置 exhaustive=true 可列出所有匹配文件（无数量上限，不含签名），而不是按排名返回前 N 个
relations	一次调用查看符号的关联：调用方、被调用方、实现者／子类，以及非调用引用——每项都带有签名。用于影响分析的工具（“更改 X 会导致什么出问题？”、“什么实现了 X？”）
info	读取特定目标：符号（节点 ID 或名称）→ 源代码 + 签名 + 位置；文件路径 → 其符号大纲

search 和 relations 均可直接接受符号名称或节点 ID——无需先查找节点 ID。两者都会限制响应大小（命中数量较大时，会通过随附的小型嵌入模型按相关性排序，而不是直接截断），并在列表达到上限时显示实际总数（callers_total、references_total 等），让 Agent 看到“显示 15 条，共 22 条”，而无需猜测。如果无法获取嵌入模型（例如首次运行时没有网络），搜索会自动回退到名称／内容匹配。

新鲜度机制

图通过单一机制保持最新：文件系统监视器（serve 默认会启动；使用 --no-watch 可禁用）。磁盘上的文件发生变化时，服务会重新索引连通集合——已更改的文件、导入该文件的文件，以及该文件导入的文件——并进行一次完整分析，从而正确重建跨文件边，而不会留下不完整结果。删除文件时，会清除其符号并刷新导入它的文件。没有轮询，也没有仅分析结构的“骨架”阶段：每次（重新）索引都会生成解析器所能提供的完整图。作为后备机制，如果某个工具访问的文件尚未由监视器处理，就会触发相同的连通集合重新索引。

基于事件的监视器无法发现服务停止期间创建、删除或编辑的文件，因此 serve 会在启动时执行一次性协调：扫描项目，索引新文件，清除已消失的文件，并刷新发生变化的文件——随后将工作交给监视器。

已知限制

• 已连接集合的重新关联，深层涟漪： 监视器会重新关联某项变更的已连接集合（变更文件及其直接导入者和导入项），而不是整个项目。重命名若经过多层间接引用产生连锁影响，可能需要完整执行 reindex 才能获得精确的图。创建一个未变更文件已导入的文件时会妥善处理——新文件编入索引后，监视器会再次遍历导入者并重新关联该导入者一次。
• 增量编辑中的跨语言边： 每当重新编入索引的文件涉及某个边界时，合成的 COMMUNICATES_WITH 边都会重新生成，因此新增或移动的暴露者／使用者无需完整执行 reindex 即可建立关联。若某项变更使文件完全退出某个边界（文件不再暴露其他文件仍在使用的端点），要获得精确的跨语言视图，可能仍需完整执行 reindex；不过，基于边界的查询无论如何都能解析连接。

卸载

graphlens-mcp remove 会从你的 Agent 中注销该服务；添加 --purge-db 还会删除本地 .graphlens/ 缓存。

开发

uv sync --all-groups   # install lint + test tooling
task check             # ruff + format-check + ty + bandit + pytest (the CI gate)
task docs:serve        # preview the docs site locally (needs Node + pnpm)

如需了解设计和不变量，请参阅架构和语义搜索页面，以及文档站点。

许可证

MIT — 请参阅 LICENSE。