简体中文 | English

Pprof Analyzer MCP Server

This is a Model Context Protocol (MCP) server implemented in Go, providing a tool to analyze Go pprof performance profiles. Built with the official Model Context Protocol Go SDK.

Features

• `analyze_pprof` Tool:
• `generate_flamegraph` Tool:
• `open_interactive_pprof` Tool (macOS Only):
• `detect_memory_leaks` Tool:
• `disconnect_pprof_session` Tool:
• `compare_profiles` Tool:
• `analyze_heap_time_series` Tool:

Installation (As a Library/Tool)

You can install this package directly using `go install`:

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

This will install the `pprof-analyzer-mcp` executable to your `$GOPATH/bin` or `$HOME/go/bin` directory. Ensure this directory is in your system's PATH to run the command directly.

Building from Source

Ensure you have a Go environment installed (Go 1.18 or higher recommended).

In the project root directory (`pprof-analyzer-mcp`), run:

go build

This will generate an executable file named `pprof-analyzer-mcp` (or `pprof-analyzer-mcp.exe` on Windows) in the current directory.

Using `go install` (Recommended)

You can also use `go install` to install the executable into your `$GOPATH/bin` or `$HOME/go/bin` directory. This allows you to run `pprof-analyzer-mcp` directly from the command line (if the directory is added to your system's PATH environment variable).

# 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

Running with Docker

Using Docker is a convenient way to run the server, as it bundles the necessary Graphviz dependency.

1. Build the Docker Image:

In the project root directory (where the `Dockerfile` is located), run:

docker build -t pprof-analyzer-mcp .

2. Run the Docker Container:

docker run -i --rm pprof-analyzer-mcp

3. Configure MCP Client for Docker:

To connect your MCP client (like Roo Cline) to the server running inside Docker, update your `.roo/mcp.json`:

{
      "mcpServers": {
        "pprof-analyzer-docker": {
          "command": "docker run -i --rm pprof-analyzer-mcp"
        }
      }
    }

Make sure the `pprof-analyzer-mcp` image has been built locally before the client tries to run this command.

Releasing (Automated via GitHub Actions)

This project uses GoReleaser and GitHub Actions to automate the release process. Releases are triggered automatically when a Git tag matching the pattern `v*` (e.g., `v0.1.0`, `v1.2.3`) is pushed to the repository.

Pre-release Checklist:

Before creating a release tag, ensure:

• ✅ All tests pass: `go test ./...`
• ✅ Code compiles successfully: `go build`
• ✅ Documentation is up to date (README, CHANGELOG, etc.)
• ✅ Commit messages follow Conventional Commits format

Release Steps:

1. Make Changes: Develop new features or fix bugs.

2. Commit Changes: Commit your changes using Conventional Commits format (e.g., `feat: ...`, `fix: ...`, `docs: ...`). This is important for automatic changelog generation.

git add .
    git commit -m "feat: Add awesome new feature"
    # or
    git commit -m "fix: Resolve issue #42"
    # or
    git commit -m "docs: Update README for new feature"

3. Push Changes: Push your commits to the main branch on GitHub.

git push origin main

4. Run Pre-release Tests: Optionally, run tests locally before tagging:

go test ./... -v
    go build -v

5. Create and Push Tag: When ready to release, create a new Git tag and push it to GitHub.

# Example: Create tag v0.2.0
    git tag v0.2.0

    # Push the tag to GitHub
    git push origin v0.2.0

6. Automatic Release: Pushing the tag will trigger the `GoReleaser` GitHub Action defined in `.github/workflows/release.yml`. This action will:

Monitoring the Release:

You can view the release workflow progress in the "Actions" tab of the GitHub repository. Once complete, the release will be available at:

https://github.com/ZephyrDeng/pprof-analyzer-mcp/releases

Configuring the MCP Client

This server uses the `stdio` transport protocol. You need to configure it in your MCP client (e.g., Roo Cline extension for VS Code).

Typically, this involves adding the following configuration to the `.roo/mcp.json` file in your project root:

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

Note: Adjust the `command` value based on your build method (`go build` or `go install`) and the actual location of the executable. Ensure the MCP client can find and execute this command.

After configuration, reload or restart your MCP client, and it should automatically connect to the `PprofAnalyzer` server.

Dependencies

• Graphviz: The `generate_flamegraph` tool requires Graphviz to generate SVG flame graphs (the `go tool pprof` command calls `dot` when generating SVG). Ensure Graphviz is installed on your system and the `dot` command is available in your system's PATH environment variable.

Installing Graphviz:

brew install graphviz

sudo apt-get update && sudo apt-get install graphviz

sudo yum install graphviz
        # or
        sudo dnf install graphviz

choco install graphviz

Usage Examples (via MCP Client)

Once the server is connected, you can call the `analyze_pprof` and `generate_flamegraph` tools using `file://`, `http://`, or `https://` URIs for the profile file.

Example: Analyze CPU Profile (Text format, Top 5)

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

Example: Analyze Heap Profile (Markdown format, Top 10)

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

Example: Analyze Goroutine Profile (Text format, Top 5)

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

Example: Generate Flame Graph for CPU Profile

{
  "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"
  }
}

Example: Generate Flame Graph for Heap Profile (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"
  }
}

Example: Analyze CPU Profile (JSON format, Top 3)

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

Example: Analyze CPU Profile (Default Flame Graph JSON format)

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

Example: Analyze Heap Profile (Explicitly Flame Graph JSON format)

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

Example: Analyze Remote CPU Profile (from HTTP URL)

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

Example: Analyze Online CPU Profile (from 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
  }
}

Example: Generate Flame Graph for Online Heap Profile (from 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"
  }
}

Example: Open Interactive Pprof UI for Online CPU Profile (macOS Only)

{
  "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
  }
}

Example: Detect Memory Leaks Between Two Heap Profiles

{
  "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% growth threshold
    "limit": 15         // Show top 15 potential leaks
  }
}

Example: Disconnect a Pprof Session

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

Future Improvements (TODO)

• Add MIME type handling in MCP results based on `output_format`.
• Add more robust error handling and logging level control.
• Add integration tests for end-to-end MCP tool interactions.
• Performance optimizations for large profile files (>1GB).

Recently Completed (v0.3.0)

• ✅ ~~Implement differential flame graphs to visualize changes between profiles.~~ (Done - `compare_profiles` tool)
• ✅ ~~Add time-series analysis for memory profiles to track growth over multiple snapshots.~~ (Done - `analyze_heap_time_series` tool)
• ✅ Add automated CI/CD with GitHub Actions testing on every PR.
• ✅ ~~Implement full analysis logic for `mutex`, `block` profiles.~~ (Done in v0.2.0)
• ✅ ~~Implement `json` output format for `mutex`, `block` profile types.~~ (Done in v0.2.0)
• ✅ Migrated to official Model Context Protocol Go SDK.
• ✅ ~~Consider supporting remote pprof file URIs (e.g., `http://`, `https://`).~~ (Done in v0.2.0)
• ✅ ~~Implement full analysis logic for `allocs` profiles.~~ (Done in v0.2.0)
• ✅ ~~Implement `json` output format for `allocs` profile type.~~ (Done in v0.2.0)
• ✅ ~~Add memory leak detection capabilities.~~ (Done in v0.2.0)