mcp-pprof-anaylzer

简体中文| English

Pprof 分析器 MCP 服务器

这是一个用 Go 实现的模型上下文协议 (MCP) 服务器，提供了分析 Go pprof 性能配置文件的工具。

特征

• analyze_pprof工具：
  • 分析指定的 Go pprof 文件并返回序列化的分析结果（例如，Top N 列表或火焰图 JSON）。
  • 支持的配置文件类型：
    • cpu ：分析代码执行过程中的 CPU 时间消耗，以查找热点。
    • heap ：分析当前内存使用情况（堆分配）以查找内存消耗高的对象和函数。
    • goroutine ：显示所有当前 goroutine 的堆栈跟踪，用于诊断死锁、泄漏或过度使用 goroutine。
    • allocs ：分析程序执行期间的内存分配（包括已释放的内存），以定位频繁分配的代码。（尚未实现）
    • mutex ：分析互斥锁的争用情况，查找导致阻塞的锁。（尚未实现）
    • block ：分析导致 goroutine 阻塞的操作（例如，通道等待、系统调用）。（尚未实现）
  • 支持的输出格式： text 、 markdown 、 json （前 N 个列表）、 flamegraph-json （分层火焰图数据，默认）。
    • text ， markdown ：人类可读的文本或 Markdown 格式。
    • json ：以结构化的 JSON 格式输出 Top N 结果（针对cpu 、 heap 、 goroutine实现）。
    • flamegraph-json ：以 JSON 格式输出分层火焰图数据，兼容 d3-flame-graph（已实现cpu 、 heap和默认格式）。输出紧凑。
  • 可配置 Top N 结果数量（ top_n ，默认为 5，对text 、 markdown 、 json格式有效）。
• generate_flamegraph工具：
  • 使用go tool pprof为指定的 pprof 文件生成火焰图（SVG 格式），保存到指定路径，并返回路径和 SVG 内容。
  • 支持的配置文件类型： cpu 、 heap 、 allocs 、 goroutine 、 mutex 、 block 。
  • 要求用户指定输出 SVG 文件路径。
  • **重要提示：**此功能依赖于已安装的Graphviz 。
• open_interactive_pprof工具（仅限 macOS）：
  • 尝试在后台为指定的 pprof 文件启动go tool pprof交互式 Web UI。如果未提供http_address ，则默认使用端口:8081 。
  • 成功启动后返回后台pprof进程的进程 ID (PID)。
  • **仅限 macOS：**此工具仅适用于 macOS。
  • **依赖项：**要求go命令在系统的 PATH 中可用。
  • **限制：**服务器无法捕获后台pprof进程产生的错误。从远程 URL 下载的临时文件直到进程终止（手动通过disconnect_pprof_session或 MCP 服务器退出）才会自动清理。
• disconnect_pprof_session工具：
  • 尝试使用其 PID 终止先前由open_interactive_pprof启动的后台pprof进程。
  • 首先发送中断信号，如果中断失败则发送终止信号。

安装（作为库/工具）

您可以使用go install直接安装此软件包：

这会将pprof-analyzer-mcp可执行文件安装到你的$GOPATH/bin或$HOME/go/bin目录。确保此目录位于系统 PATH 中，以便直接运行该命令。

从源代码构建

确保您已安装 Go 环境（建议使用 Go 1.18 或更高版本）。

在项目根目录（ pprof-analyzer-mcp ）中，运行：

这将在当前目录中生成一个名为pprof-analyzer-mcp （或 Windows 上的pprof-analyzer-mcp.exe ）的可执行文件。

使用go install （推荐）

你也可以使用go install将可执行文件安装到$GOPATH/bin或$HOME/go/bin目录中。这样你就可以直接从命令行运行pprof-analyzer-mcp （前提是该目录已添加到系统的 PATH 环境变量中）。

使用 Docker 运行

使用 Docker 是运行服务器的一种便捷方式，因为它捆绑了必要的 Graphviz 依赖项。

1. **构建 Docker 镜像：**在项目根目录（ Dockerfile所在的位置）中运行：
   docker build -t pprof-analyzer-mcp .
2. 运行 Docker 容器：
   docker run -i --rm pprof-analyzer-mcp
   • -i标志保持 STDIN 打开，这是此 MCP 服务器使用的 stdio 传输所必需的。
   • --rm标志会在容器退出时自动删除该容器。
