04 - code-graph-rag-mcp：给 Codex / Claude Code 加一个代码语义索引

GitHub: er77/code-graph-rag-mcpLicense: MIT 技术栈: Node.js + Tree-sitter + better-sqlite3 + sqlite-vec 核心定位: 用 MCP 协议为 Codex、Claude Code、Cursor、Gemini CLI 等提供多语言代码图谱 + RAG 语义索引，26 个 MCP 方法，比原生 Claude 工具快 5.5 倍。

这是对应知乎《我给 Codex 加了一个代码语义索引，终于不用每次都让它从 README 猜项目结构了》文章中的代表性项目。

1. 项目背景

1.1 Codex 用户的痛点

Codex CLI 跑大项目时的典型卡点：

每次让 LLM 从 README 猜项目结构 — 越大越猜不对
find/grep 反复扫盘 — 几万到几十万行的项目工具调用排队
没有跨语言能力 — 项目同时有 TS 前端 + Python 后端 + Go 中间件，AI 无法关联
多项目协作 — 几个仓库间的关系完全靠 LLM 推理

1.2 解题思路

code-graph-rag-mcp 把"代码图谱 + 语义 RAG"打包成一个 MCP Server，一次配置后 Codex / Claude Code 都能直接调用：

用户问 → Codex CLI → MCP tools/call → code-graph-rag-mcp
                                       │
                                       ├─ Tree-sitter 解析图
                                       ├─ better-sqlite3 存图
                                       └─ sqlite-vec 向量检索
                                       ↓
                              结构化答案（含代码片段）

1.3 实测收益

来自官方 README 的 benchmark：

指标	Native Claude	MCP CodeGraph	提升
执行时间	55.84s	<10s	5.5× 快
内存占用	进程重	65MB	显著优化
能力	基础 pattern	26 方法	全面
准确性	pattern-based	语义	更优

2. 核心概览

2.1 支持的 AI 编码工具

Claude Desktop
Claude Code（需要特殊配置避开 15s timeout）
Codex CLI
Cursor
Gemini CLI
VSCode（with MCP support）

2.2 支持的 11 种语言

语言	完成度	主要特性
Python	95%	async/await、装饰器、40+ magic methods、dataclasses
TypeScript/JavaScript	100%	ES6+、JSX、TSX、React patterns
C/C++	90%	函数、结构体/联合体/枚举、类、命名空间、模板
C#	90%	类、接口、枚举、属性、LINQ、async/await
Rust	90%	函数、结构体、枚举、trait、impl、模块、use
Go	90%	包、函数、结构体、接口、goroutine、channel
Java	90%	类、接口、枚举、record（Java 14+）、泛型、lambda
Kotlin	实现完成	包/导入、类/对象、函数/属性、关系
VBA	80%	regex-based，模块、sub、function、属性、UDT

2.3 26 个 MCP 方法概览

类别	代表方法
基础索引	`index`、`batch_index`、`reset_graph`、`clean_index`
图查询	`get_graph`、`list_entity_relationships`
语义	`semantic_search`
代码相似 / 克隆	`detect_code_clones`、`jscpd_detect_clones`
影响 / 重构	`impact_analysis`、`ai_refactoring`、`hotspot_analysis`
跨语言	多语言关系分析
诊断	`get_graph_health`、`get_version`、`get_agent_metrics`、`get_bus_stats`、`clear_bus_topic`
工程化	`lerna_project_graph`（带缓存的 monorepo 依赖图）

3. 实现原理

3.1 多 Agent 架构

code-graph-rag-mcp 采用"多 Agent 协调"设计：

            ┌──────────────────────┐
            │   MCP Server Entry   │
            │   (stdio JSON-RPC)   │
            └──────────┬───────────┘
                       │
            ┌──────────▼──────────┐
            │   Coordinator       │
            │   (路由 / 限流)       │
            └──────────┬──────────┘
                       │
       ┌───────────────┼────────────────┐
       ▼               ▼                ▼
  ParserAgent    SemanticAgent     GraphStorage
  (Tree-sitter)  (Embeddings)     (better-sqlite3
                                  + sqlite-vec)
       │               │                ▲
       └───────────────┴────────────────┘
                       │
                       ▼
          Knowledge Bus（topic 订阅）

