mcp-jvm-diagnostics 0.1.5 → 0.1.6

package/README.md

@@ -22,6 +22,19 @@ It analyzes **offline** artifacts (thread dumps, GC logs, heap histograms) rathe
 - **Supports** G1, ZGC, Parallel, Serial, and Shenandoah GC formats
 - **No external dependencies** — works on local text input, no API keys needed
 
+## Pro Tier
+
+**Generate exportable diagnostic reports (HTML + PDF)** with a Pro license key.
+
+- Full JVM thread dump analysis report with actionable recommendations
+- PDF export for sharing with your team
+- Priority support
+
+<!-- TODO: replace placeholder Stripe Payment Link once STRIPE_SECRET_KEY is configured -->
+**$9.99/month** — [Get Pro License](https://buy.stripe.com/PLACEHOLDER)
+
+Pro license key activates the `generate_report` MCP tool in mcp-jvm-diagnostics.
+
 ## Installation
 
 ```bash

package/build/analyzers/deadlock.js

@@ -63,11 +63,20 @@ export function detectDeadlocks(threads) {
             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",
-            }));
+            const dlThreads = cycleThreads.map((t, i) => {
+                // Use the lock this thread holds that the next thread in the cycle is waiting on.
+                // This ensures we report the lock that actually forms the deadlock cycle, not
+                // an arbitrary first lock (threads may hold multiple locks).
+                const nextThread = cycleThreads[(i + 1) % cycleThreads.length];
+                const cycleLock = t.holdsLocks.find(lock => lock === nextThread.waitingOn) ??
+                    t.holdsLocks[0] ??
+                    "unknown";
+                return {
+                    name: t.name,
+                    holdsLock: cycleLock,
+                    waitingOn: t.waitingOn || "unknown",
+                };
+            });
             deadlocks.push({
                 threads: dlThreads,
                 recommendation: generateRecommendation(cycleThreads),

package/build/index.js

@@ -10,9 +10,10 @@ import { analyzeGcPressure } from "./analyzers/gc-pressure.js";
 import { parseHeapHisto } from "./parsers/heap-histo.js";
 import { compareHeapHistos } from "./analyzers/heap-diff.js";
 import { parseJfrSummary } from "./parsers/jfr-summary.js";
+import { generateReportFromThreadDump, analyzeThreadDumpMarkdown, } from "./reporting.js";
 // Handle --help
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
-    console.log(`mcp-jvm-diagnostics v0.1.5 — MCP server for JVM diagnostics
+    console.log(`mcp-jvm-diagnostics v0.1.6 — MCP server for JVM diagnostics
 
 Usage:
   mcp-jvm-diagnostics [options]
@@ -26,12 +27,13 @@ Tools provided:
   analyze_heap_histo    Parse jmap -histo output, detect memory leak candidates
   compare_heap_histos   Compare two jmap histos to detect memory growth
   analyze_jfr           Parse JFR summary output, detect performance hotspots
-  diagnose_jvm          Unified diagnosis from thread dump + GC log`);
+  diagnose_jvm          Unified diagnosis from thread dump + GC log
+  generate_report       Generate an exportable HTML + PDF diagnostic report (Pro)`);
     process.exit(0);
 }
 const server = new McpServer({
     name: "mcp-jvm-diagnostics",
-    version: "0.1.4",
+    version: "0.1.6",
 });
 // --- Tool: analyze_thread_dump ---
 server.tool("analyze_thread_dump", "Parse a JVM thread dump (jstack output) and analyze thread states, detect deadlocks, identify lock contention hotspots, and find thread starvation patterns. Handles both platform threads and virtual threads (Java 21+).", {
@@ -40,83 +42,57 @@ server.tool("analyze_thread_dump", "Parse a JVM thread dump (jstack output) and
         .describe("The full thread dump text (from jstack, kill -3, or VisualVM)"),
 }, async ({ thread_dump }) => {
     try {
-        const parsed = parseThreadDump(thread_dump);
-        const deadlocks = detectDeadlocks(parsed.threads);
-        const contention = analyzeContention(parsed.threads);
-        const sections = [];
-        // Summary
-        sections.push(`## Thread Dump Analysis`);
-        sections.push(`\n- **JVM**: ${parsed.jvmInfo || "Unknown"}`);
-        sections.push(`- **Timestamp**: ${parsed.timestamp || "Unknown"}`);
-        sections.push(`- **Total threads**: ${parsed.threads.length}`);
-        // Thread state breakdown
-        const stateCounts = new Map();
-        for (const t of parsed.threads) {
-            stateCounts.set(t.state, (stateCounts.get(t.state) || 0) + 1);
-        }
-        // Ensure all canonical Java thread states appear
-        const canonicalStates = ["RUNNABLE", "WAITING", "TIMED_WAITING", "BLOCKED", "NEW", "TERMINATED"];
-        for (const s of canonicalStates) {
-            if (!stateCounts.has(s))
-                stateCounts.set(s, 0);
-        }
-        const total = parsed.threads.length;
-        const maxCount = Math.max(...stateCounts.values(), 1);
-        const barMaxWidth = 20;
-        sections.push(`\n### Thread State Summary`);
-        sections.push(`| State | Count | % | Histogram |`);
-        sections.push(`|-------|------:|--:|-----------|`);
-        // Sort: non-zero descending by count, then zero-count states in canonical order
-        const sorted = [...stateCounts.entries()].sort((a, b) => {
-            if (a[1] !== b[1])
-                return b[1] - a[1];
-            return canonicalStates.indexOf(a[0]) - canonicalStates.indexOf(b[0]);
+        return {
+            content: [{ type: "text", text: analyzeThreadDumpMarkdown(thread_dump) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error analyzing thread dump: ${err instanceof Error ? err.message : String(err)}` }],
+        };
+    }
+});
+// --- Tool: generate_report ---
+server.tool("generate_report", "Generate an exportable diagnostic report (HTML + PDF) from JVM diagnostic data. Requires a valid Pro license key.", {
+    license_key: z
+        .string()
+        .describe("A valid MCP JVM Diagnostics Pro license key"),
+    thread_dump: z
+        .string()
+        .describe("The full thread dump text to analyze and export"),
+}, async ({ license_key, thread_dump }) => {
+    try {
+        const result = await generateReportFromThreadDump({
+            licenseKey: license_key,
+            threadDump: thread_dump,
         });
-        for (const [state, count] of sorted) {
-            const pct = total > 0 ? ((count / total) * 100).toFixed(1) : "0.0";
-            const barLen = Math.round((count / maxCount) * barMaxWidth);
-            const bar = "\u2588".repeat(barLen);
-            sections.push(`| ${state} | ${count} | ${pct} | \`${bar}\` |`);
-        }
-        // Deadlocks
-        if (deadlocks.length > 0) {
-            sections.push(`\n### Deadlocks Detected (${deadlocks.length})`);
-            for (const dl of deadlocks) {
-                sections.push(`\n**Deadlock cycle** (${dl.threads.length} threads):`);
-                for (const t of dl.threads) {
-                    sections.push(`- **${t.name}** holds \`${t.holdsLock}\`, waiting for \`${t.waitingOn}\``);
-                }
-                sections.push(`\n**Resolution**: ${dl.recommendation}`);
-            }
-        }
-        else {
-            sections.push(`\n### Deadlocks: None detected`);
-        }
-        // Contention
-        if (contention.hotspots.length > 0) {
-            sections.push(`\n### Lock Contention Hotspots`);
-            sections.push(`| Lock | Blocked Threads | Holder |`);
-            sections.push(`|------|----------------|--------|`);
-            for (const h of contention.hotspots) {
-                sections.push(`| \`${h.lock}\` | ${h.blockedCount} | ${h.holderThread} |`);
-            }
-            if (contention.recommendations.length > 0) {
-                sections.push(`\n### Recommendations`);
-                for (const rec of contention.recommendations) {
-                    sections.push(`- ${rec}`);
-                }
-            }
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: result.error }],
+            };
         }
-        // Daemon vs non-daemon
-        const daemonCount = parsed.threads.filter(t => t.isDaemon).length;
-        sections.push(`\n### Thread Classification`);
-        sections.push(`- Daemon threads: ${daemonCount}`);
-        sections.push(`- Non-daemon threads: ${parsed.threads.length - daemonCount}`);
-        return { content: [{ type: "text", text: sections.join("\n") }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "Exportable diagnostic report generated successfully.",
+                        `HTML: ${result.htmlPath}`,
+                        `PDF: ${result.pdfPath}`,
+                        `Customer ID: ${result.customerId ?? "Unknown"}`,
+                    ].join("\n"),
+                },
+            ],
+        };
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error analyzing thread dump: ${err instanceof Error ? err.message : String(err)}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error generating report: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
         };
     }
 });
