1. 为什么 Claude Code 在大型项目里总在“瞎找代码”如果你用 Claude Code 分析过一个超过五万行的仓库大概率见过这样的场景你问“OrderService.createOrder 被谁调用了”它先 grep 一遍再读十几个文件然后继续 grep最后给你一个不太确定的答案。整个过程 Token 烧得飞快响应还慢。问题不在于模型不够聪明而在于它缺少一张“代码地图”——它不知道类与类、函数与函数之间的真实关系只能靠文本搜索去猜。CodeGraph 就是来解决这件事的。它是一个本地运行的代码知识图谱工具用 Tree-sitter 把仓库解析成语法树再抽取出定义、调用、继承、引用这些关系存进 SQLite带 FTS5 全文索引最后通过 MCPModel Context Protocol暴露给 Claude Code、Cursor、Codex CLI 这类 AI 编程工具。AI 不再需要反复扫描整个仓库而是直接查询“某个方法在哪里定义”“谁调用了这个方法”“改这个函数会影响哪些模块”。这篇手册面向的是本地代码库索引场景重点讲清楚三件事CodeGraph 的 MCP 怎么接进 Claude Code、Tree-sitter 和 SQLite 索引怎么验证、从配置到查询的闭环怎么跑通。适合已经在用 Claude Code、手里有中大型项目Spring Boot、微服务、K8s Operator、大型前端都算的开发者。下面所有命令和配置都可以直接复制。2. 前置准备TaoToken 与 Claude Code 环境在接 CodeGraph 之前得先保证 Claude Code 本身能正常工作。Claude Code 需要模型服务这里我用 TaoToken 来做接入它的 API 地址是 https://taotoken.net/api兼容 Anthropic 的接口格式配置起来比较直接。先拿到 API Key。打开 https://taotoken.net/api-keys 创建一个 Key复制出来。然后配置环境变量让 Claude Code 走这个端点export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key如果你用的是 Claude Code 的 settings.json可以写成这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }验证一下 Claude Code 能不能正常对话claude -p 用一句话说明什么是 MCP能返回内容就说明模型通道没问题。这一步很关键因为 CodeGraph 的 MCP Server 是挂在 Claude Code 上的如果 Claude Code 本身连不上模型后面查图谱也白搭。注意ANTHROPIC_BASE_URL 不要带结尾斜杠Key 不要提交到 Git 仓库建议放在 shell 的 profile 文件或本地 settings.json 里。环境准备好之后确认 Node.js 版本在 18 以上因为 CodeGraph 的 CLI 和 MCP Server 都依赖 Node 运行时node -v npm -v3. 安装 CodeGraph 并生成 MCP 配置骨架CodeGraph 提供三种安装方式我实测下来最省事的是全局安装加codegraph install因为它会自动检测你机器上已经装了哪些 Agent并帮你写好 MCP 配置。npm install -g colbymchenry/codegraph codegraph install执行codegraph install后会出现一个交互式选择界面大致长这样◆ Which agents should CodeGraph configure? │ ◼ Claude Code (detected) │ ◼ Cursor (detected) │ ◼ Codex CLI (detected) — global only │ ◼ opencode (detected) │ ◻ Gemini CLI (detected) └勾选 Claude Code然后它会问你是应用到所有项目还是当前项目◆ Apply agent configs to all your projects, or just this one? │ ● All projects (~/.claude, ~/.cursor, etc.) │ ○ Just this project选 All projects 会写入~/.claude.json和~/.claude/settings.json。如果你只想给某个项目用就选 Just this project配置会写到项目目录下的.mcp.json或.claude/settings.json。安装完成后Claude Code 的 MCP 配置骨架大致是这样~/.claude/settings.json片段{ mcpServers: { codegraph: { command: codegraph, args: [mcp, --project, .], env: {} } } }如果你要手动写注意command必须是codegraph在 PATH 里可执行args里的--project指向你的代码库根目录。有些版本用的是codegraph serve --mcp具体以codegraph --help输出为准。提示安装器还会问 “Auto-allow CodeGraph commands?”选 Yes 可以跳过 Claude Code 里的权限提示查询图谱时不会每次都弹确认。4. 用 Tree-sitter 建索引并验证 SQLite 图谱MCP 配置只是“通道”真正让 Claude Code 能查的是索引。进入你的项目根目录执行初始化cd demo-project codegraph init -i-i表示交互式会问你索引哪些语言、是否排除 node_modules 等。执行完后项目下会生成.codegraph/ ├── codegraph.db └── meta.jsoncodegraph.db就是 SQLite 数据库里面存的是 Tree-sitter 解析出来的节点和边。你可以直接用 sqlite3 打开验证sqlite3 .codegraph/codegraph.db .tables正常会看到类似nodes、edges、files、nodes_fts这些表。nodes_fts是 FTS5 全文索引表用来做符号搜索。查一下某个类的定义sqlite3 .codegraph/codegraph.db \ SELECT name, kind, file FROM nodes WHERE nameUserService LIMIT 5;如果返回了文件路径和节点类型class/interface说明 Tree-sitter 解析和 SQLite 写入都成功了。再查调用关系sqlite3 .codegraph/codegraph.db \ SELECT src.name, dst.name FROM edges e JOIN nodes src ON e.src_id src.id JOIN nodes dst ON e.dst_id dst.id WHERE e.kindcalls AND dst.namefindById LIMIT 10;这条 SQL 会列出所有调用findById的源节点。能查出结果就证明代码图谱已经建好了。查看整体状态codegraph status输出会包含数据库大小、索引文件数、节点数、边数、同步状态。如果节点数是 0说明索引没建上检查一下项目路径和语言配置。5. 在 Claude Code 里发起查询并验证闭环索引建好后重启 Claude CodeMCP Server 需要重新加载claude然后直接提问注意要用“利用 CodeGraph”这样的措辞引导它走图谱查询而不是默认的 grep利用 CodeGraph 分析UserService.findById 被哪些地方调用如果配置正确Claude Code 会调用 codegraph 的 MCP 工具返回调用链列表而不是去读一堆文件。你也可以问更复杂的使用 CodeGraph 找出 OrderService.createOrder() 的完整调用链使用 CodeGraph 分析如果删除 UserRepository.findByEmail() 会影响哪些代码实测下来在五万行以上的项目里这类问题的响应速度和答案准确度都比纯 grep 模式好很多。原因是 Claude Code 拿到的是结构化的边关系不需要自己推断。如果你想验证 MCP 是否真的被调用可以在 Claude Code 里输入/mcp查看已连接的 Server 列表应该能看到codegraph处于 connected 状态。如果没连上检查codegraph命令是否在 PATH 里以及 settings.json 的 JSON 格式有没有写错。6. 常见报错与排查清单报错一codegraph: command not found说明全局安装的 bin 目录不在 PATH 里。用npm bin -g找到路径加到 shell 配置里export PATH$(npm bin -g):$PATH报错二MCP Server 连不上/mcp显示 failed先手动跑一下 MCP 命令看报什么错codegraph mcp --project .如果提示找不到项目或数据库说明--project路径不对或者还没执行codegraph init -i。另外确认 settings.json 里没有多余的逗号JSON 格式错误会导致 Claude Code 静默忽略配置。报错三索引为空codegraph status显示 0 nodes检查项目语言是否被 Tree-sitter 支持。CodeGraph 支持 Java、Python、Go、TypeScript、JavaScript、Rust 等 20 多种语言但如果你项目里全是某种小众语言可能解析不了。另外确认没有把整个项目都加进 ignore 规则。报错四查询结果过时代码改了之后索引不会自动更新需要重新跑codegraph init -i或者看版本是否支持增量同步codegraph status里会显示同步状态。报错五Token 消耗没降下来确认 Claude Code 真的在走 MCP。如果提问方式太模糊比如“帮我看看这个项目”模型可能还是选择 grep。用明确的“利用 CodeGraph 分析 XXX”来引导。7. 把 CodeGraph 接进你的日常编码流CodeGraph 的价值在于把“找代码”这件事从文本搜索变成图查询。对于 Spring Boot 的 Controller-Service-Repository 调用链、微服务的跨模块依赖、K8s Operator 的 Reconcile 流程、大型前端的组件依赖它都能给出结构化的答案。配合 Claude Code 使用时建议把常用查询写成固定句式比如“使用 CodeGraph 找出 X 的完整调用链”“使用 CodeGraph 分析删除 Y 会影响哪些代码”这样模型会稳定地走图谱通道。如果你还没配好 Claude Code 的模型通道可以先到 https://taotoken.net/api-keys 拿 Key再按第 2 节的环境变量配置。MCP 接入和索引验证的完整流程就是上面这些跑通之后你会发现 Claude Code 对项目的理解明显更“有结构”了。长期做编码和 Agent 任务的也可以看看 Coding Plan 这类方案把模型调用和工具链一起管起来。