HeapDumpStarDiver MCP Server

MCP (Model Context Protocol) server for JVM heap dump analysis. Converts HPROF heap dumps to Parquet files and provides DuckDB-powered SQL querying and automated memory waste detection — all accessible to any MCP-compatible AI agent.

Install

pip install heapdump-stardiver-mcp

Prerequisites

The convert_heap_dump tool requires the HeapDumpStarDiver Rust binary. Build it from source:

git clone https://github.com/ZacAttack/HeapDumpStarDiver.git
cd HeapDumpStarDiver
cargo build --release

Or set HEAP_DUMP_STAR_DIVER_BINARY_OVERRIDE to point at a pre-built binary.

If you only need to analyze existing Parquet files (via open_session), the Rust binary is not required.

Agent Configuration

Add to your agent's MCP config:

{
  "mcpServers": {
    "heapdump-stardiver": {
      "command": "heapdump-stardiver-mcp"
    }
  }
}

Available Tools

Typical Workflow

1. convert_heap_dump(hprof_path="/path/to/dump.hprof") — convert and open session
2. list_parquet_files() — discover available tables
3. analyze_heap() — automated waste detection (duplicate strings, bad collections, boxed primitives, etc.)
4. query_heap(sql="SELECT ...") — ad-hoc DuckDB queries
5. close_session(id) or cleanup_session(id, confirm=True)

Waste Analysis

The analyze_heap tool detects common JVM memory waste patterns across 3 tiers:

• Tier 1 (fast): Duplicate strings, empty/single-element collections, bad arrays, boxed primitives
• Tier 2 (default): + collection sizing, duplicate byte arrays, class count, GC roots, DirectByteBuffers, thread stacks
• Tier 3 (thorough): + duplicate object arrays, estimated shallow sizes

License

MIT