金大哥 - go-code-graph MCP 详情

article

README

🚀 Go代码图

Go代码图是一款强大的Go代码库分析工具，它能将代码转化为可探索的图形，借助模型上下文协议（MCP）使AI助手能够理解复杂的代码库。

🚀 快速开始

借助MCP快速上手

1. 使用Docker进行设置（推荐）

# 克隆并设置
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup  # 启动Neo4j并构建MCP服务器镜像

2. 配置Claude桌面端

make generate-mcp-config  # 生成所需的确切配置

将输出内容复制到Claude桌面端的配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

3. 开始与AI一同使用

此时MCP服务器已准备就绪！你的AI助手可以分析任何Go代码库。

传统使用方式（不使用MCP）

# 构建工具
make build

# 分析代码库（仅本地包）
./bin/analyze -repo=. -output=graph.json

# 在浏览器中查看
./bin/server -graph=graph.json -port=8080
# 打开 http://localhost:8080/visualization

# 导入到Neo4j
./bin/import-neo4j -graph=graph.json -clear

✨ 主要特性

🔍 深度代码分析：从Go抽象语法树（AST）中提取9种节点类型和12种关系类型。
🎨 交互式可视化：Web界面可处理4000多个节点，并支持实时过滤。
🧠 基于AI的理解：MCP服务器支持通过自然语言对代码进行查询。
📊 图数据库：集成Neo4j，用于复杂的架构分析。
🚀 企业级规模：已在包含97个包和4000多个节点的代码库上成功测试。
⚡ 语义搜索：可选的嵌入功能，用于增强代码理解。

📦 安装指南

借助MCP快速上手

1. 使用Docker进行设置（推荐）

# 克隆并设置
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup  # 启动Neo4j并构建MCP服务器镜像

2. 配置Claude桌面端

make generate-mcp-config  # 生成所需的确切配置

将输出内容复制到Claude桌面端的配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

传统使用方式（不使用MCP）

# 构建工具
make build

💻 使用示例

基础用法

# 借助MCP快速上手
# 克隆并设置
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup  # 启动Neo4j并构建MCP服务器镜像

# 配置Claude桌面端
make generate-mcp-config  # 生成所需的确切配置

# 传统使用方式（不使用MCP）
# 构建工具
make build

# 分析代码库（仅本地包）
./bin/analyze -repo=. -output=graph.json

# 在浏览器中查看
./bin/server -graph=graph.json -port=8080
# 打开 http://localhost:8080/visualization

# 导入到Neo4j
./bin/import-neo4j -graph=graph.json -clear

高级用法

MCP工具和提示

MCP服务器提供了两种分析代码库的方式：

MCP提示（引导式工作流程）

MCP服务器包含15个全面的提示，可引导你完成常见的分析任务。这些提示会明确告知AI助手使用哪些工具以及使用顺序，确保遵循最佳实践并实现全面覆盖。详细文档请参阅 MCP提示指南。

示例提示：

analyze_new_codebase - 完成初始分析并提供架构概述
assess_code_quality - 进行全面的质量评估并提供可操作的见解
analyze_change_impact - 在进行更改之前了解影响
debug_execution_flow - 跟踪执行路径以进行调试
plan_refactoring - 获取逐步的重构指导

何时使用提示：开始新的分析任务、遵循最佳实践、确保全面覆盖。

MCP工具（构建块）

MCP服务器提供了8个强大的工具，可直接用于代码库分析。这些工具是提示所使用的构建块，但你也可以直接使用它们进行特定查询和自定义探索：

🔍 analyze_workspace

将Go代码库导入并分析到图数据库中。

何时使用：初始设置或更新代码库分析
支持：选择性包含外部依赖项
示例用法：

{
    "workspacePath": "/path/to/project",
    "workspaceName": "my-project",
    "incremental": false,
    "allowedPackages": [
        "github.com/gin-gonic/gin/...",
        "github.com/neo4j/neo4j-go-driver/v5"
    ]
}

💬 natural_query

将自然语言问题转换为图查询。

