Go Code Graph

🚀 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/..."

最佳实践

1. 从小处着手：从最关键的依赖项开始
2. 使用模式：... 后缀可有效包含所有子包
3. 监控大小：外部包会显著增加图形大小
4. 关注接口：优先考虑实现了其接口的包
5. 供应商目录：如果使用供应商目录，可以直接分析 ./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客户端）