@@ -136,6 +112,9 @@ server.tool("analyze_gc_log", "Parse a JVM GC log and analyze garbage collection
         sections.push(`- **Time span**: ${parsed.timeSpanMs > 0 ? (parsed.timeSpanMs / 1000).toFixed(1) + "s" : "N/A"}`);
         // Pause time stats
         if (parsed.events.length > 0) {
+            const gcOverheadStr = parsed.hasTimestamps
+                ? `${pressure.gcOverheadPct.toFixed(1)}%`
+                : "N/A (legacy format has no timestamps)";
             sections.push(`\n### Pause Time Statistics`);
             sections.push(`| Metric | Value |`);
             sections.push(`|--------|-------|`);
@@ -144,7 +123,7 @@ server.tool("analyze_gc_log", "Parse a JVM GC log and analyze garbage collection
             sections.push(`| Avg pause | ${pressure.avgPauseMs.toFixed(1)} ms |`);
             sections.push(`| P95 pause | ${pressure.p95PauseMs.toFixed(1)} ms |`);
             sections.push(`| Total pause time | ${pressure.totalPauseMs.toFixed(0)} ms |`);
-            sections.push(`| GC overhead | ${pressure.gcOverheadPct.toFixed(1)}% |`);
+            sections.push(`| GC overhead | ${gcOverheadStr} |`);
         }
         // Heap sizing
         if (pressure.heapBeforeMb > 0) {
@@ -408,7 +387,10 @@ server.tool("diagnose_jvm", "Unified JVM diagnosis combining thread dump and GC
             sections.push(`- Algorithm: ${parsed.algorithm}`);
             sections.push(`- Events: ${parsed.events.length}`);
             sections.push(`- Max pause: ${pressure.maxPauseMs.toFixed(1)} ms`);
-            sections.push(`- GC overhead: ${pressure.gcOverheadPct.toFixed(1)}%`);
+            const overheadLabel = parsed.hasTimestamps
+                ? `${pressure.gcOverheadPct.toFixed(1)}%`
+                : "N/A (no timestamps in legacy format)";
+            sections.push(`- GC overhead: ${overheadLabel}`);
             sections.push(`- Issues: ${pressure.issues.length}`);
         }
         // Cross-correlation

package/build/parsers/gc-log.js

@@ -126,10 +126,12 @@ export function parseGcLog(text) {
     }
     // Calculate time span
     let timeSpanMs = 0;
-    if (events.length > 1) {
+    // Legacy -verbose:gc events have timestamp=0; unified logging events have real timestamps.
+    const hasTimestamps = events.length > 0 && events.some(e => e.timestamp > 0);
+    if (hasTimestamps && events.length > 1) {
         const firstTs = events[0].timestamp;
         const lastTs = events[events.length - 1].timestamp;
         timeSpanMs = (lastTs - firstTs) * 1000;
     }
-    return { algorithm, events, timeSpanMs };
+    return { algorithm, events, timeSpanMs, hasTimestamps };
 }

package/build/reporting.js

@@ -0,0 +1,155 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { generateDiagnosticPdf, maskLicenseKey, renderDiagnosticReport, validateLicense, } from "@mcp-java-suite/license";
+import { analyzeContention } from "./analyzers/contention.js";
+import { detectDeadlocks } from "./analyzers/deadlock.js";
+import { parseThreadDump } from "./parsers/thread-dump.js";
+const PRODUCT_NAME = "jvm-diagnostics";
+const TOOL_VERSION = "0.1.6";
+export const MISSING_LICENSE_INPUT_ERROR = "Missing required input: license_key";
+export const MISSING_THREAD_DUMP_ERROR = "Missing required input: thread_dump";
+export const MISSING_ENV_LICENSE_ERROR = "MCP_LICENSE_KEY environment variable is not set. generate_report requires a valid Pro license key. Free-tier analysis tools remain available without it.";
+function isGenerateReportFailure(result) {
+    return "ok" in result && result.ok === false;
+}
+export function analyzeThreadDumpMarkdown(threadDump) {
+    const parsed = parseThreadDump(threadDump);
+    const deadlocks = detectDeadlocks(parsed.threads);
+    const contention = analyzeContention(parsed.threads);
+    const sections = [];
+    sections.push("## Thread Dump Analysis");
+    sections.push(`\n- **JVM**: ${parsed.jvmInfo || "Unknown"}`);
+    sections.push(`- **Timestamp**: ${parsed.timestamp || "Unknown"}`);
+    sections.push(`- **Total threads**: ${parsed.threads.length}`);
+    const stateCounts = new Map();
+    for (const thread of parsed.threads) {
+        stateCounts.set(thread.state, (stateCounts.get(thread.state) || 0) + 1);
+    }
+    const canonicalStates = [
+        "RUNNABLE",
+        "WAITING",
+        "TIMED_WAITING",
+        "BLOCKED",
+        "NEW",
+        "TERMINATED",
+    ];
+    for (const state of canonicalStates) {
+        if (!stateCounts.has(state)) {
+            stateCounts.set(state, 0);
+        }
+    }
+    const total = parsed.threads.length;
+    const maxCount = Math.max(...stateCounts.values(), 1);
+    const barMaxWidth = 20;
+    sections.push("\n### Thread State Summary");
+    sections.push("| State | Count | % | Histogram |");
+    sections.push("|-------|------:|--:|-----------|");
+    const sortedStates = [...stateCounts.entries()].sort((a, b) => {
+        if (a[1] !== b[1]) {
+            return b[1] - a[1];
+        }
+        return canonicalStates.indexOf(a[0]) - canonicalStates.indexOf(b[0]);
+    });
+    for (const [state, count] of sortedStates) {
+        const percentage = total > 0 ? ((count / total) * 100).toFixed(1) : "0.0";
+        const barLength = Math.round((count / maxCount) * barMaxWidth);
+        const bar = "\u2588".repeat(barLength);
+        sections.push(`| ${state} | ${count} | ${percentage} | \`${bar}\` |`);
+    }
+    if (deadlocks.length > 0) {
+        sections.push(`\n### Deadlocks Detected (${deadlocks.length})`);
+        for (const deadlock of deadlocks) {
+            sections.push(`\n**Deadlock cycle** (${deadlock.threads.length} threads):`);
+            for (const thread of deadlock.threads) {
+                sections.push(`- **${thread.name}** holds \`${thread.holdsLock}\`, waiting for \`${thread.waitingOn}\``);
+            }
+            sections.push(`\n**Resolution**: ${deadlock.recommendation}`);
+        }
+    }
+    else {
+        sections.push("\n### Deadlocks: None detected");
+    }
+    if (contention.hotspots.length > 0) {
+        sections.push("\n### Lock Contention Hotspots");
+        sections.push("| Lock | Blocked Threads | Holder |");
+        sections.push("|------|----------------|--------|");
+        for (const hotspot of contention.hotspots) {
+            sections.push(`| \`${hotspot.lock}\` | ${hotspot.blockedCount} | ${hotspot.holderThread} |`);
+        }
+        if (contention.recommendations.length > 0) {
+            sections.push("\n### Recommendations");
+            for (const recommendation of contention.recommendations) {
+                sections.push(`- ${recommendation}`);
+            }
+        }
+    }
+    const daemonCount = parsed.threads.filter((thread) => thread.isDaemon).length;
+    sections.push("\n### Thread Classification");
+    sections.push(`- Daemon threads: ${daemonCount}`);
+    sections.push(`- Non-daemon threads: ${parsed.threads.length - daemonCount}`);
+    return sections.join("\n");
+}
+function validateConfiguredLicense() {
+    const configuredKey = process.env.MCP_LICENSE_KEY;
+    if (!configuredKey || configuredKey.trim().length === 0) {
+        return { ok: false, error: MISSING_ENV_LICENSE_ERROR };
+    }
+    return validateProLicense(configuredKey, "Configured MCP_LICENSE_KEY");
+}
+function validateProLicense(key, label) {
+    try {
+        const license = validateLicense(key, PRODUCT_NAME);
+        if (!license.isPro) {
+            return {
+                ok: false,
+                error: `${label} is invalid: ${license.reason}`,
+            };
+        }
+        return license;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `License validation unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function generateReportFromThreadDump(params) {
+    if (!params.licenseKey || params.licenseKey.trim().length === 0) {
+        return { ok: false, error: MISSING_LICENSE_INPUT_ERROR };
+    }
+    if (!params.threadDump || params.threadDump.trim().length === 0) {
+        return { ok: false, error: MISSING_THREAD_DUMP_ERROR };
+    }
+    const configuredLicense = validateConfiguredLicense();
+    if (isGenerateReportFailure(configuredLicense)) {
+        return configuredLicense;
+    }
+    const providedLicense = validateProLicense(params.licenseKey, "Provided license_key");
+    if (isGenerateReportFailure(providedLicense)) {
+        return providedLicense;
+    }
+    const reportMarkdown = analyzeThreadDumpMarkdown(params.threadDump);
+    const reportParams = {
+        customerName: `Pro Customer #${providedLicense.customerId ?? "Unknown"}`,
+        licenseKeyMasked: maskLicenseKey(params.licenseKey),
+        reportDate: new Date().toISOString().slice(0, 10),
+        toolVersion: TOOL_VERSION,
+        reportMarkdown,
+    };
+    const outputDir = params.outputDir ??
+        (await mkdtemp(path.join(tmpdir(), "mcp-jvm-diagnostics-report-")));
+    const htmlPath = path.join(outputDir, "diagnostic-report.html");
+    const pdfPath = path.join(outputDir, "diagnostic-report.pdf");
+    const html = renderDiagnosticReport(reportParams);
+    await writeFile(htmlPath, html, "utf8");
+    const pdf = await generateDiagnosticPdf(reportParams);
+    await writeFile(pdfPath, pdf);
+    return {
+        ok: true,
+        htmlPath,
+        pdfPath,
+        customerId: providedLicense.customerId,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-jvm-diagnostics",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "MCP server for JVM diagnostics — analyze thread dumps, detect deadlocks, parse GC logs, and get JVM tuning recommendations",
   "mcpName": "io.github.dmitriusan/mcp-jvm-diagnostics",
   "author": "Dmytro Lisnichenko",
@@ -53,6 +53,7 @@
     "url": "https://github.com/Dmitriusan/mcp-jvm-diagnostics/issues"
   },
   "dependencies": {
+    "@mcp-java-suite/license": "file:../../mcp-suite-license/mcp-suite-license",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^3.24.2"
   },