何时使用：探索代码库结构和关系
示例问题：
- "哪些是最复杂的函数？"
- "哪些结构体的字段最多？"
- "显示未使用的接口"
- "哪些包依赖于认证模块？"
- "哪些函数处理错误？"

🔗 cypher_query

直接访问图数据库以进行复杂查询。

何时使用：需要进行自定义图遍历的高级分析
示例用法：查找循环依赖、分析调用链、自定义指标

📊 analyze_impact

分析更改某个组件会影响哪些部分。

何时使用：在进行重构或重大更改之前
示例问题："如果我更改ProcessOrder函数的签名，会有什么影响？"

🎯 find_patterns

检测代码库中的代码模式和反模式。

何时使用：代码质量评估、查找技术债务
模式类型：重复函数、高复杂度、上帝对象、未使用的代码

🔌 find_implementers

查找实现给定接口的所有类型。

何时使用：理解接口使用和多态性
示例："哪些类型实现了io.Writer接口？"

🛤️ trace_call_path

查找两个函数之间的执行路径。

何时使用：理解组件之间的连接方式
示例："main()函数如何调用SaveToDatabase函数？"

🏗️ detect_architecture

分析架构模式和层次结构。

何时使用：理解系统设计和结构
分析类型：层检测、模式识别

何时直接使用工具：特定查询、交互式探索、自定义分析工作流程。详细比较请参阅工具与提示指南。

📚 详细文档

如需详细信息，请参阅文档目录：

技术架构：系统设计、组件和嵌入
MCP工具参考：详细的工具文档及示例
MCP提示指南：全面的提示，用于引导式分析
工具与提示：何时使用工具和提示
实际使用指南：常见工作流程和最佳实践
Docker MCP设置：详细的Docker部署指南

🔧 技术细节

测试和开发

测试脚本

scripts/ 目录包含用于测试和开发的实用脚本：

test-mcp-tool.sh：使用自定义参数测试单个MCP工具
test-mcp-tools.sh：对所有MCP工具进行全面测试
setup-test-workspace.sh：初始化并分析用于测试的工作区

示例用法：

# 测试特定工具
./scripts/test-mcp-tool.sh natural_query go-code-graph '{"question":"What are the most complex functions?"}'

# 运行全面测试套件
./scripts/test-mcp-tools.sh go-code-graph

# 设置新的工作区
./scripts/setup-test-workspace.sh my-project /path/to/project

运行测试

# 运行所有测试
make test

# 运行带覆盖率的测试
make test-coverage

# 运行特定包的测试
go test ./internal/analyzer -v

分析外部依赖项

默认情况下，分析器仅包含模块中的包，以保持图形的聚焦和可管理性。但是，你可以选择性地包含外部依赖项，以了解代码与第三方库的交互方式。

为何包含外部包？

API使用：确切了解如何使用第三方库
集成点：识别与外部代码的所有接触点
调用链：跟踪包括外部调用在内的完整执行路径
接口实现：查看代码实现了哪些外部接口

命令行用法

在 analyze 命令中使用 -include-packages 标志：

# 包含单个外部包及其所有子包
./bin/analyze -repo=. -output=graph.json \
  -include-packages="github.com/gin-gonic/gin/..."

# 包含多个特定包
./bin/analyze -repo=. -output=graph.json \
  -include-packages="github.com/gin-gonic/gin,github.com/stretchr/testify/assert"

# 包含不同模式的包
./bin/analyze -repo=. -output=graph.json \
  -include-packages="github.com/sirupsen/logrus,golang.org/x/sync/..."

MCP用法

在使用MCP服务器与AI助手时，在 analyze_workspace 工具中指定外部包：

{
    "workspacePath": "/path/to/project",
    "workspaceName": "my-project",
    "incremental": false,
    "allowedPackages": [
        "github.com/gin-gonic/gin/...",
        "github.com/neo4j/neo4j-go-driver/v5"
    ]
}

或者直接告知AI助手：

"分析 /path/to/project 并包含 github.com/gin-gonic/gin"
"分析时包含数据库驱动包"

