cgraphy

cgraphy – 代码知识图谱 MCP 服务

论文（DOI）： https://doi.org/10.5281/zenodo.21422935
PyPI： https://pypi.org/project/cgraphy/
GitHub： https://github.com/pmgarg/cgraphy

cgraphy 是一个 Python 代码知识图谱和模型上下文协议（MCP）服务，面向 Claude Code、Codex CLI、Cursor 和 Gemini CLI 等 AI 编码 Agent。

cgraphy 会将任意代码库编入知识图谱——函数、类和文件作为节点；调用、导入、继承以及 git 协同变更历史作为边——并通过模型上下文协议向 AI 助手提供紧凑、符合令牌预算的图谱切片。Agent 无需每次遇到提示词都重新阅读几十个文件来了解项目，只需查询图谱，就能在几千个令牌内获得相关子图。

• 支持任何语言。 为 Python、TypeScript/JavaScript、Java、Go、C、C++ 和 Rust 提供完整精度的提取（调用、导入、继承）；通过 tree-sitter 为另外 20 多种语言提供通用的定义级提取；配置文件和文档文件也会通过摘要纳入。
• 按重要性排序。 代码图谱上的 PageRank 会优先呈现每个回答中至关重要的符号。
• 符合令牌预算。 cgraphy_context 会以贪心方式围绕某个符号扩展图谱，并在达到令牌预算时准确停止——成本随问题而变化，而非随代码库大小而变化。
• 感知 Git。 --git-history 会从提交历史中挖掘共同变更的文件（逻辑耦合），这是一种静态分析无法发现的边类型。
• 无需 API 密钥。 语义摘要由宿主 Agent 自行通过 enrich 循环生成；摘要通过内容哈希在重新索引后保留。
• 零基础设施。 所有数据存放在 .cgraphy/ 中的单个 SQLite 文件里。无需服务、守护进程或向量数据库。
• 经过端到端验证。 在 SWE-bench Lite 上进行的 400 多次受控 Agent 运行中，已部署配置解决了 57 个真实 GitHub 问题中的 14 个，而非 8 个（官方 Docker 测试框架）。索引 kubernetes（26K 个文件、219K 个节点）仅需 49s，并以 1.6s 的周期保持索引更新，查询响应时间为 1–152ms。所有基准测试和预测均在本仓库中（研究论文与基准测试）。

安装

pip install cgraphy        # or: uv tool install cgraphy

快速开始

cd your-repo
cgraphy init          # one command: MCP config + agent steering + index

cgraphy init 会执行以下三项操作：

1. 写入项目级 .mcp.json——Claude Code 的各种形式都会自动读取它：CLI、VSCode 扩展和桌面应用。
2. 将指导区块附加到 CLAUDE.md 和 AGENTS.md，告知 Agent 在读取文件之前先查询图谱（cgraphy_overview → cgraphy_search → cgraphy_context）——这正是让图谱真正取代大量文件阅读的关键。（无法强制 Agent，只能引导：通过指令文件、有说服力的工具描述，以及工具确实更快来实现，这种方式行之有效。）
3. 使用 git 协同变更历史构建索引。

也可以手动向助手注册 MCP 服务：

Claude Code

claude mcp add cgraphy -- uvx cgraphy serve /path/to/repo

Codex CLI（~/.codex/config.toml）

[mcp_servers.cgraphy]
command = "uvx"
args = ["cgraphy", "serve", "/path/to/repo"]

Gemini CLI（~/.gemini/settings.json）/ Cursor（.cursor/mcp.json）

{"mcpServers": {"cgraphy": {"command": "uvx",
                            "args": ["cgraphy", "serve", "/path/to/repo"]}}}

八个工具

阅读／了解概况：

工具	返回内容	Agent 使用场景…
cgraphy_overview	仓库地图：子系统、按重要性排列的关键符号、所有文件	首先使用，代替阅读文件来了解概况
cgraphy_search	排序后的匹配结果，包含 file:line 和摘要（安装 [semantic] 附加组件后，可混合词法与语义搜索）	在使用 grep／列出目录之前
cgraphy_context	符号周边的子图（调用方、被调用方、导入项、共同变更项），并受令牌预算限制	代替阅读整个文件
cgraphy_read	单个符号的源码，带行号并受预算限制	代替阅读整个文件

