MCP 使用与 CodeGraph 记录

1. 什么是 MCP

MCP（Model Context Protocol）是一种让 AI 代理与本地工具/服务交互的协议。通过 MCP，代理可以调用本地工具来获取代码上下文、执行搜索、分析调用关系等，而不是依赖模型自己在所有代码里搜索。

MCP 常见作用：

• 提供结构化的代码导航
• 减少模型对文件读取/grep 的依赖
• 让智能代理直接使用本地索引和数据库
• 提高代码理解、变更影响分析、追踪调用链的效率

2. CodeGraph 的原理与实现

2.1 核心原理

CodeGraph 是一个本地代码知识图谱工具，它通过以下流程理解整个项目：

1. 抽取（Extraction）

   • 使用 tree-sitter 解析源码
   • 从 AST 中提取函数、类、方法、变量、导入、调用等节点

2. 存储（Storage）

   • 将结果保存到本地 SQLite 数据库
   • 使用 FTS5 实现全文搜索
   • 保存符号、文件、边、引用等信息

3. 解析（Resolution）

   • 解析函数调用到定义
   • 解析导入关系、继承、接口实现
   • 支持框架特定路由与跨语言桥接

4. 自动同步（Auto-Sync）

   • 监听文件系统变化
   • 发生文件改动后自动增量更新索引
   • 保持索引与工作区基本一致

5. MCP 服务（MCP Server）

   • 启动 MCP 服务器，作为 AI 代理工具接口
   • 代理直接调用 CodeGraph 的工具，而无需大量 grep/read

2.2 为什么它有用

• 减少 AI 代理的文件读取和工具调用次数
• 快速定位符号和调用链
• 在大型仓库中尤其明显：直接用索引查询比逐文件搜索更快、更便宜
• 对于语义查询、影响分析、代码审查非常高效

3. 运行与使用 CodeGraph

3.1 安装方式

• 通过脚本安装（推荐）：
  • macOS / Linux：

    curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
    

  • Windows：

    irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
    

• 通过 npm：

  npx @colbymchenry/codegraph
  

3.2 当前项目快速初始化

当前仓库已经完成以下操作：

cd c:\Users\15154\Desktop\project\gs-manage-web
npx @colbymchenry/codegraph install --yes
npx @colbymchenry/codegraph init -i

索引结果：

• 扫描 140 个文件
• 索引 139 个文件
• 生成 1,451 个节点、3,152 条边

3.3 典型命令

• codegraph init -i

  • 初始化当前项目并立即构建索引

• codegraph index

  • 重新完整索引项目

• codegraph sync

  • 增量同步当前项目修改

• codegraph status

  • 查看索引状态和健康信息

• codegraph query <关键词>

  • 在索引中搜索符号

• codegraph callers <符号>

  • 查找调用指定符号的代码

• codegraph callees <符号>

  • 查找指定符号调用的函数

• codegraph trace <符号A> <符号B>

  • 跟踪两个符号之间的调用路径

• codegraph impact <符号>

  • 分析修改符号可能影响的代码范围

• codegraph files

  • 显示索引中的文件结构

• codegraph serve --mcp

  • 启动 MCP 服务器，让 AI 代理使用 CodeGraph 工具

4. CodeGraph MCP 工具介绍

4.1 codegraph_search

用途：按符号名称或关键字搜索代码库中的符号。

适用场景：

• 查找函数、类、变量
• 快速定位某个名字出现的位置

4.2 codegraph_context

用途：构建与当前任务或问题相关的代码上下文。

适用场景：

• 回答架构类问题
• 获取某个功能区域的相关代码片段

4.3 codegraph_trace

用途：追踪从一个符号到另一个符号的调用路径。

适用场景：

• 调查“这个请求如何走到这里”的问题
• 了解调用链和执行路径

4.4 codegraph_callers

用途：查找调用某个函数或方法的代码位置。

适用场景：

• 变更风险评估
• 查找入口点

4.5 codegraph_callees

用途：查找一个函数或方法内部调用了哪些其它函数。

适用场景：

• 了解函数实现细节
• 构建调用图

4.6 codegraph_impact

用途：分析修改某个符号会影响哪些代码。

适用场景：

• 评估改动范围
• 决定测试覆盖优先级

4.7 codegraph_node

用途：获取单个符号的详细信息和源码片段。

适用场景：

• 快速查看定义
• 获取符号的声明与文档

4.8 codegraph_explore

用途：一次返回多个相关符号、源码片段和关系图。

适用场景：

• 代码探索
• 多符号上下文分析

4.9 codegraph_files

用途：查看索引中的文件结构。

适用场景：

• 快速确认当前项目哪些文件已被索引
• 代替慢速文件系统扫描

4.10 codegraph_status

用途：检查索引健康、同步状况、未同步文件。

适用场景：

• 确认索引是否最新
• 排查 CodeGraph 问题

5. 其他非常常用的 MCP 组合场景

5.1 查找入口和实现

1. codegraph_search UserService
2. codegraph_callers UserService.handleRequest
3. codegraph_context 处理用户请求的流程

5.2 代码改动前的风险评估

1. codegraph_search updateProfile
2. codegraph_callers updateProfile
3. codegraph_impact updateProfile

5.3 快速定位某个功能相关代码

1. codegraph_context 实现机构管理页面的数据加载逻辑
2. codegraph_explore 机构管理 平台 信息

5.4 查找跨模块调用链

1. codegraph_trace Controller.method Service.method
2. codegraph_callees Service.method

6. 使用建议

• 先用 codegraph_search 或 codegraph_context 定位方向
• 再用 codegraph_callers / codegraph_callees 细化调用关系
• 如果要改动代码，优先运行 codegraph_impact
• 代码改动后可用 codegraph sync 让索引更新
• AI 代理使用时，尽量让代理直接调用 MCP 工具，而不是重复 grep/read

7. 本项目当前状态

• 已安装 codegraph
• 当前项目已初始化并建立索引
• 当前目录已生成 .codegraph/ 索引目录

如果你想继续，可把这份文档扩展为团队文档，并把常用命令补充到 package.json 或 README.md 中。