CodeGraph MCP Server 指南:单工具 codegraph_explore 策略、CODEGRAPH_MCP_TOOLS 配置与 Agent 使用范式

CodeGraph 通过一个常驻的 MCP(Model Context Protocol)Server 将预构建的代码知识图谱暴露给 AI Agent,默认只暴露一个"Read 级等价"的核心工具 codegraph_explore。本文基于仓库文档 MCP Server 展开,结合 MCP 工具定义源码、服务器级指令 与 MCP 启动逻辑,完整讲清 MCP 面的工具清单、CODEGRAPH_MCP_TOOLS 允许列表、输入输出边界,以及"一次 explore 取代 grep + Read 循环"的 Agent 使用范式。

启动方式:由安装器托管,无需手动运行

CodeGraph 以 MCP Server 身份运行。由安装器配置的 Agent 会自动拉起它,开发者不需要手动启动:

codegraph serve --mcp

安装器会把这一条命令写进各 Agent 客户端的 MCP 配置。从源码可以看到,所有安装目标统一使用 args: ['serve', '--mcp'],例如 共享安装目标、Antigravity 目标、OpenCode 目标;CLI 入口在 src/bin/codegraph.ts 中为 serve 子命令注册了 --mcp 选项(Run as MCP server,stdio transport)。

一个重要的设计约束是索引主权属于用户:

• 工作区存在 .codegraph/ 索引时,Agent 才会获得 CodeGraph 的工具;
• 在没有索引的工作区,服务器宣布自己处于非激活状态并不列出任何工具——Agent 继续用内置工具正常工作,是否建立索引始终由用户决定(用户可以在该项目中运行 codegraph init);
• 从源码看,即使服务器启动点本身没有索引,服务器仍会通过 projectPath 参数支持按项目查询任何已建索引的项目,并下发一套专用的服务器指令 SERVER_INSTRUCTIONS_NO_ROOT_INDEX,明确告诉 Agent "无默认项目、每次调用传 projectPath"。

从 src/mcp/index.ts 的注释还可以看到,serve --mcp 实际有三种运行时形态:Direct(单进程单客户端,CODEGRAPH_NO_DAEMON=1 时的行为)、Proxy(与共享 daemon 之间的 stdio↔socket 管道)、Daemon(脱离宿主进程、按项目根复用的后台进程)。三者对 Agent 透明,这里不展开。

默认只有一个工具:codegraph_explore

默认情况下,MCP 服务器只暴露一个工具:codegraph_explore。它是 Read 级等价的——输入一个自然语言问题或一袋子符号/文件名,返回相关符号的逐字、带行号的源码(按文件分组,和 Read 工具输出同一 <n>\t<line> 形状,可直接基于其 Edit),外加它们之间的调用路径(包括 grep 追不上的动态分发跳变,如回调、React re-render、JSX 子节点)以及一份影响面(blast-radius)摘要——说明哪些代码依赖这些符号。一次调用通常就能回答整个问题。

"只暴露一个强工具"是刻意的设计决策。仓库记录了对 Agent 行为的实测:一个瞄准精准的工具比一堆更窄的工具更能引导 Agent 直达答案(误选更少),而且 Agent 在回答问题和编辑代码时都会主动使用它。这个决策在源码中落为一行常量 DEFAULT_MCP_TOOLS = new Set(['explore']):其余工具的定义与处理逻辑全部保留,只是不再列给 Agent。

explore 的输入与动态描述

工具定义 中 codegraph_explore 的输入为:

参数	类型	说明
query(必填)	string	符号名、文件名或简短代码词,也可以是自然语言问题;流程类问题应命名跨流程的符号(如 mutateElement renderScene)
maxFiles	number	最多包含源码的文件数,默认 12
projectPath	string	跨项目查询时指定目标项目(就近解析其 .codegraph/)

另外两点源码级细节:

• 预算建议随项目规模动态注入:getTools() 会按索引文件数计算建议的 explore 调用次数(文件数 <500 时 1 次,逐级到 5 次),并把它追加进工具描述,例如 Budget: make at most 2 calls for this project (12,345 files indexed);
• 输出预算按规模分级:getExploreOutputBudget() 按文件数分档(150/500/5000/15000),总输出上限从 13K 字符封顶到约 24K,保证响应不会被宿主客户端外置成文件再读回来。

只读契约:工具注解

所有工具共享一组 READ_ONLY_ANNOTATIONS:readOnlyHint: true、destructiveHint: false、idempotentHint: true、openWorldHint: false。代码注释解释了它的实际价值——MCP 的 ToolAnnotations 是客户端可选参考但普遍会依据其行为做门控的字段,例如 Cursor 的 Ask 模式会拒绝任何未声明 readOnlyHint: true 的 MCP 工具;测试 mcp-tool-annotations.test.ts 覆盖了这一契约。

输入长度防护

MCP 客户端可能发送超大负载,源码为此设了三道上限(src/mcp/tools.ts):

• MAX_OUTPUT_LENGTH = 15000 字符:防止上下文膨胀;
• MAX_INPUT_LENGTH = 10_000 字符:自由文本入参(query/task/symbol),超过即拒绝,避免恶意客户端用 100MB 字符串打爆 FTS5 扫描;
• MAX_PATH_LENGTH = 4_096 字符:路径类入参(projectPath、path 过滤、glob)的上限。

越界时工具返回明确错误(如 query exceeds maximum length of 10000 characters),而不是崩溃或挂起。

