MCP：让 Claude 直接调用 CGB 的 13 个工具

MCP（Model Context Protocol）是 Anthropic 定义的标准，让 LLM 能调用外部工具。CGB 的 MCP server 通过 stdio 管道通信——没有 HTTP 服务器，没有端口，Claude 直接 spawn 子进程，通过 stdin/stdout 交换 JSON-RPC 消息。

仓库管理

5 个工具

初始化、查状态、列表、切换活跃库、链接已有索引

代码搜索和文档

4 个工具

混合搜索、浏览 L1/L2 文档、获取 L3 函数文档、生成文档

调用图分析

2 个工具

查找所有调用者、BFS 追踪完整调用链

配置和维护

2 个工具

查看服务器配置、重建向量索引（不重建图）

为什么选 stdio 而不是 HTTP？

stdio 通信的好处：零网络配置、进程级别权限隔离、没有端口冲突、无需认证 token（调用方本身就是本机进程），非常适合开发者工具场景。CGB 的 MCP server 入口是 cgb-mcp，底层是 entrypoints/mcp/__main__.py，用 Python 的 sys.stdin/stdout 实现完整的 JSON-RPC 2.0 消息循环。

工具调用全过程：Claude → JSON-RPC → 处理 → 响应

以 find_api 为例，看一次完整的工具调用链路。Claude 把自然语言问题转成工具调用请求， MCP server 处理后返回结构化的 JSON 响应，Claude 再基于这个上下文组织回答。整个过程对用户透明——Claude 自动决策何时调用哪个工具。

工具调用过程 — find_api 示例

0 / 6 messages

工具调用对用户完全透明

Claude 自动决定何时、调用哪个工具、传入什么参数——用户只需提问。整个 JSON-RPC 往返通常在 100-500ms 内完成。如果 Claude Desktop 配置了 CGB MCP，每次对话中 Claude 都能访问最新的代码图谱，回答基于真实代码，而不是训练记忆。

13 个工具分类详解

每个工具都有精心设计的参数接口，Claude 可以通过 tools/list 方法获取完整的 JSON Schema 描述，自动理解如何调用。

仓库管理（5个）

initialize_repository

完整索引流程：graph → api-docs → embeddings。支持进度回调，可传入 repo_path（默认当前目录）。

get_repository_info

活跃库快照：节点数 / 关系数 / 文件数 / 上次索引时间，无参数，O(1)。

list_repositories

列出 ~/.code-graph-builder/ 下所有 artifact_dir，含 indexed_at 时间戳。

switch_repository

切换活跃库：写 active.txt。可传 repo_name 或 artifact_dir 路径。

link_repository

链接已有索引到新路径，不重建。适合团队共享同一份索引产物。

代码搜索和文档（4个）

find_api

混合搜索（语义向量 + 关键词）。参数：query, top_k。返回匹配函数列表 + score + 源码预览。

list_api_docs

浏览 L1/L2 文档层级。可选 module_name；不传则返回所有模块概览。

get_api_doc

获取 L3 函数文档。参数：qualified_name。返回完整文档（含源码、调用树、参数说明）。

generate_api_docs

重生成 API 文档。mode：full / resume / enhance。resume 跳过已有文档，增量补全。

调用图分析（2个）

find_callers

查找调用某函数的所有位置。输入：qualified_name。返回 caller 列表 + 文件位置。

trace_call_chain

BFS 追踪完整调用链。参数：start_function（可选 target）。返回 wiki 格式调查报告。

配置和维护（2个）

get_config

显示服务器配置：LLM 设置、Embedding 设置、工作空间路径。调试时首先调用。

rebuild_embeddings

重建向量索引，不重建图。适合更换 embedding 模型后使用，比全量重建快数倍。

工作空间布局与增量同步机制

所有索引产物都存在 ~/.code-graph-builder/ 目录下。每个仓库有独立的 artifact_dir，每次工具调用前会自动检查是否需要增量同步。

增量同步流程

🔔

工具调用

→

📄

meta.json

→

🌿

git HEAD

→

⚡

跳过

or

📋

git diff

→

🔧

增量重建

点击"下一步"开始 Step 0 / 6

增量同步的开销分析

当代码未改动时，检查开销极低（读一次文件 + 一次 git 命令）<1ms，对工具调用几乎无感知。当有代码改动时，只重建涉及变更文件的节点，避免对整个代码库全量重建（可能需要数分钟）。这套机制让 CGB MCP server 可以在日常开发中"持续在线"——代码改动后不需要手动触发重建，下次工具调用时自动同步。