Pprof Analyzer MCP Server

Features

• **`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](#dependencies) 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.

Installation (As a Library/Tool)

Building from Source

Using `go install` (Recommended)

Running with Docker

1. **Build the Docker Image:** In the project root directory (where the `Dockerfile` is located), run: ```bash docker build -t pprof-analyzer-mcp . ```

2. **Run the Docker Container:** ```bash docker run -i --rm pprof-analyzer-mcp ``` * The `-i` flag keeps STDIN open, which is required for the stdio transport used by this MCP server. * The `--rm` flag automatically removes the container when it exits.

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`: ```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)

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

2. **Commit Changes:** Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat: ...`, `fix: ...`). This is important for automatic changelog generation. ```bash git add . git commit -m "feat: Add awesome new feature" # or git commit -m "fix: Resolve issue #42" ```

3. **Push Changes:** Push your commits to the main branch on GitHub. ```bash git push origin main ```

4. **Create and Push Tag:** When ready to release, create a new Git tag and push it to GitHub. ```bash # Example: Create tag v0.1.0 git tag v0.1.0 # Push the tag to GitHub git push origin v0.1.0 ```

5. **Automatic Release:** Pushing the tag will trigger the `GoReleaser` GitHub Action defined in `.github/workflows/release.yml`. This action will: * Build binaries for Linux, macOS, and Windows (amd64 & arm64). * Generate a changelog based on Conventional Commits since the last tag. * Create a new GitHub Release with the changelog and attach the built binaries and checksums as assets.

Configuring the MCP Client

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:** * **macOS (using Homebrew):** ```bash brew install graphviz ``` * **Debian/Ubuntu:** ```bash sudo apt-get update && sudo apt-get install graphviz ``` * **CentOS/Fedora:** ```bash sudo yum install graphviz # or sudo dnf install graphviz ``` * **Windows (using Chocolatey):** ```bash choco install graphviz ``` * **Other Systems:** Refer to the [Graphviz official download page](https://graphviz.org/download/).

Usage Examples (via MCP Client)

Future Improvements (TODO)

• Implement full analysis logic for `allocs`, `mutex`, `block` profiles.

• Implement `json` output format for `allocs`, `mutex`, `block` profile types.

• Set appropriate MIME types in MCP results based on `output_format`.

• Add more robust error handling and logging level control.

• ~~Consider supporting remote pprof file URIs (e.g., `http://`, `https://`).~~ (Done)