3.2 双轨存储

图数据：better-sqlite3 存节点 / 边
向量数据：sqlite-vec 扩展（同一个 SQLite 文件即可装下向量索引）
- 表名：doc_embeddings、vec_doc_embeddings
本地化：./.code-graph-rag/vectors.db（v2.7.11 起改为每仓库独立 DB）

3.3 嵌入路由（v2.6.0+）

支持多种 Provider，按配置切换：

Provider	说明
`memory`	启动期临时嵌入，最快但重启失效
`transformers`	本地 ONNX/transformers.js 跑嵌入
`ollama`	通过 Ollama 本地服务
`openai`	OpenAI 或任意兼容端点（Gemini OpenAI-compat、Cloudru 等）
`cloudru`	Cloud.ru 嵌入服务

环境变量示例（Gemini 通过 OpenAI 兼容路由）：

bash

MCP_EMBEDDING_PROVIDER=openai
MCP_EMBEDDING_MODEL=gemini-embedding-001
MCP_EMBEDDING_ENABLED=true
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
OPENAI_API_KEY=YOUR_KEY

3.4 关键工程优化

a) 确定性图 ID（v2.6.0）

对节点/边使用 SHA256-based 稳定 ID，跨次索引可幂等更新，不会重复写。

b) 增量解析

ParserAgent 重启用 Tree-sitter 的增量解析能力，文件改动只重新解析变更的节点。

c) Knowledge Bus 反压

当 Agent 满载时，工具会返回 agent_busy + retryAfterMs 提示，避免 Codex 把超时归咎于 MCP 服务。

d) Codex 友好的 stdio 隔离

stdout 严格只走 JSON-RPC，所有日志重定向到 stderr 或 /tmp/code-graph-rag-mcp/mcp-server-YYYY-MM-DD.log，避免 Codex 那种"严格 stdio"客户端启动失败。

e) 客户端超时差异处理

Claude Desktop：可在配置里加 MCP_TIMEOUT
Claude Code（CLI）：硬编码 15s timeout，不认 MCP_TIMEOUT，需要用 MCP_SEMANTIC_WARMUP_LIMIT=0 关闭嵌入预热
Codex：stdio 严格，需要禁用 stdout 日志，可选用 batch_index 替代 index 避免单次超时

4. 完整使用步骤

4.1 系统要求

Node.js 24+
最低 2GB RAM（推荐 8GB）

4.2 安装

最新版必须从 GitHub Release 装 tgz，不要用 npm（README 明确说明）：

bash

# 下载 release tgz 后
npm install -g ./er77-code-graph-rag-mcp-2.7.12.tgz
code-graph-rag-mcp --version

4.3 配置 Claude Desktop

推荐用 MCP Inspector：

bash

npx @modelcontextprotocol/inspector add code-graph-rag \
  --command "npx" \
  --args "@er77/code-graph-rag-mcp /path/to/your/codebase"

或者：

bash

claude mcp add-json code-graph-rag '{
  "command": "npx",
  "args": ["@er77/code-graph-rag-mcp", "/_work_folder"],
  "env": {
    "MCP_TIMEOUT": "80000"
  }
}'

4.4 配置 Claude Code（CLI）— 重点

Claude Code CLI 强制 15s 工具超时，不认 MCP_TIMEOUT。首次 semantic_search 默认会做 50 个 embedding warmup，常常超时。

bash

claude mcp add code-graph-rag -s user \
  -e MCP_EMBEDDING_PROVIDER=openai \
  -e MCP_EMBEDDING_MODEL=gemini-embedding-001 \
  -e MCP_EMBEDDING_ENABLED=true \
  -e OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai \
  -e OPENAI_API_KEY=YOUR_KEY \
  -e MCP_SEMANTIC_WARMUP_LIMIT=0 \
  -- code-graph-rag-mcp /path/to/your/codebase

