MCP CodeGraph 完整介绍

一、基础定义

CodeGraph = 代码知识图谱 + MCP (Model Context Protocol) Server 开源本地优先工具，为 AI 编程助手（Claude Desktop / Cursor / Windsurf / Claude Code）构建项目代码语义图 。 仓库：suatkocar/codegraph（主流原版）

核心定位：让大模型不用反复 grep、批量读取文件，直接结构化查询函数调用、依赖、引用链路，大幅节省上下文 Token。

二、核心原理

源代码 → Tree-sitter AST解析 → 提取符号&关系 → SQLite本地图谱数据库 → MCP服务暴露工具 → AI Agent调用

1. 解析引擎：Tree-sitter，支持 30 + 编程语言（TS/JS/Python/Go/Java/Rust/C# 等）
2. 存储 ：单机 SQLite，纯本地运行，代码不上云、无需 API Key
3. 索引：增量索引 + 文件监听自动刷新，代码改动后台更新图谱
4. 通信：MCP 标准 Stdio（主流）/ HTTP WebSocket（实验）

三、核心能力（MCP 对外工具）

AI 可直接调用这些结构化接口：

1. 符号查询：查找类 / 函数 / 变量定义
2. 查找引用：查找所有调用方（等价 IDE「Find References」）
3. 调用链路分析：上游调用者、下游被调用函数
4. 依赖图谱：文件 / 模块导入依赖关系
5. 变更影响域分析：预判修改某函数会影响哪些代码（重构必备）
6. 死代码扫描：识别未被引用的符号
7. 语义检索：结合向量嵌入做自然语言代码搜索
8. 路由识别：自动匹配 Web 框架路由 ↔ 处理函数 (FastAPI/Express 等)

四、解决的痛点

传统 AI 编码问题：

• AI 新开会话丢失项目全局架构认知
• 大量重复读取文件，Token 消耗极高
• 无法跨文件理解隐式调用关系，重构容易漏改
• 无法评估代码修改的爆炸半径

CodeGraph 优化：AI 直接查询图谱，由 "逐个读文件" 升级为 "查询结构化代码地图"。

五、快速部署流程

1. 安装二进制

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/suatkocar/codegraph/main/install.sh | bash

# Homebrew
brew tap suatkocar/codegraph
brew install codegraph

# Windows：下载release二进制，加入PATH

2. 项目初始化 & 建立索引

cd 你的代码仓库根目录
codegraph init        # 生成配置
codegraph index .     # 构建初始代码图谱

3. MCP 客户端配置（示例 Claude Desktop / Cursor .mcp.json）

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

--watch：开启文件监听，代码变更自动增量更新索引。

六、区分：同名项目提醒

社区存在多个名字近似项目，不要混淆：

1. ✅ suatkocar/codegraph（最流行原版 MCP CodeGraph，Rust 实现）
2. code-graph-mcp：另一套独立实现
3. nabi-codegraph-mcp：轻量精简版（仅 TS/Python）

七、适用场景

• 大型仓库、Monorepo 项目 AI 辅助开发
• 大规模重构、模块拆分、接口改造
• 让 Claude/Cursor 深度理解项目架构
• 自动化变更风险评估、代码审查辅助

八、优缺点

✅ 优点

• 完全本地、隐私安全
• Rust 实现性能高，大库索引速度快
• 标准 MCP 协议，所有 MCP 客户端通用
• 增量索引，支持实时同步代码变更

❌ 局限

• 动态语言（Python JS）无法 100% 捕获运行时动态调用
• 不处理编译期泛型复杂推导（静态分析通用限制）
  • 首次索引大型项目需要一定时间