3. **为 Docker 配置 MCP 客户端：**要将您的 MCP 客户端（如 Roo Cline）连接到 Docker 内运行的服务器，请更新您的.roo/mcp.json ：
   { "mcpServers": { "pprof-analyzer-docker": { "command": "docker run -i --rm pprof-analyzer-mcp" } } }
   在客户端尝试运行此命令之前，请确保pprof-analyzer-mcp映像已在本地构建。

发布（通过 GitHub Actions 自动执行）

该项目使用GoReleaser和 GitHub Actions 来自动化发布流程。当符合v*模式的 Git 标签（例如v0.1.0 、 v1.2.3 ）推送到代码库时，会自动触发发布。

发布步骤：

1. **进行更改：**开发新功能或修复错误。
2. **提交变更：**使用常规提交格式提交变更（例如， feat: ... 、 fix: ... ）。这对于自动生成变更日志至关重要。
   git add . git commit -m "feat: Add awesome new feature" # or git commit -m "fix: Resolve issue #42"
3. **推送更改：**将您的提交推送到 GitHub 上的主分支。
   git push origin main
4. **创建并推送标签：**准备发布时，创建一个新的 Git 标签并将其推送到 GitHub。
   # Example: Create tag v0.1.0 git tag v0.1.0 # Push the tag to GitHub git push origin v0.1.0
5. **自动发布：**推送标签将触发.github/workflows/release.yml中定义的GoReleaser GitHub Action。此操作将：
   • 为 Linux、macOS 和 Windows（amd64 和 arm64）构建二进制文件。
   • 根据自上次标记以来的常规提交生成变更日志。
   • 使用变更日志创建一个新的 GitHub 版本，并将构建的二进制文件和校验和作为资产附加。

您可以在 GitHub 仓库的“操作”选项卡中查看发布工作流程进度。

配置 MCP 客户端

此服务器使用stdio传输协议。您需要在 MCP 客户端（例如 VS Code 的 Roo Cline 扩展）中进行配置。

通常，这涉及将以下配置添加到项目根目录中的.roo/mcp.json文件：

**注意：**请根据您的构建方法（ go build或go install ）以及可执行文件的实际位置调整command值。确保 MCP 客户端能够找到并执行此命令。

配置完成后，重新加载或重新启动您的 MCP 客户端，它应该自动连接到PprofAnalyzer服务器。

依赖项

• Graphviz ： generate_flamegraph工具需要 Graphviz 来生成 SVG 火焰图（ go tool pprof命令在生成 SVG 时会调用dot ）。请确保您的系统已安装 Graphviz，并且dot命令已添加到系统的 PATH 环境变量中。安装 Graphviz：
  • macOS（使用 Homebrew）：
    brew install graphviz
  • Debian/Ubuntu：
    sudo apt-get update && sudo apt-get install graphviz
  • CentOS/Fedora：
    sudo yum install graphviz # or sudo dnf install graphviz
  • Windows（使用 Chocolatey）：
    choco install graphviz
  • **其他系统：**参考Graphviz官方下载页面。

使用示例（通过 MCP 客户端）

连接服务器后，您可以使用file:// 、 http://或https:// URI 调用analyze_pprof和generate_flamegraph工具来获取配置文件。

示例：分析 CPU 配置文件（文本格式，前 5 名）

示例：分析堆配置文件（Markdown 格式，前 10 名）

示例：分析 Goroutine Profile（文本格式，Top 5）

示例：生成 CPU 配置文件的火焰图

示例：为堆配置文件生成火焰图（inuse_space）

示例：分析 CPU 配置文件（JSON 格式，Top 3）

示例：分析 CPU 配置文件（默认火焰图 JSON 格式）

示例：分析堆配置文件（显式火焰图 JSON 格式）

示例：分析远程 CPU 配置文件（来自 HTTP URL）

示例：分析在线 CPU 配置文件（来自 GitHub 原始 URL）

示例：为在线堆配置文件生成火焰图（来自 GitHub 原始 URL）

示例：打开交互式 Pprof UI 进行在线 CPU 性能分析（仅限 macOS）

示例：断开 Pprof 会话

未来改进（TODO）

• 实现allocs 、 mutex 、 block profiles 的完整分析逻辑。
• 为allocs 、 mutex 、 block配置文件类型实现json输出格式。
• 根据output_format在 MCP 结果中设置适当的 MIME 类型。
• 添加更强大的错误处理和日志级别控制。
• ~~考虑支持远程 pprof 文件 URI（例如， http:// 、 https:// ）。~~（已完成）