关键：MCP_SEMANTIC_WARMUP_LIMIT=0 关闭 warmup，首次查询毫秒级初始化，后续查询 <500ms 命中热缓存。

4.5 配置 Codex CLI — 推荐方式

bash

# 推荐：添加全局 MCP 入口（任何项目目录都能用）
codex mcp remove code-graph-rag    # 可选清理
codex mcp add code-graph-rag -- code-graph-rag-mcp

# 或者指向本地 dev build（不需要 npm/npx）
codex mcp add code-graph-rag -- node /absolute/path/to/code-graph-rag-mcp/dist/index.js

也可以直接写 ~/.codex/config.toml：

toml

[mcp_servers.code-graph-rag]
command = "code-graph-rag-mcp"
args = []

⚠️ 省略目录参数，让 MCP 服务通过 roots/list 自动获取工作区根目录。

4.6 配置 Gemini CLI

bash

gemini mcp add-json code-graph-rag '{
  "command": "npx",
  "args": ["@er77/code-graph-rag-mcp", "/path/to/your/codebase"]
}'

4.7 在 AI 工具里使用

自然语言示例

"What entities are in my codebase?"
"Find authentication functions in backend-api"
"Compare user management across all projects"
"Analyze the impact of changing this class"
"Suggest refactoring for this file"
"Find code clones in src/"

CLI 直接调用 MCP 工具

bash

# 健康检查
get_graph_health

# 重置图数据
reset_graph

# 清洗并完整索引
clean_index

# 大仓库友好的批量索引（推荐 Codex）
batch_index

# Lerna 工作区依赖图
lerna_project_graph --args '{"ingest": true}'
lerna_project_graph --args '{"ingest": true, "force": true}'   # 强制刷新

# 关系查询
list_entity_relationships --args '{"entityName": "YourEntity", "relationshipTypes": ["imports"]}'

# Agent 指标 / 知识总线诊断
get_agent_metrics
get_bus_stats
clear_bus_topic --args '{"topic": "semantic:search"}'

# CLI 一次性索引（debug 模式）
node dist/index.js /path/to/project '{
  "jsonrpc":"2.0","id":"index-1","method":"tools/call",
  "params":{"name":"index","arguments":{
    "directory":"/path/to/project","incremental":false,"fullScan":true,"reset":true
  }}
}'

4.8 大仓库索引（batch_index）

index 或 clean_index 在 Codex 上超大仓库容易超时。推荐：

batch_index 调用 1 → 返回 sessionId + done:false
batch_index 调用 2（带 sessionId）→ done:false
...
batch_index 调用 N（带 sessionId）→ done:true

可指定 maxFilesPerBatch 控制每批文件数。

5. 26 个 MCP 方法详解（节选）

方法	用途
`index`	全量/增量索引
`batch_index`	可断点续做的批量索引（Codex 大仓库推荐）
`reset_graph`	清空图数据
`clean_index`	reset + full index
`get_graph`	获取图结构
`list_entity_relationships`	实体的关系列表
`semantic_search`	自然语言代码搜索
`detect_code_clones`	嵌入 + JSCPD 联合的克隆检测
`jscpd_detect_clones`	纯 JSCPD 克隆检测（不需要嵌入）
`impact_analysis`	变更影响分析
`ai_refactoring`	AI 建议重构
`hotspot_analysis`	复杂度 + 耦合度热点
`get_graph_health`	数据库诊断
`get_version`	服务版本与运行时信息
`lerna_project_graph`	Lerna 工作区依赖 DAG，可缓存可刷新可入库
`get_agent_metrics`	运行时 Agent 指标
`get_bus_stats`	Knowledge Bus 状态
`clear_bus_topic`	清空特定主题

6. 性能与资源占用

指标	实现
解析速度	100+ files/秒（Tree-sitter 多线程）
查询响应	<100ms（SQLite + 向量优化）
内存	65MB 级别
向量检索	可选硬件加速；自动 ingestion
AST 提取	精确代码片段 + 语义上下文

6.1 多项目并行

toml

# Claude Desktop / Codex 都支持配置多个 MCP server，每个指向不同仓库
[mcp_servers.frontend]
command = "code-graph-rag-mcp"
args = ["/path/to/frontend"]

