mcp-jvm-diagnostics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmytro Lisnichenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,165 @@
+[![npm version](https://img.shields.io/npm/v/mcp-jvm-diagnostics)](https://www.npmjs.com/package/mcp-jvm-diagnostics)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+# MCP JVM Diagnostics
+
+A Model Context Protocol (MCP) server that gives AI assistants the ability to analyze JVM thread dumps and GC logs. It detects deadlocks, identifies lock contention hotspots, analyzes garbage collection pressure, and recommends JVM tuning parameters.
+
+## Why This Tool?
+
+JVM diagnostic MCP servers exist (TDA, jfr-mcp, Arthas) — but they're all **Java-based**, requiring a JVM runtime just to diagnose JVM problems. This tool runs on **Node.js** via `npx` — no JVM, no Docker, no SSH.
+
+It analyzes **offline** artifacts (thread dumps, GC logs, heap histograms) rather than requiring a running JVM. Paste a thread dump or GC log and get instant analysis. Part of the [MCP Java Backend Suite](https://www.npmjs.com/package/mcp-java-backend-suite) — 5 tools covering databases, JVM, migrations, Spring Boot, and Redis for Java backend developers.
+
+## Features
+
+- **6 MCP tools** for comprehensive JVM diagnostics
+- **Thread dump analysis** — deadlock detection, contention hotspots, thread state breakdown
+- **GC log analysis** — pause statistics, heap trends, memory leak detection
+- **Heap histogram analysis** — memory leak candidates, classloader leaks, finalization issues
+- **JFR summary** — Java Flight Recorder file analysis
+- **Unified diagnosis** — cross-correlates thread and GC data
+- **Supports** G1, ZGC, Parallel, Serial, and Shenandoah GC formats
+- **No external dependencies** — works on local text input, no API keys needed
+
+## Installation
+
+```bash
+npx mcp-jvm-diagnostics
+```
+
+Or install globally:
+
+```bash
+npm install -g mcp-jvm-diagnostics
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "jvm-diagnostics": {
+      "command": "npx",
+      "args": ["-y", "mcp-jvm-diagnostics"]
+    }
+  }
+}
+```
+
+No environment variables needed — this tool works on text input you provide.
+
+## Quick Demo
+
+Try these prompts in Claude (paste your JVM output):
+
+1. **"Analyze this thread dump: [paste jstack output]"** — Detects deadlocks, contention hotspots, and thread state breakdown
+2. **"Analyze this GC log: [paste GC log]"** — Shows pause statistics, heap trends, and tuning recommendations
+3. **"Compare these heap histograms to find memory leaks: BEFORE: [paste] AFTER: [paste]"** — Identifies growing classes, classloader leaks, and finalizer issues
+
+## Tools
+
+### `analyze_thread_dump`
+
+Parse a JVM thread dump and analyze thread states, detect deadlocks, and identify lock contention.
+
+**Parameters:**
+- `thread_dump` — The full thread dump text (from `jstack <pid>`, `kill -3`, or VisualVM)
+
+**Example prompt:** "Analyze this thread dump and tell me if there are any deadlocks"
+
+### `analyze_gc_log`
+
+Parse a GC log and analyze garbage collection patterns, pause times, and memory pressure.
+
+**Parameters:**
+- `gc_log` — The GC log text (from `-Xlog:gc*` or `-verbose:gc`)
+
+**Example prompt:** "Analyze this GC log and tell me if there are any performance issues"
+
+### `analyze_heap_histo`
+
+Parse `jmap -histo` output and detect memory leak candidates, object creation hotspots, and classloader leaks.
+
+**Parameters:**
+- `histo` — The jmap -histo output text (from `jmap -histo <pid>` or `jmap -histo:live <pid>`)
+
+**Example prompt:** "Analyze this heap histogram and tell me if there are any memory leak candidates"
+
+### `diagnose_jvm`
+
+Unified JVM diagnosis combining thread dump and GC log analysis for comprehensive root cause analysis.
+
+**Parameters:**
+- `thread_dump` (optional) — Thread dump text
+- `gc_log` (optional) — GC log text
+
+**Example prompt:** "I have both a thread dump and GC log from the same time — diagnose what's wrong"
+
+### `compare_heap_histos`
+
+Compare two `jmap -histo` snapshots taken at different times to detect memory growth patterns and leak candidates.
+
+**Parameters:**
+- `before` — The first (earlier) jmap -histo output
+- `after` — The second (later) jmap -histo output
+
+**Example prompt:** "Compare these two heap histograms and tell me what's growing"
+
+**Detects:**
+- Classes with growing instance/byte counts (leak candidates)
+- New classes that appeared between snapshots
+- Classes that disappeared (GC'd or unloaded)
+- Overall heap growth rate
+- Classloader leaks and finalizer queue growth
+
+## Collecting JVM Diagnostics
+
+### Thread Dump
+```bash
+# Using jstack
+jstack <pid> > thread-dump.txt
+
+# Using kill signal (Linux/Mac)
+kill -3 <pid>
+
+# Using jcmd
+jcmd <pid> Thread.print > thread-dump.txt
+```
+
+### GC Log
+Add these JVM flags to your application:
+```bash
+# Java 9+ (unified logging)
+-Xlog:gc*:file=gc.log:time,level,tags
+
+# Java 8
+-verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:gc.log
+```
+
+## Contributing
+
+1. Clone the repo
+2. `npm install`
+3. `npm run build`
+4. `npm test`
+
+## Limitations & Known Issues
+
+- **Text input only**: Thread dumps, GC logs, and heap histograms must be provided as text. The server cannot attach to a running JVM or capture data automatically.
+- **Java 9+ GC logs**: The GC log parser is optimized for unified logging format (`-Xlog:gc*`). Legacy `-verbose:gc` format (Java 8) has basic support but may miss some events.
+- **Shenandoah GC**: Limited support. G1, ZGC, Parallel, and Serial are fully supported.
+- **Virtual threads (Java 21+)**: Thread dump parser handles virtual threads but analysis recommendations are tuned for platform threads.
+- **Heap histo comparison**: Requires standard `jmap -histo` or `jcmd GC.class_histogram` format. Custom formats or truncated output may not parse correctly.
+- **Deadlock detection**: Detects monitor-based deadlocks. ReentrantLock deadlocks may not be detected if lock addresses are not visible in the thread dump.
+- **No historical analysis**: Each analysis is a point-in-time snapshot. For trend analysis, compare multiple snapshots manually.
+- **HotSpot/OpenJDK only**: Parser targets HotSpot/OpenJDK thread dump format. GraalVM native-image or Eclipse OpenJ9 dumps may parse incompletely.
+- **Classloader leak detection**: Heap analysis flags growing ClassLoader instances but cannot definitively prove a leak without memory profiler data.
+
+## License
+
+MIT

package/build/analyzers/contention.js

@@ -0,0 +1,64 @@
+/**
+ * Lock contention analyzer.
+ *
+ * Identifies the most-contended locks and most-blocked threads.
+ * Generates actionable recommendations.
+ */
+export function analyzeContention(threads) {
+    // Map: lock address → thread holding it
+    const lockHolders = new Map();
+    for (const t of threads) {
+        for (const lock of t.holdsLocks) {
+            lockHolders.set(lock, t.name);
+        }
+    }
+    // Map: lock address → threads blocked on it
+    const blockedOn = new Map();
+    for (const t of threads) {
+        if (t.state === "BLOCKED" && t.blockedBy) {
+            const existing = blockedOn.get(t.blockedBy) || [];
+            existing.push(t.name);
+            blockedOn.set(t.blockedBy, existing);
+        }
+    }
+    // Build hotspot list sorted by blocked count
+    const hotspots = [];
+    for (const [lock, waitingThreads] of blockedOn.entries()) {
+        hotspots.push({
+            lock,
+            blockedCount: waitingThreads.length,
+            holderThread: lockHolders.get(lock) || "unknown",
+            waitingThreads,
+        });
+    }
+    hotspots.sort((a, b) => b.blockedCount - a.blockedCount);
+    // Generate recommendations
+    const recommendations = [];
+    const totalBlocked = threads.filter(t => t.state === "BLOCKED").length;
+    const totalThreads = threads.length;
+    if (totalBlocked > 0) {
+        const pct = ((totalBlocked / totalThreads) * 100).toFixed(0);
+        recommendations.push(`${totalBlocked} of ${totalThreads} threads (${pct}%) are BLOCKED — investigate contended locks.`);
+    }
+    if (hotspots.length > 0 && hotspots[0].blockedCount >= 5) {
+        recommendations.push(`Lock \`${hotspots[0].lock}\` held by "${hotspots[0].holderThread}" is blocking ${hotspots[0].blockedCount} threads. This is a critical hotspot — consider reducing the lock scope or using a read-write lock.`);
+    }
+    if (hotspots.length > 3) {
+        recommendations.push("Multiple contention hotspots detected. Consider redesigning synchronization — ConcurrentHashMap, read-write locks, or lock-free data structures may reduce contention.");
+    }
+    // Check for thread pool exhaustion
+    const poolPatterns = ["pool-", "http-", "exec-", "ForkJoin", "worker-"];
+    for (const pattern of poolPatterns) {
+        const poolThreads = threads.filter(t => t.name.includes(pattern));
+        const poolBlocked = poolThreads.filter(t => t.state === "BLOCKED");
+        if (poolThreads.length > 0 && poolBlocked.length > poolThreads.length * 0.5) {
+            recommendations.push(`Thread pool "${pattern}*" has ${poolBlocked.length}/${poolThreads.length} threads BLOCKED — pool exhaustion risk. Consider increasing pool size or reducing lock hold time.`);
+        }
+    }
+    // Check for WAITING threads that might indicate starvation
+    const waitingCount = threads.filter(t => t.state === "WAITING").length;
+    if (waitingCount > totalThreads * 0.7) {
+        recommendations.push(`${waitingCount} of ${totalThreads} threads are WAITING — possible thread starvation. Check if producer threads are stuck or undersized.`);
+    }
+    return { hotspots, recommendations };
+}

package/build/analyzers/deadlock.js

@@ -0,0 +1,89 @@
+/**
+ * Deadlock detector.
+ *
+ * Builds a lock wait graph from thread dump data and detects cycles
+ * indicating deadlocks.
+ */
+/**
+ * Detect deadlocks by finding cycles in the lock wait graph.
+ *
+ * Algorithm:
+ * 1. Build a map: lock address → holding thread
+ * 2. Build a map: thread → lock it's waiting on
+ * 3. For each waiting thread, follow the chain:
+ *    thread waits on lock → lock held by thread2 → thread2 waits on lock2 → ...
+ *    If we revisit a thread, we found a cycle (deadlock).
+ */
+export function detectDeadlocks(threads) {
+    // Map: lock address → thread that holds it
+    const lockHolders = new Map();
+    for (const t of threads) {
+        for (const lock of t.holdsLocks) {
+            lockHolders.set(lock, t);
+        }
+    }
+    // Only consider threads that are waiting on a lock AND hold at least one lock
+    // (a deadlock cycle requires each thread to hold one lock while waiting for another)
+    // Exclude threads waiting on a lock they already hold — this is Object.wait()
+    // (the thread temporarily releases the monitor while waiting on a condition)
+    const waitingThreads = threads.filter(t => t.waitingOn !== null &&
+        t.holdsLocks.length > 0 &&
+        !t.holdsLocks.includes(t.waitingOn));
+    const deadlocks = [];
+    const visited = new Set();
+    for (const startThread of waitingThreads) {
+        if (visited.has(startThread.name))
+            continue;
+        const chain = [];
+        const chainNames = new Set();
+        let current = startThread;
+        while (current && !chainNames.has(current.name)) {
+            chain.push(current);
+            chainNames.add(current.name);
+            // Find who holds the lock this thread is waiting on
+            const waitingOnLock = current.waitingOn;
+            if (!waitingOnLock)
+                break;
+            const holder = lockHolders.get(waitingOnLock);
+            if (!holder || !holder.waitingOn)
+                break;
+            current = holder;
+        }
+        // Check if we found a cycle
+        if (current && chainNames.has(current.name)) {
+            // Extract just the cycle portion
+            const cycleStartIdx = chain.findIndex(t => t.name === current.name);
+            const cycleThreads = chain.slice(cycleStartIdx);
+            // Skip if we've already found this deadlock
+            const cycleKey = cycleThreads.map(t => t.name).sort().join(",");
+            if (visited.has(cycleKey))
+                continue;
+            visited.add(cycleKey);
+            // Mark all threads in cycle as visited
+            for (const t of cycleThreads) {
+                visited.add(t.name);
+            }
+            const dlThreads = cycleThreads.map(t => ({
+                name: t.name,
+                holdsLock: t.holdsLocks[0] || "unknown",
+                waitingOn: t.waitingOn || "unknown",
+            }));
+            deadlocks.push({
+                threads: dlThreads,
+                recommendation: generateRecommendation(cycleThreads),
+            });
+        }
+    }
+    return deadlocks;
+}
+function generateRecommendation(threads) {
+    // Analyze the stack traces to give a meaningful recommendation
+    const stackMethods = threads.flatMap(t => t.stackTrace).join("\n");
+    if (stackMethods.includes("synchronized")) {
+        return "Use java.util.concurrent locks with tryLock() and timeout instead of synchronized blocks. Ensure consistent lock ordering across all threads.";
+    }
+    if (stackMethods.includes("ReentrantLock")) {
+        return "Use tryLock(timeout) instead of lock() to prevent indefinite blocking. Review lock ordering for consistency.";
+    }
+    return "Ensure consistent lock ordering across all threads. Consider using java.util.concurrent locks with tryLock(timeout) to prevent indefinite blocking.";
+}

package/build/analyzers/gc-pressure.js

@@ -0,0 +1,111 @@
+/**
+ * GC pressure analyzer.
+ *
+ * Detects excessive pauses, promotion failures, memory pressure patterns.
+ * Recommends JVM flags for tuning.
+ */
+export function analyzeGcPressure(log) {
+    const pauseEvents = log.events.filter(e => e.pauseMs > 0);
+    const pauses = pauseEvents.map(e => e.pauseMs).sort((a, b) => a - b);
+    const result = {
+        minPauseMs: 0,
+        maxPauseMs: 0,
+        avgPauseMs: 0,
+        p95PauseMs: 0,
+        totalPauseMs: 0,
+        gcOverheadPct: 0,
+        heapBeforeMb: 0,
+        heapAfterMb: 0,
+        issues: [],
+        recommendations: [],
+    };
+    if (pauses.length === 0)
+        return result;
+    // Pause statistics
+    result.minPauseMs = pauses[0];
+    result.maxPauseMs = pauses[pauses.length - 1];
+    result.totalPauseMs = pauses.reduce((a, b) => a + b, 0);
+    result.avgPauseMs = result.totalPauseMs / pauses.length;
+    result.p95PauseMs = pauses[Math.floor(pauses.length * 0.95)] || result.maxPauseMs;
+    // GC overhead
+    if (log.timeSpanMs > 0) {
+        result.gcOverheadPct = (result.totalPauseMs / log.timeSpanMs) * 100;
+    }
+    // Heap stats (average before/after)
+    const heapEvents = log.events.filter(e => e.heapBeforeMb > 0);
+    if (heapEvents.length > 0) {
+        result.heapBeforeMb =
+            heapEvents.reduce((s, e) => s + e.heapBeforeMb, 0) / heapEvents.length;
+        result.heapAfterMb =
+            heapEvents.reduce((s, e) => s + e.heapAfterMb, 0) / heapEvents.length;
+    }
+    // Issue detection
+    detectIssues(log, result);
+    // Recommendations
+    generateRecommendations(log, result);
+    return result;
+}
+function detectIssues(log, result) {
+    // High GC overhead
+    if (result.gcOverheadPct > 15) {
+        result.issues.push(`GC overhead is ${result.gcOverheadPct.toFixed(1)}% — above 15% threshold. Application is spending too much time in GC.`);
+    }
+    // Long pauses
+    if (result.maxPauseMs > 1000) {
+        result.issues.push(`Maximum GC pause of ${result.maxPauseMs.toFixed(0)}ms exceeds 1 second — causes visible latency spikes.`);
+    }
+    // Full GC events
+    const fullGcCount = log.events.filter(e => e.type.includes("Full") || e.type.includes("Major")).length;
+    if (fullGcCount > 0) {
+        result.issues.push(`${fullGcCount} Full GC event(s) detected — these cause the longest pauses. May indicate heap pressure or explicit System.gc() calls.`);
+    }
+    // Heap not shrinking (possible memory leak)
+    const heapEvents = log.events.filter(e => e.heapAfterMb > 0);
+    if (heapEvents.length >= 5) {
+        const firstHalf = heapEvents.slice(0, Math.floor(heapEvents.length / 2));
+        const secondHalf = heapEvents.slice(Math.floor(heapEvents.length / 2));
+        const avgFirst = firstHalf.reduce((s, e) => s + e.heapAfterMb, 0) / firstHalf.length;
+        const avgSecond = secondHalf.reduce((s, e) => s + e.heapAfterMb, 0) / secondHalf.length;
+        if (avgSecond > avgFirst * 1.3) {
+            result.issues.push(`Heap after GC is growing over time (${avgFirst.toFixed(0)}MB → ${avgSecond.toFixed(0)}MB) — possible memory leak.`);
+        }
+    }
+    // Low reclaim ratio
+    if (result.heapBeforeMb > 0 && result.heapAfterMb > 0) {
+        const reclaimPct = ((result.heapBeforeMb - result.heapAfterMb) / result.heapBeforeMb) * 100;
+        if (reclaimPct < 10) {
+            result.issues.push(`GC reclaims only ${reclaimPct.toFixed(0)}% of heap per collection — most objects survive. Heap may be too small or there's a memory leak.`);
+        }
+    }
+}
+function generateRecommendations(log, result) {
+    // High overhead → increase heap
+    if (result.gcOverheadPct > 15) {
+        result.recommendations.push("Increase heap size (-Xmx) to reduce GC frequency. Start with 2x current value.");
+    }
+    // Long pauses → switch to low-latency collector
+    if (result.maxPauseMs > 500) {
+        if (log.algorithm === "Parallel" || log.algorithm === "Serial") {
+            result.recommendations.push(`Switch from ${log.algorithm} GC to G1 (-XX:+UseG1GC) or ZGC (-XX:+UseZGC) for lower pause times.`);
+        }
+        else if (log.algorithm === "G1") {
+            result.recommendations.push("Consider tuning G1 target pause time: -XX:MaxGCPauseMillis=200. If pauses still too long, evaluate ZGC.");
+        }
+    }
+    // Full GCs → tune thresholds
+    const fullGcCount = log.events.filter(e => e.type.includes("Full")).length;
+    if (fullGcCount > 3) {
+        result.recommendations.push("Frequent Full GCs indicate heap pressure. Increase -Xmx or tune -XX:InitiatingHeapOccupancyPercent (G1) to start concurrent marking earlier.");
+    }
+    // Low reclaim → check for leaks
+    if (result.heapBeforeMb > 0) {
+        const reclaimPct = ((result.heapBeforeMb - result.heapAfterMb) / result.heapBeforeMb) * 100;
+        if (reclaimPct < 10) {
+            result.recommendations.push("Very low reclaim ratio suggests most objects are long-lived. Take a heap dump and analyze with Eclipse MAT or jmap -histo to identify memory leaks.");
+        }
+    }
+    // General best practices
+    if (result.recommendations.length === 0) {
+        result.recommendations.push("GC behavior looks healthy. For production, ensure -Xms equals -Xmx to avoid heap resizing pauses.");
+    }
+}

package/build/analyzers/heap-diff.js

@@ -0,0 +1,152 @@
+/**
+ * Heap histogram diff analyzer.
+ *
+ * Compares two jmap -histo outputs to detect memory growth patterns.
+ * Identifies:
+ * - Classes with growing instance/byte counts (leak candidates)
+ * - Classes that appeared in the second snapshot but not the first (new allocations)
+ * - Classes that disappeared (GC'd or unloaded)
+ * - Overall heap growth rate
+ */
+import { parseHeapHisto } from "../parsers/heap-histo.js";
+// Common JDK internal classes — growth in these is usually not a direct leak
+const JDK_INTERNALS = new Set([
+    "[B", "[C", "[I", "[J", "[S", "[Z", "[D", "[F",
+    "java.lang.String", "java.lang.Object[]", "java.lang.Class",
+    "java.util.HashMap$Node", "java.util.concurrent.ConcurrentHashMap$Node",
+    "java.lang.reflect.Method", "java.lang.ref.Finalizer",
+]);
+export function compareHeapHistos(before, after) {
+    const reportBefore = parseHeapHisto(before);
+    const reportAfter = parseHeapHisto(after);
+    // Build lookup maps
+    const beforeMap = new Map();
+    for (const e of reportBefore.entries) {
+        beforeMap.set(e.className, e);
+    }
+    const afterMap = new Map();
+    for (const e of reportAfter.entries) {
+        afterMap.set(e.className, e);
+    }
+    const growing = [];
+    const shrinking = [];
+    const newClasses = [];
+    const removedClasses = [];
+    // Compare entries present in both
+    for (const [className, afterEntry] of afterMap) {
+        const beforeEntry = beforeMap.get(className);
+        if (!beforeEntry) {
+            // New class in second snapshot
+            newClasses.push({
+                className,
+                instancesBefore: 0,
+                instancesAfter: afterEntry.instances,
+                instancesDelta: afterEntry.instances,
+                bytesBefore: 0,
+                bytesAfter: afterEntry.bytes,
+                bytesDelta: afterEntry.bytes,
+                growthPct: 100,
+            });
+            continue;
+        }
+        const bytesDelta = afterEntry.bytes - beforeEntry.bytes;
+        const instancesDelta = afterEntry.instances - beforeEntry.instances;
+        const growthPct = beforeEntry.bytes > 0 ? (bytesDelta / beforeEntry.bytes) * 100 : 0;
+        const entry = {
+            className,
+            instancesBefore: beforeEntry.instances,
+            instancesAfter: afterEntry.instances,
+            instancesDelta,
+            bytesBefore: beforeEntry.bytes,
+            bytesAfter: afterEntry.bytes,
+            bytesDelta,
+            growthPct,
+        };
+        if (bytesDelta > 0) {
+            growing.push(entry);
+        }
+        else if (bytesDelta < 0) {
+            shrinking.push(entry);
+        }
+    }
+    // Find removed classes (in before but not after)
+    for (const [className, beforeEntry] of beforeMap) {
+        if (!afterMap.has(className)) {
+            removedClasses.push({
+                className,
+                instancesBefore: beforeEntry.instances,
+                instancesAfter: 0,
+                instancesDelta: -beforeEntry.instances,
+                bytesBefore: beforeEntry.bytes,
+                bytesAfter: 0,
+                bytesDelta: -beforeEntry.bytes,
+                growthPct: -100,
+            });
+        }
+    }
+    // Sort by bytes delta (largest growth first)
+    growing.sort((a, b) => b.bytesDelta - a.bytesDelta);
+    shrinking.sort((a, b) => a.bytesDelta - b.bytesDelta);
+    newClasses.sort((a, b) => b.bytesAfter - a.bytesAfter);
+    const totalBytesBefore = reportBefore.totalBytes;
+    const totalBytesAfter = reportAfter.totalBytes;
+    const totalBytesDelta = totalBytesAfter - totalBytesBefore;
+    // Analyze for issues
+    const issues = [];
+    const recommendations = [];
+    // Check for significant heap growth
+    if (totalBytesBefore > 0) {
+        const overallGrowth = (totalBytesDelta / totalBytesBefore) * 100;
+        if (overallGrowth > 50) {
+            issues.push(`Heap grew ${overallGrowth.toFixed(0)}% between snapshots — significant memory growth detected`);
+        }
+    }
+    // Check for non-JDK classes with significant growth
+    const suspiciousGrowing = growing.filter(e => !JDK_INTERNALS.has(e.className) && e.bytesDelta > 1_000_000);
+    for (const entry of suspiciousGrowing.slice(0, 5)) {
+        issues.push(`${entry.className}: +${formatBytes(entry.bytesDelta)} (+${entry.instancesDelta} instances, ${entry.growthPct.toFixed(0)}% growth) — potential memory leak`);
+        recommendations.push(`Investigate ${entry.className} retention — capture heap dump and trace GC roots with Eclipse MAT`);
+    }
+    // Check for classloader leaks
+    const classEntry = growing.find(e => e.className === "java.lang.Class");
+    if (classEntry && classEntry.instancesDelta > 1000) {
+        issues.push(`java.lang.Class grew by ${classEntry.instancesDelta} instances — possible classloader leak (hot redeploy, dynamic proxies)`);
+        recommendations.push("Check for classloader leaks if using hot deployment. Consider full restart instead of redeploy.");
+    }
+    // Check for finalizer queue growth
+    const finalizerEntry = growing.find(e => e.className === "java.lang.ref.Finalizer");
+    if (finalizerEntry && finalizerEntry.instancesDelta > 5000) {
+        issues.push(`Finalizer queue grew by ${finalizerEntry.instancesDelta} — finalization is backing up`);
+        recommendations.push("Replace finalize() with Cleaner or try-with-resources.");
+    }
+    if (issues.length === 0 && totalBytesDelta <= 0) {
+        recommendations.push("Heap is stable or shrinking — no memory leak indicators detected.");
+    }
+    if (issues.length === 0 && totalBytesDelta > 0 && suspiciousGrowing.length === 0) {
+        recommendations.push("Growth appears to be in JDK internal classes — likely normal String/array allocation. Monitor for sustained growth across multiple snapshots.");
+    }
+    return {
+        growing,
+        shrinking,
+        newClasses,
+        removedClasses,
+        totalBytesBefore,
+        totalBytesAfter,
+        totalBytesDelta,
+        totalInstancesBefore: reportBefore.totalInstances,
+        totalInstancesAfter: reportAfter.totalInstances,
+        issues,
+        recommendations,
+    };
+}
+function formatBytes(bytes) {
+    const abs = Math.abs(bytes);
+    const sign = bytes < 0 ? "-" : "";
+    if (abs >= 1_073_741_824)
+        return `${sign}${(abs / 1_073_741_824).toFixed(1)} GB`;
+    if (abs >= 1_048_576)
+        return `${sign}${(abs / 1_048_576).toFixed(1)} MB`;
+    if (abs >= 1024)
+        return `${sign}${(abs / 1024).toFixed(0)} KB`;
+    return `${sign}${abs} B`;
+}