编辑／审查——让图成为变更循环一部分的工具：

工具	返回内容	Agent 使用场景…
cgraphy_impact	影响范围：直接及传递依赖项、受影响的测试、历史上共同变更的文件	修改共享代码之前
cgraphy_diff_context	将当前 Git 差异映射到已修改的符号、使用方及覆盖这些符号的测试	提交之前／恢复工作时

丰富图谱：

工具	返回内容	Agent 使用场景…
cgraphy_enrich	仍需单行摘要的符号批次	收到“丰富图谱”请求时
cgraphy_store_summaries	确认信息和剩余数量	保存已撰写的摘要

检索会感知使用情况：Agent 反复询问的符号，在后续上下文扩展中会获得少量且有上限的加权提升（遥测数据保留在本地 SQLite 文件中，不会离开你的设备）。

语义搜索（可选）

pip install "cgraphy[semantic]"

添加轻量级静态嵌入（model2vec，仅使用 CPU，无需 torch），并通过倒数排名融合与 FTS5 结合，从而弥合问题描述式用语（“登录故障”）与代码标识符（validate_jwt）之间的词汇差异。

图谱会自我修复：工具会检测过时文件，并在回答前增量重新索引（仅处理已更改的文件）。

丰富图谱

结构会自动提取；含义 则来自摘要。只需告诉你的 Agent 一次：

enrich the cgraphy graph

它会循环执行 cgraphy_enrich → cgraphy_store_summaries，直到每个符号都有一条语义摘要。摘要会与各符号源码的哈希关联，因此编辑某个函数时，只会使该函数的摘要失效。

对于 CI，cgraphy index --summarize 可使用你自己的 Anthropic API 密钥预先生成摘要（安装 cgraphy[summarize]，并设置 ANTHROPIC_API_KEY）。

查看器

cgraphy view .        # http://localhost:8787

一个无需依赖项的本地页面（内置 Cytoscape.js）：可搜索、按类型着色、点击查看详情、双击展开邻居；共同变更边以虚线显示。

衡量节省效果

python scripts/benchmark.py /path/to/repo "your question"

输出 Agent 通过 cgraphy（概览 + 搜索 + 上下文）了解概况所花费的令牌数，与阅读所有代码文件所花费的令牌数进行对比，并给出缩减比例。

定位基准测试（研究工具）

python scripts/eval_localization.py /path/to/repo 50

从仓库历史记录中挖掘类似修复的提交（主题 = 查询，已修改文件 = 标准答案；共同变更挖掘会排除被评估的提交），然后针对一系列消融配置进行评分——仅 FTS、+PageRank、+图扩展、±共同变更边——并评估 hit@5/hit@10/MRR 和令牌成本。无需调用大模型，无需人工评分，完全可复现。结果和论文草稿位于 paper/。

工作原理

1. cgraphy index 遍历仓库（遵循 .gitignore + .cgraphyignore），使用 tree-sitter 解析每个文件，并将节点和 边存储在 .cgraphy/graph.db（SQLite + FTS5）中。重新索引会根据 内容哈希增量执行。
2. 解析器尽力通过限定名称链接跨文件引用（调用、导入、继承）；未解析的名称会保留，绝不会丢弃。
3. PageRank 在边图上运行；每次查询都会优先展示重要符号。搜索会结合 FTS5 相关性与排名。
4. cgraphy serve 通过 stdio 提供五种 MCP 工具。
5. 可选：--git-history 会从 git log 中挖掘加权的共同变更边。

设计详情：docs/superpowers/specs/2026-07-08-cgraphy-design.md

引用 cgraphy

如果你在研究或工具开发中使用 cgraphy，请引用这篇论文：

@misc{garg2026cgraphy,
  author = {Garg, Prateek Mohan},
  title  = {Which Graph Signals Pay for Their Tokens? cgraphy: A Token-Budgeted
            Code Knowledge Graph as a Portable Context Layer for AI Coding Agents},
  year   = {2026},
  doi    = {10.5281/zenodo.21422935},
  url    = {https://doi.org/10.5281/zenodo.21422935},
  note   = {Preprint}
}

许可证

MIT

mcp-name: io.github.pmgarg/cgraphy