JVMind MAT Heap Dump Analyzer

JVMind × MAT — Heap Dump Analysis

English | 中文

Java heap dump analysis built on the Eclipse Memory Analyzer (MAT) engine: upload → parse → MAT-like web queries → domain diagnostics (connection-pool leaks and more) → natural-language agent diagnosis.

Status: the Java parser and query service are tested. MCP Server v0.2.1 is published on PyPI and the official MCP Registry. Python platform integration is still in progress. See PROJECT-STATUS.md.

Quick start

1. Project overview → this file + mat-study/README.md (the design blueprint; Chinese).
2. Current progress → PROJECT-STATUS.md (completed work, remaining tasks, lessons learned).
3. Python team onboarding → TODO-PYTHON-TEAM.md (task list, API contract, acceptance criteria).
4. Run the query service → query-service/DEPLOY.md (deploy + curl verification).
5. Run the parser → parser-cli/v1-parsehd/README.md (no build required; uses the MAT distribution).
6. Analyze heap dumps from Claude/Cursor/VS Code → mcp-server/README.md (uvx jvmind-mat-mcp, local stdio).

MCP Server (published)

A local stdio MCP server that exposes MAT heap analysis to Claude Desktop, Cursor, and VS Code. It can discover local Java processes and capture a live heap dump from a running JVM, or open an existing .hprof file. Heap dumps never leave the machine; the MAT helper binds to 127.0.0.1 only.

uvx jvmind-mat-mcp doctor      # checks JDK 21 / MAT 1.17 / permissions

Capabilities: list_java_processes / dump_java_heap for live capture, open_heapdump for existing files, then mat_overview / mat_histogram / mat_dominator / mat_threads / mat_object / mat_path2gc / mat_oql / mat_leak_suspects / mat_diagnose_oom and more — 19 tools in total.

Requirements: Python 3.10+, JDK 21+, Eclipse MAT 1.17.x (a small query bundle is installed into MAT on first use).

Tools

All analysis tools take the report_id returned by open_heapdump.

• open_heapdump — open a local .hprof, start background indexing, return a report_id
• get_heapdump_status — poll parse status, progress, and phase
• list_heapdumps — list heap dumps known to this MCP server
• close_heapdump — release a heap dump handle and optionally stop the MAT helper
• list_java_processes — discover local attachable JVMs (pid, main class, command; MAT helper excluded)
• dump_java_heap — preview and capture a live heap dump, then start MAT parsing (confirm=true)
• mat_overview — heap overview: used/committed/live heap, object/class/classloader counts, JDK version
• mat_histogram — class histogram sorted by shallow, retained, or object count
• mat_dominator — dominator tree of the largest retained objects, with parent drill-down
• mat_threads — list threads or drill into stack frames and frame locals
• mat_threadlocals — inspect ThreadLocal values grouped by value class or thread
• mat_object — inspect a single object's fields, statics, references, and GC root
• mat_path2gc — shortest path from an object to a GC root
• mat_oql — run an OQL query and return rows plus a reusable result set id
• mat_leak_suspects — run LeakHunter and return suspects with retained sizes and descriptions
• mat_diagnose_oom — composite OOM diagnosis: leak suspects + SQL in threads + dominator analysis
• mat_connection_pools — diagnose database connection pools and leaked connections
• mat_top_consumers — top memory consumers by retained heap
• mat_sql_in_threads — find SQL statements in thread stacks

Architecture

  User uploads a heap dump
        │
   [Python/FastAPI]  ← in progress (TODO-PYTHON-TEAM.md)
   upload / queue / progress / auth / agent
        ├── fork ─────────────▶ [parser-cli / V1]  hprof → *.index   ✅ tested
        │                              (writes to NFS)
        └── reverse proxy ────▶ [query-service]    queries over indexes  ✅ tested
                                  (OSGi bundle, :8090)
                                  histogram / dominators / threads / OQL
                                  + Leak Suspects / path2gc etc.
         Shared: NFS (dump files) + PostgreSQL (tasks/reports)

  Local MCP path (v0.2.1 published):
  Claude Desktop / Cursor / VS Code
        │ stdio
        ▼
   [mcp-server] ──HTTP 127.0.0.1──▶ [query-service :8090]
        └── runs MAT ParseHeapDump when index files are missing
            (reuses the parser-cli V1 logic)

Repository layout

Top level

mat-study/ — design documents (Chinese)

parser-cli/ — parsing layer (hprof → index)

query-service/ — query layer (OSGi bundle, :8090) ✅

mcp-server/ — local stdio MCP (✅ v0.2.1 published)

marketplace/ — directory submission pack (🟡 prepared, not submitted)

Module status

Key facts (avoid re-learning these)

• MAT dependencies are not on Maven Central → use Tycho (eclipse-plugin) with a p2 repository or a local Directory target; do not add <dependencies>.
• Version ↔ JDK: 1.17 → JDK 21, 1.14 → JDK 17, 1.12 → JDK 11 (keep all three places in sync).
• Deployment: copy the jar into plugins/, add a line to bundles.info (auto-start=true), and restart with -clean (not dropins/).
• The query service has no authentication and is intranet-only. The Python proxy injects dumpDir (= the dump directory).
• Reopening a dump requires both the hprof and index files on a seekable filesystem (NFS works).
• MCP package jvmind-mat-mcp; Registry name io.github.kengrary/jvmind-mat. After changing the Java query layer, rerun mcp-server/scripts/vendor-bundle.sh, otherwise the wheel ships a stale bundle.
• On first use the MCP server writes com.jvmind.mat.query into MAT's plugins/ and bundles.info; the MAT install must be writable.
• Live capture uses jmap -dump:live: it dumps only live objects, triggers a Full GC, and may pause the target JVM. The default output is the server's current working directory; override it with JVMIND_MCP_DUMP_DIR or the tool's output_dir.
• Smithery is skipped for now: its web UI only exposes remote HTTPS URLs and the CLI server-creation endpoint was removed. MCPB artifacts are kept for a later retry. The Docker image is for directory review; real analysis still needs MAT + JDK 21 on the host.

Tech stack

• Parsing/query: Java 21 + Eclipse MAT 1.17 (OSGi/Equinox)
• MCP server: Python 3.10+ / MCP Python SDK 2.x / uv / stdio
• Platform/agent: Python + FastAPI (the existing JVMind platform)
• Storage: NFS (dump files) + PostgreSQL (tasks/reports)
• Distribution: PyPI + official MCP Registry; mcp.so, Glama, and PulseMCP materials are prepared; Smithery is skipped
• License: MIT for this project (see LICENSE); Eclipse MAT is EPL-2.0 and is not redistributed