[mcp_servers.backend]
command = "code-graph-rag-mcp"
args = ["/path/to/backend"]

然后可以问："compare user management across all projects"。

7. 常见排坑

7.1 Claude Code: `semantic_search timed out after 15000ms`

如 4.4 所述，Claude Code CLI 硬编码 15s 超时。

修复：在 MCP server env 加 MCP_SEMANTIC_WARMUP_LIMIT=0。

7.2 Codex/VSCode MCP stdio 启动失败

Codex 严格要求 stdout 只走 JSON-RPC。

修复：

升级到 v2.7.12+（自动把 stdout 日志重定向到 stderr）
推荐配置：

toml

[mcp_servers.code-graph-rag]
command = "code-graph-rag-mcp"
args = []

如果还要看 stdout 日志做调试：MCP_STDIO_ALLOW_STDOUT_LOGS=1（不推荐生产）
启动仍失败？看 /tmp/code-graph-rag-mcp/mcp-server-YYYY-MM-DD.log

7.3 `batch_index` 报 `agent_busy` / `memory_limit`

bash

# 调高 coordinator / conductor 限制
COORDINATOR_MEMORY_LIMIT=...
CONDUCTOR_MEMORY_LIMIT=...
COORDINATOR_MAX_MEMORY_MB=...
CONDUCTOR_MAX_MEMORY_MB=...

# 或编辑 config/default.yaml

# 真正 OOM 时增大 Node 堆
NODE_OPTIONS="--max-old-space-size=4096" code-graph-rag-mcp

7.4 多仓库 SQLite 混在一起

v2.7.11 起每仓库一个 DB（./.code-graph-rag/vectors.db），记得加到 .gitignore：

.code-graph-rag/

7.5 `better-sqlite3` 原生模块版本不匹配

v2.6.4 起自动重建。失败时：

bash

npm rebuild better-sqlite3
# 全局安装时通常路径为：
# /usr/lib/node_modules/@er77/code-graph-rag-mcp

7.6 旧库缺少新列

bash

rm -f ./.code-graph-rag/vectors.db \
      ./.code-graph-rag/vectors.db-wal \
      ./.code-graph-rag/vectors.db-shm
# 重启服务，自动重建

7.7 已知警告

boolean@3.2.0 弃用警告来自 onnxruntime-node 间接依赖。从 v2.7.12 起，npm 安装默认不再自动装 onnxruntime-node，警告消失。

8. 多项目场景实战

8.1 同时分析前后端

"Find authentication functions in backend-api"
→ 调用 backend MCP server 的 semantic_search

"How does the frontend call the auth endpoint?"
→ 调用 frontend MCP server，再回到 backend 关联

8.2 Lerna Monorepo

bash

# 一次性入图
lerna_project_graph --args '{"ingest": true}'

# 配置变了，强制刷新
lerna_project_graph --args '{"ingest": true, "force": true}'

# 缓存返回 {cached: true}，30s debounce

9. 适用场景

✅ 强推：

多项目 / Monorepo
Codex CLI 用户
需要"语义 + 图谱 + 克隆检测"一站式
想用 Gemini Embedding 但又不想自己写嵌入路由

⚠️ 慎用：

Claude Code CLI（要注意 15s timeout 配置）
内存 <4GB 的轻量机器（大仓库容易 OOM）

❌ 不适用：

只用 Claude Desktop 的小项目（GitNexus 更简单）
23+ 语言中的小众语言（用 code-review-graph）

10. 与其他项目的关系

项目	code-graph-rag-mcp
code-review-graph	偏图谱 + Claude Code 深度，code-graph-rag-mcp 偏 RAG + Codex 强支持
GitNexus	GitNexus 自带 Web UI 和 7 Skills，code-graph-rag-mcp 工具更多（26 vs 7）
Semble	Semble 极轻量纯检索，code-graph-rag-mcp 是"图 + 嵌入"一体
BitFun flashgrep	flashgrep 只解决 grep 速度，code-graph-rag-mcp 解决语义和结构

11. 参考链接

