技术文档摘要

简体中文 | English

Pprof Analyzer MCP Server

[](https://github.com/ZephyrD eng/pprof-analyzer-mcp/actions)

这是一个用 Go 实现的 Model Context Protocol (MCP) 服务器，提供了一个工具来分析 Go pprof 性能配置文件。

功能

• analyze_pprof 工具：
  • 分析指定的 Go pprof 文件，并返回序列化的分析结果（例如，Top N 列表或火焰图 JSON）。
  • 支持的配置文件类型：
    • cpu：分析代码执行期间的 CPU 时间消耗以找到热点。
    • heap：分析当前内存使用情况（堆分配）以找到高内存消耗的对象和函数。增强对象计数、分配位置和类型信息。
    • goroutine：显示所有当前 goroutine 的堆栈跟踪，用于诊断死锁、泄漏或过度使用 goroutine。
    • allocs：分析程序执行期间的内存分配（包括已释放的）以定位频繁分配的代码。提供详细的分配位置和对象计数信息。
    • mutex：分析互斥锁的竞争以找到导致阻塞的锁。（尚未实现）
    • block：分析导致 goroutine 阻塞的操作（例如，通道等待、系统调用）。（尚未实现）
  • 支持的输出格式：text，markdown，json（Top N 列表），flamegraph-json（分层火焰图数据，默认）。
    • text，markdown：人类可读的文本或 Markdown 格式。
    • json：以结构化 JSON 格式输出 Top N 结果（已实现 cpu，heap，goroutine，allocs）。
    • flamegraph-json：以 JSON 格式输出分层火焰图数据，兼容 d3-flame-graph（已实现 cpu，heap，allocs，默认格式）。输出是紧凑的。
  • 可配置的 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 服务器退出）。
• detect_memory_leaks 工具：
  • 比较两个堆配置文件快照以识别潜在的内存泄漏。
  • 分析按对象类型和分配位置的内存增长。
  • 提供详细的内存增长统计，包括绝对变化和百分比变化。
  • 可配置的增长阈值和结果限制。
  • 通过比较不同时间点的配置文件帮助识别内存泄漏。
• disconnect_pprof_session 工具：
  • 尝试使用其 PID 终止之前由 open_interactive_pprof 启动的后台 pprof 进程。
  • 先发送中断信号，如果中断失败则发送杀死信号。

安装（作为库/工具）

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

go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

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

从源码构建

确保您已安装 Go 环境（推荐 Go 1.18 或更高版本）。

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

go build

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

使用 go install（推荐）

您也可以使用 go install 将可执行文件安装到您的 $GOPATH/bin 或 $HOME/go/bin 目录中。这允许您直接从命令行运行 pprof-analyzer-mcp（如果该目录添加到了您的系统 PATH 环境变量中）。

# 使用 go.mod 中定义的模块路径安装可执行文件
go install .
# 或直接使用 GitHub 路径（发布后推荐）
# go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

使用 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. 配置 MCP 客户端以使用 Docker： 要将您的 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. 进行更改： 开发新功能或修复 bug。
2. 提交更改： 使用 常规提交 格式提交更改（例如，feat: ...，fix: ...）。这对于自动生成变更日志很重要。

   git add .
   git commit -m "feat: 添加了很棒的新功能"
   # 或
   git commit -m "fix: 解决问题 #42"
   

3. 推送更改： 将您的提交推送到 GitHub 的主分支。

   git push origin main
   

4. 创建并推送标签： 准备好发布时，创建一个新的 Git 标签并将其推送到 GitHub。

   # 示例：创建标签 v0.1.0
   git tag v0.1.0
   
   # 将标签推送到 GitHub
   git push origin v0.1.0
   

5. 自动发布： 推送标签将触发在 .github/workflows/release.yml 中定义的 GoReleaser GitHub Action。此操作将：
   • 构建适用于 Linux、macOS 和 Windows（amd64 & arm64）的二进制文件。
   • 根据自上次标签以来的常规提交生成变更日志。
   • 创建新的 GitHub 发布，附带生成的二进制文件和校验和作为资产。

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

配置 MCP 客户端

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

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

{
  "mcpServers": {
    "pprof-analyzer": {
      "command": "pprof-analyzer-mcp"
    }
  }
}

注意： 根据您的构建方法（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
    # 或
    sudo dnf install graphviz
    

  • Windows（使用 Chocolatey）：

    choco install graphviz
    

  • 其他系统： 请参阅 Graphviz 官方下载页面。

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

一旦服务器连接成功，您可以使用 file://，http:// 或 https:// URI 对 analyze_pprof 和 generate_flamegraph 工具进行调用。

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "top_n": 10,
    "output_format": "markdown"
  }
}

示例：分析 goroutine 配置文件（文本格式，Top 5）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/goroutine.pprof",
    "profile_type": "goroutine"
  }
}

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

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "output_svg_path": "/path/to/save/cpu_flamegraph.svg"
  }
}

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

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_svg_path": "/path/to/save/heap_flamegraph.svg"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "top_n": 3,
    "output_format": "json"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
    // output_format 默认为 "flamegraph-json"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_format": "flamegraph-json"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://example.com/profiles/cpu.pprof",
    "profile_type": "cpu"
  }
}

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

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu",
    "profile_type": "cpu",
    "top_n": 5
  }
}

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

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.heap",
    "profile_type": "heap",
    "output_svg_path": "./online_heap_flamegraph.svg"
  }
}

示例：打开在线 CPU 配置文件的交互式 Pprof UI（仅限 macOS）

{
  "tool_name": "open_interactive_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu"
    // 可选："http_address": ":8082" // 示例覆盖默认端口
  }
}

示例：检测两个堆配置文件之间的内存泄漏

{
  "tool_name": "detect_memory_leaks",
  "arguments": {
    "old_profile_uri": "file:///path/to/your/heap_before.pprof",
    "new_profile_uri": "file:///path/to/your/heap_after.pprof",
    "threshold": 0.05,  // 5% 增长阈值
    "limit": 15         // 显示前 15 个潜在泄漏
  }
}

示例：断开 Pprof 会话

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // 替换 12345 为 `open_interactive_pprof` 返回的实际 PID
  }
}

未来改进（待办事项）

• 实现 mutex，block 配置文件的完整分析逻辑。
• 实现 mutex，block 配置文件类型的 json 输出格式。
• 根据 output_format 设置 MCP 结果中的适当 MIME 类型。
• 添加更强大的错误处理和日志级别控制。
• 添加对远程 pprof 文件 URI（例如，http://，https://）的支持。（已完成）
• 实现 allocs 配置文件的完整分析逻辑。（已完成）
• 实现 allocs 配置文件类型的 json 输出格式。（已完成）
• 添加内存泄漏检测能力。（已完成）
• 添加对内存配置文件的时间序列分析，以跟踪多个快照中的增长。
• 实现差异火焰图以可视化配置文件之间的变化。