包模式

精确包：github.com/sirupsen/logrus - 仅包含此特定包
包含子包：github.com/gin-gonic/gin/... - 包含包及其所有子包
多个包：命令行中使用逗号分隔的列表，MCP中使用数组

示例用例

1. 数据库驱动分析

./bin/analyze -repo=. -output=db-integration.json \
  -include-packages="github.com/lib/pq,database/sql"

2. Web框架集成

./bin/analyze -repo=. -output=web-app.json \
  -include-packages="github.com/gin-gonic/gin/...,github.com/gorilla/mux"

3. 内部共享库

./bin/analyze -repo=. -output=full-analysis.json \
  -include-packages="github.com/mycompany/shared-lib/...,github.com/mycompany/common/..."

最佳实践

从小处着手：从最关键的依赖项开始
使用模式：... 后缀可有效包含所有子包
监控大小：外部包会显著增加图形大小
关注接口：优先考虑实现了其接口的包
供应商目录：如果使用供应商目录，可以直接分析 ./vendor/...

性能考虑

包含外部包会增加：

分析时间（需要解析更多包）
内存使用（更多节点和边）
图形复杂度（需要跟踪更多关系）
可视化性能（需要渲染更多元素）

故障排除

包未找到：

确保包在 go.mod 中，或运行 go mod download
检查确切的导入路径是否与代码中的一致
尝试使用 go list 验证包路径

图形过大：

更有选择性地包含包
尽可能使用特定包而不是 ...
考虑单独分析外部包

示例自然语言查询

向AI助手提出以下问题：

代码质量

"哪些是最复杂且需要重构的函数？"
"查找参数过多的函数"
"显示可能存在过多职责的上帝对象"

架构理解

"支付和订单服务如何交互？"
"主要的架构层次有哪些？"
"哪些包存在循环依赖？"

影响分析

"如果删除User结构体，会有什么影响？"
"哪些服务依赖于认证模块？"
"查找所有调用已弃用API的地方"

代码模式

"查找重复的函数实现"
"哪些接口只有一个实现？"
"显示未使用的私有函数"

开发支持

"理解此服务的主要入口点有哪些？"
"哪些函数会启动goroutine？"
"查找所有错误处理模式"

外部依赖项（使用 -include-packages 进行分析时）

"我们的代码如何使用wp-golang-packages库？"
"我们实现了哪些外部接口？"
"显示所有对数据库驱动的调用"

📄 许可证

本项目采用MIT许可证，详细信息请参阅 LICENSE 文件。

📦 系统要求

Docker（用于Neo4j和MCP服务器）
Go 1.24+（用于本地开发）
兼容MCP的客户端（Claude桌面端或其他MCP客户端）

go-code-graph

README

🚀 Go代码图

🚀 快速开始

借助MCP快速上手

1. 使用Docker进行设置（推荐）

2. 配置Claude桌面端

3. 开始与AI一同使用

传统使用方式（不使用MCP）

✨ 主要特性

📦 安装指南

借助MCP快速上手

1. 使用Docker进行设置（推荐）

2. 配置Claude桌面端

传统使用方式（不使用MCP）

💻 使用示例

基础用法

高级用法

MCP工具和提示

MCP提示（引导式工作流程）

MCP工具（构建块）

🔍 analyze_workspace

💬 natural_query

🔗 cypher_query

📊 analyze_impact

🎯 find_patterns

🔌 find_implementers

🛤️ trace_call_path

🏗️ detect_architecture

📚 详细文档

🔧 技术细节

测试和开发

测试脚本

运行测试

分析外部依赖项

为何包含外部包？

命令行用法

MCP用法

包模式

示例用例

1. 数据库驱动分析

2. Web框架集成

3. 内部共享库

最佳实践

性能考虑

故障排除

示例自然语言查询

代码质量

架构理解

影响分析

代码模式

开发支持

外部依赖项（使用 -include-packages 进行分析时）

📄 许可证

📦 系统要求

运行方式说明

托管运行

本地运行 / 其它方式