内容
# graphlens-mcp
<!-- mcp-name: io.github.Neko1313/graphlens-mcp -->
[](https://github.com/Neko1313/graphlens-mcp/actions/workflows/ci.yml)
[](https://neko1313.github.io/graphlens-mcp/)
[](https://www.python.org/)
[](LICENSE)
一款免费、MIT许可的MCP服务器，为编码代理（Claude Code、Cursor及兼容客户端）提供项目的**语义代码图**，包括符号、跨文件调用、引用、导入和跨语言边界。
与从上到下读取文件或使用grep搜索名称不同，代理**导航结构**：*谁调用此函数*，*它依赖于什么*，*如果我更改其签名，会发生什么*。它是`graphlens`分析引擎上的一个薄运行时层：`graphlens`提供机制（解析、稳定的节点身份、解析器）；`graphlens-mcp`拥有存储、更新和面向代理的接口。
📖 **文档：** <https://neko1313.github.io/graphlens-mcp/>
> 状态：早期。核心导航功能已实现；参见[已知限制](#已知限制)。
## 为什么
`文件系统`/grep MCP使代理读取整个文件并匹配文本 — 速度慢、噪音大、且无法识别实际调用`OrderService.create`的三个模块。裸tree-sitter提供单文件语法，但无法解析文件之间的链接。`graphlens-mcp`回答跨文件问题 — 调用图和影响分析 — 并在您编辑时保持图的更新，然后通过捆绑的导航技能教导代理如何使用它。
## 安装
需要 **Python ≥ 3.13** （从`graphlens`继承的约束）。
```bash
uv tool install graphlens-mcp # 或：pipx install graphlens-mcp
```
Python语言分析开箱即用（`ty`类型引擎作为依赖项提供）。其他语言立即解析，并在其工具链存在时解锁完整的跨文件语义（Node for TypeScript、Go工具链等）；如果没有工具链，则该语言被报告为`degraded`而不是阻止`init`。
## 快速入门（两条命令）
```bash
uv tool install graphlens-mcp # 1. 安装
cd your-project && graphlens-mcp init # 2. 索引 + 配置代理
```
`init`检测项目的语言，将代码索引到本地图，写入代理配置中的MCP服务器条目，并安装导航技能。您**不**需要自己运行`serve` — 代理从配置中启动它。重启代理并询问类似的问题，例如 *"如果我更改`create_order`的签名，会发生什么？"*。
## 命令
| 命令 | 功能 |
|---|---|
| `graphlens-mcp init` | 检测语言 → 工具链医生 → 完整索引 → 配置代理 → 安装技能 |
| `graphlens-mcp serve` | 在stdio上启动MCP服务器。**由代理启动**，而不是您 |
| `graphlens-mcp status` | 显示检测到的语言、工具链状态和图大小/更新时间 |
| `graphlens-mcp reindex` | 强制完全重建（例如，在安装新工具链后） |
| `graphlens-mcp remove` | 从代理中注销并（使用`--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`。
## 代理工具
每个响应都带有图质量状态（`ok` | `degraded`），以便代理永远不会将部分答案误认为是完整答案。
| 工具 | 目的 |
|---|---|
| `search_symbols` | 符号名称的全文本搜索 — **从这里开始** |
| `get_node_info` | 源码片段 + 签名 + 节点位置 |
| `get_file_structure` | 文件的符号大纲 |
| `get_callees` | 函数调用的内容（出站，最高`max_depth`） |
| `get_callers` | 调用函数的对象 — 主要影响分析工具 |
| `get_neighbors` | 任意方向上N个跳跃内的节点 |
| `find_references` | 非调用用法（类型注解、赋值） |
| `get_cross_language_calls` | 跨服务边界的连接（HTTP/gRPC/队列） |
## 更新模型
一个机制保持图的更新：**文件系统监视器**（`serve`默认启动；使用`--no-watch`禁用）。当磁盘上的文件更改时，服务器重新索引**连接集** — 更改的文件及其导入的文件和被导入的文件 — 通过一次完整的分析，以便正确地重建跨文件边，而不是留下部分内容。删除文件会修剪其符号并更新其导入者。不进行轮询，也没有仅限于结构的"skeleton"阶段：每次（重新）索引都会生成解析器能提供的完整图。作为备份，如果某个文件被监视器尚未处理的文件所触及，相同的连接重新索引会在访问时触发。
在服务器关闭期间创建、删除或编辑的文件对于基于事件的监视器不可见，因此`serve`在启动时运行一次性**协调**：它扫描项目，索引新文件，修剪消失的文件，并更新更改的文件 — 然后移交给监视器。
## 已知限制
- **连接集重新链接，深度影响：** 监视器重新链接更改的**连接集**（更改的文件及其直接导入者和导入的模块），而不是整个项目。通过多层间接影响而更改的rename可能需要完整的`reindex`才能获得准确的图。创建的文件已经被未更改的文件导入，处理 — 第二个导入者传递在新文件被索引后重新链接该导入者。
- **跨语言边界在增量编辑时：** 合成`COMMUNICATES_WITH`边在每次重新索引的文件触及的边界时重新合成，因此新的或移动的暴露者/消费者在无需完整`reindex`的情况下被链接。更改使边界完全消失（一个文件停止暴露其他文件仍在消费的端点）可能仍需要完整的`reindex`才能获得准确的跨语言视图；基于边界的查询解析连接无论如何。
## 卸载
`graphlens-mcp remove`从代理中注销服务器；添加`--purge-db`以删除本地`.graphlens/`缓存。
## 开发
```bash
uv sync --all-groups # 安装lint + 测试工具
task check # ruff + 格式检查 + ty + bandit + pytest（CI网关）
task docs:serve # 在本地预览文档站点（需要Node + pnpm）
```
参见 [ARCHITECTURE.md](ARCHITECTURE.md) 获取设计和不变式，或 [文档站点](https://neko1313.github.io/graphlens-mcp/) 获取完整指南。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