其余 7 个工具:完全可用,但默认不列出

另有 7 个工具存在且完全功能可用,只是默认不在 tools/list 中列出——因为它们返回的信息已经内联在 codegraph_explore 的响应里(explore 的影响面小节、关系图、符号本体及其被调用列表):

工具	用途
codegraph_node	单个符号的源码 + caller/callee 链路;或以 Read 同等形状(带行号)整文件读取,重名时返回所有重载定义体
codegraph_search	按名称跨库查找符号(只返回位置,不返回代码)
codegraph_callers	找出调用某函数的所有函数
codegraph_callees	找出某函数调用的所有函数
codegraph_impact	分析修改某符号会波及哪些代码
codegraph_files	获取已索引的文件结构(比文件系统扫描更快)
codegraph_status	检查索引健康度与统计信息

各工具的完整 JSON Schema 见 tools.ts 中的定义,常用默认值可一览:

• codegraph_search:kind 支持 function/method/class/interface/type/variable/route/component 过滤,limit 默认 10;
• codegraph_callers / codegraph_callees:必填 symbol,可用 file 在重名符号间消歧,limit 默认 20;
• codegraph_impact:depth 默认 2(遍历多少层依赖);
• codegraph_node:两种模式——只传 file 是"整文件读取"(支持 offset/limit/symbolsOnly,与 Read 同形),传 symbol(+可选 includeCode/line)是"单符号定位 + 源码 + 调用链";
• codegraph_files:支持 path 目录过滤、pattern glob、format(tree/flat/grouped)。

每个工具都有对应的 CLI 等价命令,供脚本和非 MCP 场景使用:

MCP 工具	CLI 等价命令
codegraph_node	codegraph node
codegraph_search	codegraph query
codegraph_callers	codegraph callers
codegraph_callees	codegraph callees
codegraph_impact	codegraph impact
codegraph_files	codegraph files
codegraph_status	codegraph status

README 对这一点有同样说明:这些工具"stays fully functional but unlisted by default",并给出了 CODEGRAPH_MCP_TOOLS 与 CLI 等价命令的组合用法。

用 CODEGRAPH_MCP_TOOLS 重新启用工具

CODEGRAPH_MCP_TOOLS 环境变量接受一个逗号分隔的短名允许列表,整体替换默认工具面:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

源码行为细节(见 getStaticTools() 与 ToolHandler.toolAllowlist()):

• 未设置/为空:走默认面(仅 explore);
• 设置后:完整替换默认,任意已定义工具都可被重新启用;
• 匹配用短名,node 与 codegraph_node 均可,前缀可带可不带;
• 被允许列表裁掉的工具是真正从 ListTools 消失,而不是调用时才被拒绝;若客户端仍调用一个被禁用的工具,会收到 Tool <name> is disabled via CODEGRAPH_MCP_TOOLS 的明确错误;
• 测试 mcp-tool-allowlist.test.ts 覆盖了允许列表解析与禁用报错两条路径。

该变量通常写在 MCP 配置的 env 块中(仓库的评测脚本 run-arms.sh 正是这样做的:"env":{"CODEGRAPH_MCP_TOOLS":"$TOOLS"}),无需改客户端的工具清单配置即可收缩工具面。

Agent 使用范式:一次 explore 代替 grep + Read

CodeGraph 就是那个预构建的搜索索引。文档给出的用法原则:

• 面对"X 如何工作"、架构问题、流程问题("X 如何到达 Y")、"X 在哪"类问题,以及编辑代码过程中,Agent 应直接用 codegraph_explore 回答然后停下,典型情况下零次文件读取,而不是用 grep + Read 重新推导答案;
• 量级对比:一次直接的 CodeGraph 回答是 1 到几次调用;一次 grep/read 式探索则是几十次。

这份指导如何到达 Agent 的?两条通道:

1. MCP initialize 响应:服务器在握手时下发服务器级指令(SERVER_INSTRUCTIONS),MCP 客户端(Claude Code、Cursor、opencode 等)会自动把它注入主 Agent 的系统提示。指令内容包括:任何结构性/流程性问题优先 explore;把 explore 返回的源码视为"已 Read",不要再重复打开这些文件;反模式清单(不要用 grep 复核 codegraph 的结果、不要先 grep/Read 再 explore、不要手工拼流程、编辑后留意 staleness 横幅);以及局限说明(索引落后文件写入约 1 秒、跨文件解析是尽力而为的名称匹配、不承担实时正确性验证职责);
2. 安装器写入的指令文件段:由于子 Agent 和非 MCP 框架永远看不到 initialize 响应,安装器会额外在每个 Agent 的指令文件中写入一段简短的、带标记围栏的说明,指向 codegraph explore CLI 等价命令(安装器实现见 src/installer/ 目录)。

两条通道共同保证了无论 Agent 走 MCP 还是 CLI,拿到的行为指引一致。

小结

CodeGraph 的 MCP 面设计可以概括为三句话:默认一个 codegraph_explore 工具承担几乎全部场景(逐字源码 + 调用路径 + 影响面,一次调用取代几十次 grep/Read);其余 7 个工具保留完整功能并通过 CODEGRAPH_MCP_TOOLS 一键重新露出;Agent 侧的使用范式通过 initialize 响应与安装器指令文件双通道下发。工具定义、允许列表与输出预算的实现均可在 src/mcp/tools.ts 中直接查阅,行为边界由 mcp-tool-allowlist.test.ts、mcp-tool-annotations.test.ts 等测试固化。