GitHub: https://github.com/er77/code-graph-rag-mcp
NPM: https://www.npmjs.com/package/@er77/code-graph-rag-mcp
MCP Protocol: https://github.com/modelcontextprotocol
知乎《我给 Codex 加了一个代码语义索引，终于不用每次都让它从 README 猜项目结构了》

docs

hook

watcher

04 - code-graph-rag-mcp：给 Codex / Claude Code 加一个代码语义索引 ​

1. 项目背景 ​

1.1 Codex 用户的痛点 ​

1.2 解题思路 ​

1.3 实测收益 ​

2. 核心概览 ​

2.1 支持的 AI 编码工具 ​

2.2 支持的 11 种语言 ​

2.3 26 个 MCP 方法概览 ​

3. 实现原理 ​

3.1 多 Agent 架构 ​

3.2 双轨存储 ​

3.3 嵌入路由（v2.6.0+） ​

3.4 关键工程优化 ​

a) 确定性图 ID（v2.6.0） ​

b) 增量解析 ​

c) Knowledge Bus 反压 ​

d) Codex 友好的 stdio 隔离 ​

e) 客户端超时差异处理 ​

4. 完整使用步骤 ​

4.1 系统要求 ​

4.2 安装 ​

4.3 配置 Claude Desktop ​

4.4 配置 Claude Code（CLI）— 重点 ​

4.5 配置 Codex CLI — 推荐方式 ​

4.6 配置 Gemini CLI ​

4.7 在 AI 工具里使用 ​

自然语言示例 ​

CLI 直接调用 MCP 工具 ​

4.8 大仓库索引（batch_index） ​

5. 26 个 MCP 方法详解（节选） ​

6. 性能与资源占用 ​

6.1 多项目并行 ​

7. 常见排坑 ​

7.1 Claude Code: semantic_search timed out after 15000ms ​

7.2 Codex/VSCode MCP stdio 启动失败 ​

7.3 batch_index 报 agent_busy / memory_limit ​

7.4 多仓库 SQLite 混在一起 ​

7.5 better-sqlite3 原生模块版本不匹配 ​

7.6 旧库缺少新列 ​

7.7 已知警告 ​

8. 多项目场景实战 ​

8.1 同时分析前后端 ​

8.2 Lerna Monorepo ​

9. 适用场景 ​

10. 与其他项目的关系 ​

11. 参考链接 ​

04 - code-graph-rag-mcp：给 Codex / Claude Code 加一个代码语义索引

1. 项目背景

1.1 Codex 用户的痛点

1.2 解题思路

1.3 实测收益

2. 核心概览

2.1 支持的 AI 编码工具

2.2 支持的 11 种语言

2.3 26 个 MCP 方法概览

3. 实现原理

3.1 多 Agent 架构

3.2 双轨存储

3.3 嵌入路由（v2.6.0+）

3.4 关键工程优化

a) 确定性图 ID（v2.6.0）

b) 增量解析

c) Knowledge Bus 反压

d) Codex 友好的 stdio 隔离

e) 客户端超时差异处理

4. 完整使用步骤

4.1 系统要求

4.2 安装

4.3 配置 Claude Desktop

4.4 配置 Claude Code（CLI）— 重点

4.5 配置 Codex CLI — 推荐方式

4.6 配置 Gemini CLI

4.7 在 AI 工具里使用

自然语言示例

CLI 直接调用 MCP 工具

4.8 大仓库索引（batch_index）

5. 26 个 MCP 方法详解（节选）

6. 性能与资源占用

6.1 多项目并行

7. 常见排坑

7.1 Claude Code: `semantic_search timed out after 15000ms`

7.2 Codex/VSCode MCP stdio 启动失败

7.3 `batch_index` 报 `agent_busy` / `memory_limit`

7.4 多仓库 SQLite 混在一起

7.5 `better-sqlite3` 原生模块版本不匹配

7.6 旧库缺少新列

7.7 已知警告

8. 多项目场景实战

8.1 同时分析前后端

8.2 Lerna Monorepo

9. 适用场景

10. 与其他项目的关系

11. 参考链接