Claude CodeGraph MCP 完整指南（替代/互补 Codebase-Memory 的代码图谱工具）

一、CodeGraph 是什么

codegraph 是当下主流轻量型代码语义图谱 MCP 服务，专门给 Claude 提供项目全局代码结构、调用关系、依赖链路检索，是大型仓库开发刚需，常和 Karpathy、Superpowers 搭配，和 codebase-memory 属于同类工具但实现、性能、用法有区别。

核心解决痛点：

1. 新开会话 AI 完全忘记项目结构、函数调用、模块依赖
2. 翻阅大量文件消耗巨额上下文 Token
3. 修改代码无法预判全局影响，重构易踩坑
4. Monorepo、多包项目梳理架构成本极高

二、CodeGraph vs Codebase-Memory 核心差异

对比项	CodeGraph	Codebase-Memory
底层解析	Tree-sitter 高性能语法解析，启动快	自定义深度AST解析，索引更完整
索引速度	轻量增量索引，小仓库秒建	百万行项目索引耗时更长
资源占用	内存占用低，轻薄笔记本友好	存储图谱体积更大
擅长场景	日常查调用链、定位函数、快速架构概览	深度重构、跨模块影响分析、死代码扫描
生态	开箱即用，无额外缓存文件	自带本地持久化知识库
适用人群	日常开发、前端/中小型后端	大型monorepo、长期复杂重构

简单选择建议：

• 笔记本性能一般、中小型项目 → CodeGraph
• 百万行级大仓库、频繁重构、需要精准影响评估 → Codebase-Memory
• 追求极致工程流程：两者二选一 + Karpathy + Superpowers

三、CodeGraph 核心能力

1. 仓库全局索引

自动扫描主流语言：TS/JS/Go/Python/Java/C++/Vue/React

• 增量索引：仅更新修改文件，不用全量重建
• 自动忽略 .git、node_modules、dist、build 等目录

2. 语义查询工具集

1. search_symbol：按函数/类/变量名全局检索定义位置
2. find_references：查找该符号所有调用、引用、使用处
3. get_call_graph：生成函数完整调用上下游链路
4. list_modules：输出项目模块分层、依赖关系
5. get_file_deps：分析单个文件导入/被哪些文件导入
6. list_exports：查看文件导出的所有接口、类型、工具函数

3. 架构可视化分析

一键输出项目分层结构：

• 目录模块划分
• 公共工具层、业务层、接口层边界
• 第三方依赖与内部代码隔离边界

4. 变更风险预判

修改文件前自动分析：

• 哪些业务模块依赖当前代码
• 改动会影响多少页面、接口、单元测试配合 Karpathy 外科式修改规则，避免无关连锁改动。

四、两种部署方式（MCP 标准配置）

方式1：.mcp.json 全局/项目配置（推荐）

项目根目录新建 .mcp.json，自动加载 CodeGraph MCP：

{"mcpServers": {"codegraph": {"command": "npx","args": ["@codegraph/mcp"]}}}

保存后重启 Claude Code 会话自动初始化。

方式2：Claude Code 插件命令安装

# 添加社区插件源/plugin marketplace add codegraph/mcp# 安装 codegraph 技能/plugin install codegraph@codegraph/mcp# 初始化索引/codegraph:index

五、常用内置指令

/codegraph:index # 全量构建代码图谱/codegraph:reindex # 增量更新索引/codegraph:refs funcName # 查询函数所有引用位置/codegraph:callgraph funcName# 打印完整调用链路/codegraph:deps src/xxx.ts # 查看文件上下游依赖/codegraph:arch# 输出项目整体架构/codegraph:search UserService# 全局搜索类/方法

六、标准三件套组合工作流（Karpathy + CodeGraph + Superpowers）

1. 需求输入 → Karpathy Guidelines：禁止脑补、先对齐需求，简约实现
2. 熟悉项目上下文 → CodeGraph：查询架构、现有接口、历史实现逻辑
3. 需求确认 → Superpowers brainstorming 输出方案、write-plan 拆分微任务
4. 编码阶段
   • CodeGraph 实时查询依赖、调用链，预判修改风险
   • Karpathy 约束仅做精准外科修改，不乱改无关代码
   • Superpowers TDD 先写测试再编码
5. 报错调试：CodeGraph 追踪异常链路 + systematic-debugging 系统化排错
6. 收尾校验：CodeGraph 分析改动影响范围 + 全量测试、代码评审

七、使用场景建议

1. 小型脚本、单文件工具仅开启 Karpathy，无需 CodeGraph，节省资源。

2. 中小型前后端单体项目标配三件套：Karpathy + CodeGraph + Superpowers，轻量化不卡顿。

3. 大型 Monorepo / 企业级仓库可选升级为 Codebase-Memory 替代 CodeGraph，深度重构能力更强。

4. 团队统一规范项目统一提交：

   • CLAUDE.md（Karpathy 编码约束）
   • .mcp.json（CodeGraph MCP 配置）Superpowers 标准化开发流程，团队 AI 编码行为统一。

八、核心优势总结

1. 轻量高性能：Tree-sitter 语法树解析，启动、索引速度快，低配电脑流畅运行
2. 大幅节省 Token：结构化查询替代全文读取，避免上下文溢出
3. 跨会话持久记忆：新开会话不用重复讲解项目结构、接口定义
4. 本地离线运行：代码仅在本机解析，不上传云端，私有业务代码安全
5. 全栈适配：前端组件、路由、后端接口、模型层均可解析调用关系