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客戶端）