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

CodeGraph MCP Server 指南:单工具 codegraph_explore 策略、CODEGRAPH_MCP_TOOLS 配置与 Agent 使用范式【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraphCodeGraph 通过一个常驻的 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_DAEMON1时的行为)、Proxy(与共享 daemon 之间的 stdio↔socket 管道)、Daemon(脱离宿主进程、按项目根复用的后台进程)。三者对 Agent 透明,这里不展开。默认只有一个工具:codegraph_explore默认情况下,MCP 服务器只暴露一个工具:codegraph_explore。它是 Read 级等价的——输入一个自然语言问题或一袋子符号/文件名,返回相关符号的逐字、带行号的源码(按文件分组,和Read工具输出同一n\tline形状,可直接基于其 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)maxFilesnumber最多包含源码的文件数,默认 12projectPathstring跨项目查询时指定目标项目(就近解析其.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目录过滤、patternglob、format(tree/flat/grouped)。每个工具都有对应的 CLI 等价命令,供脚本和非 MCP 场景使用:MCP 工具CLI 等价命令codegraph_nodecodegraph nodecodegraph_searchcodegraph querycodegraph_callerscodegraph callerscodegraph_calleescodegraph calleescodegraph_impactcodegraph impactcodegraph_filescodegraph filescodegraph_statuscodegraph statusREADME 对这一点有同样说明:这些工具stays fully functional but unlisted by default,并给出了CODEGRAPH_MCP_TOOLS与 CLI 等价命令的组合用法。用CODEGRAPH_MCP_TOOLS重新启用工具CODEGRAPH_MCP_TOOLS环境变量接受一个逗号分隔的短名允许列表,整体替换默认工具面:CODEGRAPH_MCP_TOOLSexplore,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 ReadCodeGraph就是那个预构建的搜索索引。文档给出的用法原则:面对X 如何工作、架构问题、流程问题(X 如何到达 Y)、X 在哪类问题,以及编辑代码过程中,Agent 应直接用codegraph_explore回答然后停下,典型情况下零次文件读取,而不是用 grep Read 重新推导答案;量级对比:一次直接的 CodeGraph 回答是 1 到几次调用;一次 grep/read 式探索则是几十次。这份指导如何到达 Agent 的?两条通道:MCPinitialize响应:服务器在握手时下发服务器级指令(SERVER_INSTRUCTIONS),MCP 客户端(Claude Code、Cursor、opencode 等)会自动把它注入主 Agent 的系统提示。指令内容包括:任何结构性/流程性问题优先 explore;把 explore 返回的源码视为已 Read,不要再重复打开这些文件;反模式清单(不要用 grep 复核 codegraph 的结果、不要先 grep/Read 再 explore、不要手工拼流程、编辑后留意 staleness 横幅);以及局限说明(索引落后文件写入约 1 秒、跨文件解析是尽力而为的名称匹配、不承担实时正确性验证职责);安装器写入的指令文件段:由于子 Agent 和非 MCP 框架永远看不到initialize响应,安装器会额外在每个 Agent 的指令文件中写入一段简短的、带标记围栏的说明,指向codegraph exploreCLI 等价命令(安装器实现见 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 等测试固化。【免费下载链接】codegraphPre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, CoPilot, and Hermes Agent — fewer tokens, fewer tool calls, 100% local项目地址: https://gitcode.com/GitHub_Trending/co0degr/codegraph创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考