简体中文 | English

Pprof Analyzer MCP 服务器

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

功能

• analyze_pprof Tool:
  • Analyzes the specified Go pprof file and returns serialized analysis results (e.g., Top N list or flame graph JSON).
  • Supported Profile Types:
    • cpu: Analyzes CPU time consumption during code execution to find hot spots.
    • heap: Analyzes the current memory usage (heap allocations) to find objects and functions with high memory consumption.
    • goroutine: Displays stack traces of all current goroutines, used for diagnosing deadlocks, leaks, or excessive goroutine usage.
    • allocs: Analyzes memory allocations (including freed ones) during program execution to locate code with frequent allocations. (Not yet implemented)
    • mutex: Analyzes contention on mutexes to find locks causing blocking. (Not yet implemented)
    • block: Analyzes operations causing goroutine blocking (e.g., channel waits, system calls). (Not yet implemented)
  • Supported Output Formats: text, markdown, json (Top N list), flamegraph-json (hierarchical flame graph data, default).
    • text, markdown: Human-readable text or Markdown format.
    • json: Outputs Top N results in structured JSON format (implemented for cpu, heap, goroutine).
    • flamegraph-json: Outputs hierarchical flame graph data in JSON format, compatible with d3-flame-graph (implemented for cpu, heap, default format). Output is compact.
  • Configurable number of Top N results (top_n, defaults to 5, effective for text, markdown, json formats).
• generate_flamegraph Tool:
  • Uses go tool pprof to generate a flame graph (SVG format) for the specified pprof file, saves it to the specified path, and returns the path and SVG content.
  • Supported Profile Types: cpu, heap, allocs, goroutine, mutex, block.
  • Requires the user to specify the output SVG file path.
  • Important: This feature depends on Graphviz being installed.
• open_interactive_pprof Tool (macOS Only):
  • Attempts to launch the go tool pprof interactive web UI in the background for the specified pprof file. Uses port :8081 by default if http_address is not provided.
  • Returns the Process ID (PID) of the background pprof process upon successful launch.
  • macOS Only: This tool will only work on macOS.
  • Dependencies: Requires the go command to be available in the system's PATH.
  • Limitations: Errors from the background pprof process are not captured by the server. Temporary files downloaded from remote URLs are not automatically cleaned up until the process is terminated (either manually via disconnect_pprof_session or when the MCP server exits).
• disconnect_pprof_session Tool:
  • Attempts to terminate a background pprof process previously started by open_interactive_pprof, using its PID.
  • Sends an Interrupt signal first, then a Kill signal if Interrupt fails.

安装（作为库/工具）

你可以直接使用 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 环境变量中）。

# Installs the executable using the module path defined in go.mod
go install .
# Or directly using the GitHub path (recommended after publishing)
# 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. 配置用于 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 来自动化发布过程。当推送到仓库的 Git 标签匹配模式 v*（例如 v0.1.0、v1.2.3）时，会自动触发发布。

发布步骤：

1. **进行更改：**开发新功能或修复错误。
2. **提交更改：**使用Conventional Commits格式提交您的更改（例如，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) 的二进制文件。
   • 基于自上次标签以来的 Conventional Commits 生成变更日志。
   • 创建一个新的 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 性能分析（文本格式，前 5 名）

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

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

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

示例：分析 Goroutine 配置文件（文本格式，前 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 格式，前 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 defaults to "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 原始 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 原始 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"
    // Optional: "http_address": ":8082" // Example of overriding the default port
  }
}

示例：断开 Pprof 会话

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // Replace 12345 with the actual PID returned by open_interactive_pprof
  }
}

未来改进（TODO）

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