HAYASAKA7/go-arch-xray
GitHub: HAYASAKA7/go-arch-xray
Go Architecture X-Ray 是一个基于 MCP 协议的 Go 代码库深度分析服务器，通过 SSA 和类层次分析为 AI 客户端提供调用图、依赖关系、架构边界检查等结构化洞察能力。
Stars: 0 | Forks: 1
# Go Architecture X-Ray MCP
Go Architecture X-Ray 是一个模型上下文协议服务器，用于从 AI 客户端检查 Go 代码库。它通过 stdio 运行，并在 MCP 会话的生命周期内维护一个进程作用域的 LRU 缓存（默认 2 个条目）用于存储已分析的程序。
## 内存说明
如果在超大型单体代码库中仍然观察到较高的 RSS（常驻内存集），请将您的 `package_patterns` 缩小到您实际想要检查的模块，而不是使用 `./...`。
## 工具
### 调用图与可达性
- `analyze_call_hierarchy`：从一个函数开始构建前向 CHA（类层次结构分析）调用层次结构。上限为 3 跳；将边标记为 `Static`、`Interface` 或 `Goroutine`。
- `find_callers`：查找目标函数的传入调用者树。可配置深度，最多 8 跳。
- `find_call_path`：在 CHA 调用图上进行广度优先搜索 (BFS)，以查找从一个函数到另一个函数的调用路径。最多返回 `max_paths` 条不同路径；每条路径包含逐步的 `CallEdge` 条目。
### 导入图与架构
- `get_package_dependencies`：返回直接的包导入依赖，用于架构边界检查。
- `find_reverse_dependencies`：返回导入了指定目标包的包。可选地包含传递依赖闭包。
- `detect_import_cycles`：使用 Tarjan 强连通分量 (SCC) 算法检测已加载包图中的导入循环。返回所有循环的强连通分量。
- `check_architecture_boundaries`：根据可配置的规则集（`forbid`、`allow_only`、`allow_prefix`）评估包。项目内部的违规行为会附带文件/行位置进行报告。在允许类型的规则中，标准库（Stdlib）始终被允许。
### 结构体分析
- `get_interface_topology`：查找实现了目标接口的结构体。支持值接收者和指针接收者、嵌入、包限定接口名、标准库过滤、源码位置和上下文锚点。
- `trace_struct_lifecycle`：使用 SSA 报告结构体的实例化、字段修改和接口移交点。支持 `dedupe_mode`、`max_hops` 和 `summary` 输出控制。
- `detect_concurrency_risks`：通过启发式方法标记在 goroutines 中被修改且没有可见的 mutex 或 `sync/atomic` 保护的结构体字段。
### 工作区管理
- `reload_workspace`：使缓存的 `go/packages` 和 SSA 分析失效，并针对根路径和包模式重新加载。
- `cache_status`：返回 LRU 缓存占用率和每个条目的元数据（包数量、函数数量）。
- `clear_cache`：根据 `root_path`/`package_pattern` 键清除缓存条目，或使用 `all: true` 清除所有条目。
- `list_entrypoints`：列出已加载包中的 `main` 函数、`init` 函数和 goroutine 生成点。
- `list_http_routes`：扫描源文件以查找 HTTP 路由注册（net/http、gin、chi、gorilla/mux、echo、fiber、fasthttp/router）。返回路由方法、路径、处理程序、框架和字面量路径路由的源码位置。支持大型路由表的游标流式传输。
- `find_dead_code`：报告未导出的函数和方法，这些函数和方法未被引用，或无法通过 CHA 调用图从任何程序入口点到达。传递 `include_exported: true` 也可以审计导出的符号（对于内部模块很有用）。结果包含注意事项——CHA 无法看到反射、插件、cgo 或 `//go:linkname`。
- `find_duplicate_methods`：将工作区中签名和规范化主体匹配的函数和方法分组。主体在空白规范化和注释剥离后进行哈希处理。调整 `min_body_lines`（默认为 3）以控制噪声基准。
## 从 GitHub Releases 安装
带有标签的发布版本为以下平台构建了二进制文件：
- Windows amd64: `go-arch-xray--windows-amd64.zip`
- Windows arm64: `go-arch-xray--windows-arm64.zip`
- macOS Intel: `go-arch-xray--darwin-amd64.tar.gz`
- macOS Apple Silicon: `go-arch-xray--darwin-arm64.tar.gz`
- Linux amd64: `go-arch-xray--linux-amd64.tar.gz`
- Linux arm64: `go-arch-xray--linux-arm64.tar.gz`
从 GitHub Releases 页面下载适用于您平台的压缩包，将其解压，并在您的 MCP 主机配置中使用解压后的二进制文件路径。
在 macOS/Linux 上，如有必要，请使二进制文件可执行：
```
chmod +x ./go-arch-xray-*
```
## 从 npm 安装
一个轻量级的 Node 启动器已作为 [`@hayasaka7/go-arch-xray`](https://www.npmjs.com/package/@hayasaka7/go-arch-xray) 发布。
在安装时，`postinstall` 脚本会从相应的 GitHub Release 下载匹配的二进制文件。
直接通过 `npx` 使用：
```
npx -y @hayasaka7/go-arch-xray
```
或者全局安装：
```
npm install -g @hayasaka7/go-arch-xray
go-arch-xray
```
设置 `GO_ARCH_XRAY_BIN=/absolute/path/to/binary` 以跳过下载，并将启动器指向一个预安装的二进制文件（适用于隔离网络环境）。
## 从源码构建
```
go build ./...
```
适用于 macOS/Linux 的发布版二进制文件：
```
go build -trimpath -ldflags "-s -w" -o go-arch-xray .
```
适用于 Windows 的发布版二进制文件：
```
go build -trimpath -ldflags "-s -w" -o go-arch-xray.exe .
```
## MCP 主机配置
如果您通过 npm 安装，请使用下一节中所示的 `npx` 命令配置，这样 MCP 主机就不需要绝对路径。
例如。您可以为 Claude Code 进行安装，命令如下：
```
claude mcp add go-arch-xray -- npx -y @hayasaka7/go-arch-xray
```
使用已编译二进制文件的绝对路径。
例如。Claude Code 命令配置：
Windows：
```
claude mcp add go-arch-xray "Disk:\\path\\to\\go-arch-xray.exe"
```
macOS/Linux：
```
claude mcp add go-arch-xray "/path/to/go-arch-xray"
```
Windows：
```
{
"mcpServers": {
"go-arch-xray": {
"command": "D:\\Projects\\MCPDev\\go-arch-xray.exe",
"args": []
}
}
}
```
macOS/Linux：
```
{
"mcpServers": {
"go-arch-xray": {
"command": "/usr/local/bin/go-arch-xray",
"args": []
}
}
}
```
如果您下载了 release 资产，解压后的二进制文件名包含目标平台，例如：
```
{
"mcpServers": {
"go-arch-xray": {
"command": "/Users/you/bin/go-arch-xray-darwin-arm64",
"args": []
}
}
}
```
如果您通过 npm 安装，请使用 `npx`，这样 MCP 主机就不需要绝对路径：
```
{
"mcpServers": {
"go-arch-xray": {
"command": "npx",
"args": ["-y", "@hayasaka7/go-arch-xray"]
}
}
}
```
## 发布工作流
维护者可以通过推送以 `v` 开头的标签来发布版本：
```
git tag v0.5.0
git push origin v0.5.0
```
GitHub Actions 工作流会运行测试，为 Windows、macOS 和 Linux 交叉编译发布版二进制文件，将它们打包并附加到 GitHub Release 中。
## 通用输入
大多数工具接受：
- `root_path`：Go 项目的根目录。默认为服务器工作目录。
- `package_pattern`：单个 Go 包模式。也接受逗号分隔的列表。默认为 `./...`。
- `package_patterns`：Go 包模式数组。与 `package_pattern` 合并（去重）。用于在单次请求中进行多模块 / 多子树扫描。
高吞吐量工具还接受：
- `limit`：返回的最大项目数。
- `offset`：分页起始索引。
- `summary`：除了详细条目外，还返回汇总计数。
- `max_items`：返回项目的硬性安全上限。
- `chunk_size`：基于游标的流式传输的页面大小。当设置 (>0) 时，响应最多返回 `chunk_size` 个项目，并附带 `next_cursor` 和 `has_more`。通过将 `next_cursor` 作为 `cursor` 传回进行迭代，直到 `has_more` 为 `false`。
- `cursor`：由先前流式响应返回的不透明连续标记。请勿手动修改或构造。
### 流式传输与分页
对于返回切片的工具（`get_interface_topology`、`get_package_dependencies`、
`find_callers`、`find_reverse_dependencies`、`check_architecture_boundaries`、
`list_entrypoints`、`list_http_routes`、`analyze_call_hierarchy`、
`trace_struct_lifecycle`）：
- 优先使用基于游标的流式传输（`chunk_size` 为 20-50 + `cursor`），而不是使用过大的 `max_items`/`limit` 值。巨大的单次有效载荷可能会溢出 MCP 传输缓冲区和 LLM 上下文窗口。
- 服务器默认将每个块的上限设置为 **50 个项目**，以保护 AI 的上下文预算——大于 50 的值将被静默限制。在应对能够处理更大响应的传输/客户端运行时，可以通过 `GO_ARCH_XRAY_MAX_CHUNK_SIZE` 环境变量进行覆盖。
- 当非流式响应返回 `truncated: true` 且带有较大的 `total_before_truncate` 时，请使用 `chunk_size` 重试，而不是增加 `max_items`。
- 每个流式响应都带有底层数据集的指纹。如果在迭代中途重新加载了工作区，下一次调用将返回 `stream cursor invalidated` 错误。请**不带** `cursor` 重新启动流；不要尝试修复该 token。
MCP 服务器的 `Instructions` 字段会告诉 AI 客户端自动遵循此策略，因此大多数客户端无需提示即可选择流式传输。
### 图表导出
`get_package_dependencies`、`analyze_call_hierarchy`、
`check_architecture_boundaries` 和 `find_reverse_dependencies` 接受一个可选的 `export` 参数：
- `mermaid` — 可渲染 Markdown 的 Mermaid 图表（`graph LR` / `graph TD`）。
边界违规和根/目标使用类（`violation`、`root`、`target`）进行标记，以进行视觉强调。
- `dot` — Graphviz `digraph` 源码，适用于 `dot -Tsvg`。
- `json-graph` — 用于自定义可视化的普通 `{nodes, edges}` JSON。
当提供 `export` 时，响应将获得一个 `diagram` 字段，其中填充了渲染后的字符串。图表仅反映当前分页/流式传输窗口的数据，因此有效载荷大小仍受相同的 `limit`/`max_items`/`chunk_size` 控制限制。默认行为（无 `export`）保持不变。
带有图表的边界检查示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_pattern": "./...",
"rules": [{"type": "forbid", "from": "example.com/project/api/", "to": "example.com/project/repo/"}],
"export": "mermaid"
}
```
`get_interface_topology` 的多模式示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_patterns": ["./internal/...", "./pkg/api/..."],
"interface_name": "example.com/project/internal/api.Service",
"include_stdlib": false
}
```
旧的单模式示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_pattern": "./...",
"interface_name": "example.com/project/internal/api.Service",
"include_stdlib": false
}
```
`find_call_path` 输入示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_pattern": "./...",
"from_function": "HandleRequest",
"to_function": "db.Query",
"max_depth": 8,
"max_paths": 5
}
```
`find_reverse_dependencies` 输入示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_pattern": "./...",
"target_package": "example.com/project/internal/core",
"include_transitive": true
}
```
`analyze_call_hierarchy` 输入示例：
```
{
"root_path": "D:\\Projects\\ExampleGoProject",
"package_pattern": "./...",
"function_name": "Run",
"max_depth": 3
}
```
## 注意事项
诊断日志被写入 stderr，因此 stdout 保持为 MCP 协议流量保留。业务错误作为带有 `isError: true` 的 MCP 工具错误返回，允许客户端纠正输入，而不会将服务器传输视为失败。
标签：AI客户端, AI编程辅助, BFS, Go工具链, Go语言, LRU, MCP, Model Context Protocol, SCC, SOC Prime, SSA, stdio, stdlib, Tarjan, 代码分析, 代码审查, 代码搜索, 依赖图, 内存缓存, 凭证管理, 后端开发, 工具, 广度优先搜索, 开发工具, 强连通分量, 循环依赖检测, 接口拓扑, 数据管道, 日志审计, 暗色界面, 架构分析, 架构扫描, 架构边界, 程序破解, 结构体生命周期, 调用图, 软件工程, 错误基检测, 静态代码分析