heapdump-stardiver-mcp 0.1.2

MCP server for HeapDumpStarDiver - JVM heap dump analysis with DuckDB

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

Agent	Config file
Claude Code	.mcp.json in repo root
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Cursor	.cursor/mcp.json in repo root
Kiro	.kiro/settings/mcp.json in repo root

Available Tools

Tool	Description
convert_heap_dump	Convert HPROF → Parquet and open analysis session
open_session	Open session from existing Parquet files
list_sessions	Show all active sessions
close_session	Close DuckDB connection, keep files
cleanup_session	Close connection and delete Parquet files
list_parquet_files	List tables with row counts and schemas
query_heap	Run DuckDB SQL against Parquet (paginated)
analyze_heap	Automated waste detection and heap profiling

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