@yawlabs/mcp-compliance 0.9.2 → 0.10.1

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { watch as fsWatch, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
 import { createRequire as createRequire2 } from "module";
 import { createInterface } from "readline/promises";
 import chalk2 from "chalk";
@@ -56,147 +56,8 @@ function renderBadgeSvg(input) {
 </svg>`;
 }
 
-// src/config.ts
-import { existsSync, readFileSync } from "fs";
-import { join, resolve } from "path";
-var SEARCH_NAMES = ["mcp-compliance.config.json", ".mcp-compliancerc.json", ".mcp-compliancerc"];
-function loadConfig(explicitPath, cwd = process.cwd()) {
-  if (explicitPath) {
-    const abs = resolve(cwd, explicitPath);
-    if (!existsSync(abs)) throw new Error(`Config file not found: ${explicitPath}`);
-    return parseConfig(readFileSync(abs, "utf8"), abs);
-  }
-  for (const name of SEARCH_NAMES) {
-    const abs = join(cwd, name);
-    if (existsSync(abs)) return parseConfig(readFileSync(abs, "utf8"), abs);
-  }
-  const pkgPath = join(cwd, "package.json");
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-      if (pkg["mcp-compliance"]) return validate(pkg["mcp-compliance"], pkgPath);
-    } catch {
-    }
-  }
-  return null;
-}
-function parseConfig(contents, source) {
-  let raw;
-  try {
-    raw = JSON.parse(contents);
-  } catch (err) {
-    throw new Error(`Failed to parse config at ${source}: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  return validate(raw, source);
-}
-function validate(raw, source) {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(`Config at ${source} must be a JSON object`);
-  }
-  const obj = raw;
-  const allowed = /* @__PURE__ */ new Set([
-    "target",
-    "timeout",
-    "preflightTimeout",
-    "retries",
-    "only",
-    "skip",
-    "strict",
-    "format",
-    "verbose"
-  ]);
-  for (const k of Object.keys(obj)) {
-    if (!allowed.has(k)) {
-      throw new Error(`Config at ${source}: unknown key "${k}"`);
-    }
-  }
-  if (obj.target !== void 0) validateTarget(obj.target, source);
-  if (obj.format !== void 0 && !["terminal", "json", "sarif"].includes(obj.format)) {
-    throw new Error(`Config at ${source}: format must be one of terminal, json, sarif`);
-  }
-  return obj;
-}
-function validateTarget(t, source) {
-  if (!t || typeof t !== "object" || Array.isArray(t)) {
-    throw new Error(`Config at ${source}: target must be an object`);
-  }
-  const obj = t;
-  if (obj.type !== "http" && obj.type !== "stdio") {
-    throw new Error(`Config at ${source}: target.type must be "http" or "stdio"`);
-  }
-  if (obj.type === "http" && typeof obj.url !== "string") {
-    throw new Error(`Config at ${source}: http target requires string "url"`);
-  }
-  if (obj.type === "stdio" && typeof obj.command !== "string") {
-    throw new Error(`Config at ${source}: stdio target requires string "command"`);
-  }
-}
-
-// src/mcp/server.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { dirname, join as join2, resolve as resolve2 } from "path";
-import { fileURLToPath } from "url";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-// src/mcp/tools.ts
-import { z } from "zod";
-
-// src/runner.ts
-import { createRequire } from "module";
-import { request as request2 } from "undici";
-
-// src/badge.ts
-import { createHash } from "crypto";
-function urlHash(url) {
-  return createHash("sha256").update(url).digest("hex").slice(0, 12);
-}
-function generateBadge(url) {
-  const hash = urlHash(url);
-  const imageUrl = `https://mcp.hosting/api/compliance/ext/${hash}/badge`;
-  const reportUrl = `https://mcp.hosting/compliance/ext/${hash}`;
-  return {
-    imageUrl,
-    reportUrl,
-    markdown: `[![MCP Compliant](${imageUrl})](${reportUrl})`,
-    html: `<a href="${reportUrl}"><img src="${imageUrl}" alt="MCP Compliant"></a>`
-  };
-}
-
-// src/grader.ts
-function computeGrade(score) {
-  if (score >= 90) return "A";
-  if (score >= 75) return "B";
-  if (score >= 60) return "C";
-  if (score >= 40) return "D";
-  return "F";
-}
-function computeScore(tests) {
-  const total = tests.length;
-  const passed = tests.filter((t) => t.passed).length;
-  const failed = total - passed;
-  const requiredTests = tests.filter((t) => t.required);
-  const requiredPassed = requiredTests.filter((t) => t.passed).length;
-  const requiredScore = requiredTests.length > 0 ? requiredPassed / requiredTests.length * 70 : 70;
-  const optionalTests = tests.filter((t) => !t.required);
-  const optionalPassed = optionalTests.filter((t) => t.passed).length;
-  const optionalScore = optionalTests.length > 0 ? optionalPassed / optionalTests.length * 30 : 30;
-  const score = Math.round(requiredScore + optionalScore);
-  const overall = requiredPassed === requiredTests.length ? passed === total ? "pass" : "partial" : "fail";
-  const categories = {};
-  for (const t of tests) {
-    if (!categories[t.category]) categories[t.category] = { passed: 0, total: 0 };
-    categories[t.category].total++;
-    if (t.passed) categories[t.category].passed++;
-  }
-  return {
-    score,
-    grade: computeGrade(score),
-    overall,
-    summary: { total, passed, failed, required: requiredTests.length, requiredPassed },
-    categories
-  };
-}
+// src/benchmark.ts
+import { performance } from "perf_hooks";
 
 // src/transport/http.ts
 import { request } from "undici";
@@ -353,9 +214,21 @@ function createStdioTransport(opts) {
   let exited = false;
   let exitCode = null;
   let spawnError = null;
+  let spawned = false;
   const pending = /* @__PURE__ */ new Map();
   let stdoutBuffer = "";
   let stderrBuffer = "";
+  const spawnReady = new Promise((resolve3, reject) => {
+    child.once("spawn", () => {
+      spawned = true;
+      resolve3();
+    });
+    child.once("error", (err) => {
+      if (!spawned) reject(err);
+    });
+  });
+  spawnReady.catch(() => {
+  });
   child.on("error", (err) => {
     spawnError = err;
     rejectAllPending(err);
@@ -425,6 +298,15 @@ function createStdioTransport(opts) {
     ${snippet.replace(/\n/g, "\n    ")}`;
   }
   async function writeLine(line) {
+    if (!spawned && !spawnError) {
+      try {
+        await spawnReady;
+      } catch (err) {
+        throw new Error(
+          annotateWithStderr(`stdio transport: spawn failed \u2014 ${err instanceof Error ? err.message : String(err)}`)
+        );
+      }
+    }
     if (exited) {
       throw new Error(annotateWithStderr(`stdio transport: child has exited (code ${exitCode})`));
     }
@@ -518,7 +400,349 @@ function createStdioTransport(opts) {
   return transport;
 }
 
+// src/benchmark.ts
+function pct(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p / 100 * sorted.length) - 1));
+  return sorted[idx];
+}
+async function runBenchmark(target, opts = {}) {
+  const requests = opts.requests ?? 100;
+  const concurrency = Math.max(1, opts.concurrency ?? 1);
+  const timeout = opts.timeout ?? 15e3;
+  const transport = target.type === "http" ? createHttpTransport({ url: target.url, headers: target.headers }) : createStdioTransport({
+    command: target.command,
+    args: target.args,
+    env: target.env,
+    cwd: target.cwd
+  });
+  let nextId = 1;
+  try {
+    await transport.request(
+      "initialize",
+      { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mcp-compliance-bench", version: "1" } },
+      () => nextId++,
+      { timeout }
+    );
+    await transport.notify("notifications/initialized", void 0, { timeout });
+  } catch {
+  }
+  const latencies = [];
+  let succeeded = 0;
+  let failed = 0;
+  const overallStart = performance.now();
+  let inFlight = 0;
+  let issued = 0;
+  let resolveAll;
+  const allDone = new Promise((r) => {
+    resolveAll = r;
+  });
+  function tick() {
+    while (inFlight < concurrency && issued < requests) {
+      issued++;
+      inFlight++;
+      const t0 = performance.now();
+      transport.request("ping", void 0, () => nextId++, { timeout }).then(() => {
+        latencies.push(performance.now() - t0);
+        succeeded++;
+      }).catch(() => {
+        latencies.push(performance.now() - t0);
+        failed++;
+      }).finally(() => {
+        inFlight--;
+        opts.onProgress?.(succeeded + failed, requests);
+        if (succeeded + failed >= requests) resolveAll();
+        else tick();
+      });
+    }
+  }
+  tick();
+  await allDone;
+  const durationMs = performance.now() - overallStart;
+  await transport.close().catch(() => {
+  });
+  const sorted = [...latencies].sort((a, b) => a - b);
+  const mean = sorted.reduce((s, v) => s + v, 0) / Math.max(1, sorted.length);
+  const targetDescription = target.type === "http" ? target.url : `stdio:${target.command} ${target.args?.join(" ") ?? ""}`;
+  return {
+    target: targetDescription,
+    requests,
+    succeeded,
+    failed,
+    durationMs,
+    throughputPerSec: durationMs > 0 ? requests / durationMs * 1e3 : 0,
+    latencyMs: {
+      min: sorted[0] ?? 0,
+      p50: pct(sorted, 50),
+      p90: pct(sorted, 90),
+      p95: pct(sorted, 95),
+      p99: pct(sorted, 99),
+      max: sorted[sorted.length - 1] ?? 0,
+      mean
+    }
+  };
+}
+function formatBenchmark(result) {
+  const lines = [];
+  lines.push(`Benchmark: ${result.target}`);
+  lines.push(
+    `  ${result.requests} requests in ${result.durationMs.toFixed(0)}ms (${result.throughputPerSec.toFixed(1)} req/s)`
+  );
+  lines.push(`  ${result.succeeded} succeeded \xB7 ${result.failed} failed`);
+  lines.push("");
+  lines.push("Latency (ms):");
+  lines.push(`  min   ${result.latencyMs.min.toFixed(2)}`);
+  lines.push(`  mean  ${result.latencyMs.mean.toFixed(2)}`);
+  lines.push(`  p50   ${result.latencyMs.p50.toFixed(2)}`);
+  lines.push(`  p90   ${result.latencyMs.p90.toFixed(2)}`);
+  lines.push(`  p95   ${result.latencyMs.p95.toFixed(2)}`);
+  lines.push(`  p99   ${result.latencyMs.p99.toFixed(2)}`);
+  lines.push(`  max   ${result.latencyMs.max.toFixed(2)}`);
+  return lines.join("\n");
+}
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+var SEARCH_NAMES = ["mcp-compliance.config.json", ".mcp-compliancerc.json", ".mcp-compliancerc"];
+function loadConfig(explicitPath, cwd = process.cwd()) {
+  if (explicitPath) {
+    const abs = resolve(cwd, explicitPath);
+    if (!existsSync(abs)) throw new Error(`Config file not found: ${explicitPath}`);
+    return parseConfig(readFileSync(abs, "utf8"), abs);
+  }
+  for (const name of SEARCH_NAMES) {
+    const abs = join(cwd, name);
+    if (existsSync(abs)) return parseConfig(readFileSync(abs, "utf8"), abs);
+  }
+  const pkgPath = join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      if (pkg["mcp-compliance"]) return validate(pkg["mcp-compliance"], pkgPath);
+    } catch {
+    }
+  }
+  return null;
+}
+function parseConfig(contents, source) {
+  let raw;
+  try {
+    raw = JSON.parse(contents);
+  } catch (err) {
+    throw new Error(`Failed to parse config at ${source}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return validate(raw, source);
+}
+function validate(raw, source) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Config at ${source} must be a JSON object`);
+  }
+  const obj = raw;
+  const allowed = /* @__PURE__ */ new Set([
+    "target",
+    "timeout",
+    "preflightTimeout",
+    "retries",
+    "only",
+    "skip",
+    "strict",
+    "format",
+    "verbose"
+  ]);
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) {
+      throw new Error(`Config at ${source}: unknown key "${k}"`);
+    }
+  }
+  if (obj.target !== void 0) validateTarget(obj.target, source);
+  if (obj.format !== void 0 && !["terminal", "json", "sarif"].includes(obj.format)) {
+    throw new Error(`Config at ${source}: format must be one of terminal, json, sarif`);
+  }
+  return obj;
+}
+function validateTarget(t, source) {
+  if (!t || typeof t !== "object" || Array.isArray(t)) {
+    throw new Error(`Config at ${source}: target must be an object`);
+  }
+  const obj = t;
+  if (obj.type !== "http" && obj.type !== "stdio") {
+    throw new Error(`Config at ${source}: target.type must be "http" or "stdio"`);
+  }
+  if (obj.type === "http" && typeof obj.url !== "string") {
+    throw new Error(`Config at ${source}: http target requires string "url"`);
+  }
+  if (obj.type === "stdio" && typeof obj.command !== "string") {
+    throw new Error(`Config at ${source}: stdio target requires string "command"`);
+  }
+}
+
+// src/diff.ts
+function diffReports(baseline, current) {
+  const baseById = new Map(baseline.tests.map((t) => [t.id, t]));
+  const curById = new Map(current.tests.map((t) => [t.id, t]));
+  const regressions = [];
+  const fixes = [];
+  const newFailures = [];
+  const newPasses = [];
+  const removed = [];
+  for (const [id, cur] of curById) {
+    const base = baseById.get(id);
+    if (!base) {
+      const entry = {
+        id,
+        name: cur.name,
+        category: cur.category,
+        required: cur.required,
+        kind: cur.passed ? "newPass" : "newFail",
+        currentDetails: cur.details
+      };
+      (cur.passed ? newPasses : newFailures).push(entry);
+      continue;
+    }
+    if (base.passed !== cur.passed) {
+      const entry = {
+        id,
+        name: cur.name,
+        category: cur.category,
+        required: cur.required,
+        kind: cur.passed ? "fix" : "regression",
+        baselineDetails: base.details,
+        currentDetails: cur.details
+      };
+      (cur.passed ? fixes : regressions).push(entry);
+    }
+  }
+  for (const [id, base] of baseById) {
+    if (!curById.has(id)) {
+      removed.push({
+        id,
+        name: base.name,
+        category: base.category,
+        required: base.required,
+        kind: "removed",
+        baselineDetails: base.details
+      });
+    }
+  }
+  return {
+    baselineGrade: baseline.grade,
+    currentGrade: current.grade,
+    baselineScore: baseline.score,
+    currentScore: current.score,
+    regressions,
+    fixes,
+    newFailures,
+    newPasses,
+    removed
+  };
+}
+function formatDiff(summary) {
+  const lines = [];
+  const arrow = summary.baselineGrade === summary.currentGrade ? "\u2192" : "\u2192";
+  lines.push(
+    `Grade ${summary.baselineGrade} (${summary.baselineScore}%) ${arrow} ${summary.currentGrade} (${summary.currentScore}%)`
+  );
+  lines.push("");
+  function section(label, entries) {
+    if (!entries.length) return;
+    lines.push(`${label} (${entries.length}):`);
+    for (const e of entries) {
+      const req = e.required ? " [required]" : "";
+      lines.push(`  - ${e.id}${req}: ${e.name}`);
+      if (e.baselineDetails && e.currentDetails && e.baselineDetails !== e.currentDetails) {
+        lines.push(`      was: ${e.baselineDetails}`);
+        lines.push(`      now: ${e.currentDetails}`);
+      } else if (e.currentDetails) {
+        lines.push(`      ${e.currentDetails}`);
+      } else if (e.baselineDetails) {
+        lines.push(`      ${e.baselineDetails}`);
+      }
+    }
+    lines.push("");
+  }
+  section("Regressions", summary.regressions);
+  section("Fixes", summary.fixes);
+  section("New failures", summary.newFailures);
+  section("New passes", summary.newPasses);
+  section("Removed tests", summary.removed);
+  if (summary.regressions.length + summary.fixes.length + summary.newFailures.length + summary.newPasses.length + summary.removed.length === 0) {
+    lines.push("No changes between baseline and current.");
+  }
+  return lines.join("\n");
+}
+function hasRegressions(summary) {
+  return summary.regressions.length > 0 || summary.newFailures.some((e) => e.required);
+}
+
+// src/mcp/server.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2, resolve as resolve2 } from "path";
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/mcp/tools.ts
+import { z } from "zod";
+
+// src/runner.ts
+import { createRequire } from "module";
+import { request as request2 } from "undici";
+
+// src/badge.ts
+import { createHash } from "crypto";
+function urlHash(url) {
+  return createHash("sha256").update(url).digest("hex").slice(0, 24);
+}
+function generateBadge(url) {
+  const hash = urlHash(url);
+  const imageUrl = `https://mcp.hosting/api/compliance/ext/${hash}/badge`;
+  const reportUrl = `https://mcp.hosting/compliance/ext/${hash}`;
+  return {
+    imageUrl,
+    reportUrl,
+    markdown: `[![MCP Compliant](${imageUrl})](${reportUrl})`,
+    html: `<a href="${reportUrl}"><img src="${imageUrl}" alt="MCP Compliant"></a>`
+  };
+}
+
+// src/grader.ts
+function computeGrade(score) {
+  if (score >= 90) return "A";
+  if (score >= 75) return "B";
+  if (score >= 60) return "C";
+  if (score >= 40) return "D";
+  return "F";
+}
+function computeScore(tests) {
+  const total = tests.length;
+  const passed = tests.filter((t) => t.passed).length;
+  const failed = total - passed;
+  const requiredTests = tests.filter((t) => t.required);
+  const requiredPassed = requiredTests.filter((t) => t.passed).length;
+  const requiredScore = requiredTests.length > 0 ? requiredPassed / requiredTests.length * 70 : 70;
+  const optionalTests = tests.filter((t) => !t.required);
+  const optionalPassed = optionalTests.filter((t) => t.passed).length;
+  const optionalScore = optionalTests.length > 0 ? optionalPassed / optionalTests.length * 30 : 30;
+  const score = Math.round(requiredScore + optionalScore);
+  const overall = requiredPassed === requiredTests.length ? passed === total ? "pass" : "partial" : "fail";
+  const categories = {};
+  for (const t of tests) {
+    if (!categories[t.category]) categories[t.category] = { passed: 0, total: 0 };
+    categories[t.category].total++;
+    if (t.passed) categories[t.category].passed++;
+  }
+  return {
+    score,
+    grade: computeGrade(score),
+    overall,
+    summary: { total, passed, failed, required: requiredTests.length, requiredPassed },
+    categories
+  };
+}
+
 // src/types.ts
+var REPORT_SCHEMA_VERSION = "1";
 var TEST_DEFINITIONS = [
   // ── Transport (13 tests) ─────────────────────────────────────────
   {
@@ -823,6 +1047,15 @@ var TEST_DEFINITIONS = [
     description: "Sends a tools/call request with _meta.progressToken and checks if the server sends progress notifications via SSE. Progress support is optional but recommended for long-running operations.",
     recommendation: "When a request includes _meta.progressToken, send notifications/progress events via SSE to report progress. Include progressToken, progress (current), and optionally total fields."
   },
+  {
+    id: "lifecycle-meta-tolerance",
+    name: "Tolerates _meta field on requests",
+    category: "lifecycle",
+    required: false,
+    specRef: "basic/utilities#_meta",
+    description: "Sends a ping with params._meta = { extra: 'value' } and verifies the server doesn't error. The 2025-11-25 spec allows arbitrary _meta on any request; servers should ignore unknown _meta fields gracefully.",
+    recommendation: "Treat the _meta field as opaque \u2014 pass it through your request validator, but do not reject requests for unknown _meta keys. The MCP spec reserves _meta for protocol/transport metadata and forward-compat extensibility."
+  },
   // ── Tools (4 tests) ──────────────────────────────────────────────
   {
     id: "tools-list",
@@ -1535,7 +1768,7 @@ async function runComplianceSuite(target, options = {}) {
           if (attempt < retries) await new Promise((r) => setTimeout(r, 1e3 * (attempt + 1)));
         }
       }
-      tests.push({
+      const result = {
         id,
         name,
         category,
@@ -1544,8 +1777,10 @@ async function runComplianceSuite(target, options = {}) {
         details: lastResult.details,
         durationMs: Date.now() - start,
         specRef: `${SPEC_BASE}/${specRef}`
-      });
+      };
+      tests.push(result);
       options.onProgress?.(id, lastResult.passed, lastResult.details);
+      options.onTestComplete?.(result);
     }
     await test(
       "transport-post",
@@ -2137,6 +2372,28 @@ async function runComplianceSuite(target, options = {}) {
         }
       }
     );
+    await test(
+      "lifecycle-meta-tolerance",
+      "Tolerates _meta field on requests",
+      "lifecycle",
+      false,
+      "basic/utilities#_meta",
+      async () => {
+        try {
+          const res = await rpc("ping", { _meta: { "mcp-compliance/probe": "1" } });
+          const body = res.body;
+          if (body.error) {
+            return {
+              passed: false,
+              details: `Server rejected _meta on ping (code ${body.error.code}). _meta should be ignored, not error.`
+            };
+          }
+          return { passed: true, details: "Server accepted ping with arbitrary _meta field" };
+        } catch (err) {
+          return { passed: false, details: `Error: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+    );
     await test(
       "transport-content-type-init",
       "Initialize response has valid content type",
@@ -4019,6 +4276,7 @@ async function runComplianceSuite(target, options = {}) {
     const { score, grade, overall, summary, categories } = computeScore(tests);
     const badge = generateBadge(displayUrl);
     return {
+      schemaVersion: REPORT_SCHEMA_VERSION,
       specVersion: SPEC_VERSION,
       toolVersion: TOOL_VERSION,
       url: displayUrl,
@@ -4610,6 +4868,134 @@ function formatMarkdown(report) {
   }
   return lines.join("\n");
 }
+function formatHtml(report) {
+  const gradeColors = {
+    A: "#10b981",
+    B: "#84cc16",
+    C: "#eab308",
+    D: "#f97316",
+    F: "#ef4444"
+  };
+  const gradeColor2 = gradeColors[report.grade] || "#6b7280";
+  function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  }
+  const failed = report.tests.filter((t) => !t.passed);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const cat of CATEGORY_ORDER) grouped.set(cat, []);
+  for (const t of report.tests) grouped.get(t.category)?.push(t);
+  const isStdio = report.url.startsWith("stdio:");
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>MCP Compliance \u2014 ${esc(report.url)} \u2014 Grade ${report.grade}</title>
+<style>
+  :root { color-scheme: light dark; }
+  *, *::before, *::after { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; background: #0b0f17; color: #e5e7eb; }
+  @media (prefers-color-scheme: light) { body { background: #f9fafb; color: #111827; } .card { background: #fff !important; border-color: #e5e7eb !important; } .muted { color: #6b7280 !important; } }
+  .container { max-width: 960px; margin: 0 auto; padding: 32px 24px; }
+  header { text-align: center; margin-bottom: 32px; }
+  h1 { font-size: 28px; margin: 0 0 4px; }
+  .muted { color: #9ca3af; font-size: 13px; }
+  .grade-card { background: #111827; border: 1px solid #1f2937; border-radius: 12px; padding: 32px; margin: 24px 0; text-align: center; }
+  .grade-letter { font-size: 96px; font-weight: 700; line-height: 1; color: ${gradeColor2}; margin: 0; }
+  .grade-score { font-size: 24px; font-weight: 600; margin-top: 4px; }
+  .grade-overall { display: inline-block; padding: 4px 12px; border-radius: 999px; font-size: 12px; font-weight: 600; text-transform: uppercase; margin-top: 12px; }
+  .grade-overall.pass { background: #064e3b; color: #6ee7b7; }
+  .grade-overall.partial { background: #78350f; color: #fcd34d; }
+  .grade-overall.fail { background: #7f1d1d; color: #fca5a5; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: 12px; margin: 24px 0; }
+  .cat-card { background: #111827; border: 1px solid #1f2937; border-radius: 8px; padding: 16px; text-align: center; }
+  .cat-stat { font-size: 24px; font-weight: 700; }
+  .cat-label { font-size: 12px; color: #9ca3af; text-transform: uppercase; letter-spacing: 0.05em; margin-top: 4px; }
+  .cat-stat.full { color: #10b981; }
+  .cat-stat.partial { color: #eab308; }
+  .cat-stat.empty { color: #ef4444; }
+  .card { background: #111827; border: 1px solid #1f2937; border-radius: 8px; padding: 20px; margin: 16px 0; }
+  .card h2 { margin-top: 0; font-size: 16px; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th, td { text-align: left; padding: 8px 12px; border-bottom: 1px solid #1f2937; vertical-align: top; }
+  th { font-weight: 600; color: #9ca3af; font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; }
+  td.status { white-space: nowrap; font-weight: 600; }
+  td.status.pass { color: #10b981; }
+  td.status.fail { color: #ef4444; }
+  td.id { font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 12px; color: #9ca3af; }
+  .badge-tag { display: inline-block; background: #1f2937; color: #fcd34d; font-size: 10px; padding: 2px 6px; border-radius: 4px; text-transform: uppercase; letter-spacing: 0.05em; }
+  .warn { background: #78350f; color: #fcd34d; padding: 12px 16px; border-radius: 8px; margin: 8px 0; font-size: 13px; }
+  .badge-img { background: #fff; padding: 8px; border-radius: 6px; display: inline-block; margin-top: 8px; }
+  code { background: #1f2937; padding: 1px 6px; border-radius: 4px; font-size: 12px; }
+  details summary { cursor: pointer; padding: 8px 0; font-weight: 600; }
+  footer { text-align: center; color: #6b7280; font-size: 12px; margin-top: 48px; }
+  footer a { color: #60a5fa; text-decoration: none; }
+</style>
+</head>
+<body>
+<div class="container">
+  <header>
+    <h1>MCP Compliance Report</h1>
+    <div class="muted">${esc(report.url)}</div>
+    <div class="muted" style="margin-top:6px">Spec ${esc(report.specVersion)} \xB7 Tool v${esc(report.toolVersion)} \xB7 ${new Date(report.timestamp).toLocaleString()}</div>
+    ${report.serverInfo.name ? `<div class="muted">Server: ${esc(report.serverInfo.name)}${report.serverInfo.version ? ` v${esc(report.serverInfo.version)}` : ""}</div>` : ""}
+  </header>
+
+  <div class="grade-card">
+    <div class="grade-letter">${esc(report.grade)}</div>
+    <div class="grade-score">${report.score}%</div>
+    <div class="grade-overall ${esc(report.overall)}">${esc(report.overall)}</div>
+    <div class="muted" style="margin-top:12px">${report.summary.passed} / ${report.summary.total} tests passed \xB7 ${report.summary.requiredPassed} / ${report.summary.required} required</div>
+  </div>
+
+  <div class="grid">
+    ${CATEGORY_ORDER.filter((c) => report.categories[c] && report.categories[c].total > 0).map((c) => {
+    const s = report.categories[c];
+    const cls = s.passed === s.total ? "full" : s.passed > 0 ? "partial" : "empty";
+    return `<div class="cat-card"><div class="cat-stat ${cls}">${s.passed}/${s.total}</div><div class="cat-label">${esc(CATEGORY_LABELS[c] || c)}</div></div>`;
+  }).join("")}
+  </div>
+
+  ${report.warnings.length ? `<div class="card"><h2>Warnings (${report.warnings.length})</h2>${report.warnings.map((w) => `<div class="warn">${esc(w)}</div>`).join("")}</div>` : ""}
+
+  ${failed.length ? `<div class="card"><h2>Failed tests (${failed.length})</h2>
+    <table><thead><tr><th>Status</th><th>Test</th><th>Details</th></tr></thead><tbody>
+    ${failed.map(
+    (t) => `<tr>
+      <td class="status fail">FAIL</td>
+      <td><div>${esc(t.name)} ${t.required ? '<span class="badge-tag">Required</span>' : ""}</div><div class="id">${esc(t.id)}</div></td>
+      <td>${esc(t.details)}${t.specRef ? ` <a href="${esc(t.specRef)}" class="muted">[spec]</a>` : ""}</td>
+    </tr>`
+  ).join("")}
+    </tbody></table></div>` : ""}
+
+  ${[...grouped.entries()].filter(([, tests]) => tests.length > 0).map(
+    ([cat, tests]) => `<div class="card"><h2>${esc(CATEGORY_LABELS[cat] || cat)}</h2>
+    <table><thead><tr><th>Status</th><th>Test</th><th>Details</th><th>Time</th></tr></thead><tbody>
+    ${tests.map(
+      (t) => `<tr>
+      <td class="status ${t.passed ? "pass" : "fail"}">${t.passed ? "PASS" : "FAIL"}</td>
+      <td><div>${esc(t.name)} ${t.required ? '<span class="badge-tag">Required</span>' : ""}</div><div class="id">${esc(t.id)}</div></td>
+      <td>${esc(t.details)}${t.specRef ? ` <a href="${esc(t.specRef)}" class="muted">[spec]</a>` : ""}</td>
+      <td class="muted">${t.durationMs}ms</td>
+    </tr>`
+    ).join("")}
+    </tbody></table></div>`
+  ).join("")}
+
+  ${!isStdio ? `<div class="card"><h2>Embed badge</h2>
+    <div class="badge-img"><img src="${esc(report.badge.imageUrl)}" alt="MCP Compliance"></div>
+    <p class="muted" style="margin-top:12px">Markdown:</p>
+    <code style="display:block; padding:8px; background:#0b0f17">${esc(report.badge.markdown)}</code></div>` : `<div class="card"><h2>Local badge</h2>
+    <p class="muted">Stdio servers can't be published to mcp.hosting (no public URL). Use <code>--output badge.svg</code> to write a local badge image.</p></div>`}
+
+  <footer>
+    Generated by <a href="https://www.npmjs.com/package/@yawlabs/mcp-compliance">@yawlabs/mcp-compliance</a> v${esc(report.toolVersion)}
+  </footer>
+</div>
+</body>
+</html>`;
+}
 
 // src/token-store.ts
 import { createHash as createHash2 } from "crypto";
@@ -4619,7 +5005,7 @@ import { dirname as dirname2, join as join3 } from "path";
 var STORE_DIR = join3(homedir(), ".mcp-compliance");
 var STORE_PATH = join3(STORE_DIR, "tokens.json");
 function hashUrl(url) {
-  return createHash2("sha256").update(url).digest("hex").slice(0, 12);
+  return createHash2("sha256").update(url).digest("hex").slice(0, 24);
 }
 function readStore() {
   if (!existsSync3(STORE_PATH)) return {};
@@ -4794,7 +5180,7 @@ program.command("test").description("Run the full compliance test suite against
   "[target]",
   "Server URL, or command to spawn as a stdio server (optional when a config file defines 'target')"
 ).argument("[extraArgs...]", "Additional args passed to the stdio command").addOption(
-  new Option("--format <format>", "Output format").choices(["terminal", "json", "sarif", "github", "markdown"]).default("terminal")
+  new Option("--format <format>", "Output format").choices(["terminal", "json", "sarif", "github", "markdown", "html"]).default("terminal")
 ).option("--config <path>", "Load options from a config file (default: mcp-compliance.config.json in cwd)").option("--output <file>", "Write a local SVG badge to the given path after the run (works with any transport)").option("--list", "Print the test IDs that would run given current filters, then exit (no connection)").addOption(
   new Option(
     "--transport <kind>",
@@ -4817,7 +5203,7 @@ program.command("test").description("Run the full compliance test suite against
   "--timeout <ms>",
   "Request timeout in milliseconds (bump to 30000+ for stdio servers with slow startup)",
   "15000"
-).option("--no-color", "Disable colored output (also honors NO_COLOR env var)").option("--preflight-timeout <ms>", "Preflight connectivity check timeout in milliseconds").option("--retries <n>", "Number of retries for failed tests", "0").option(
+).option("--no-color", "Disable colored output (also honors NO_COLOR env var)").option("--watch", "Re-run tests when files in the cwd change (stdio targets only)").option("--preflight-timeout <ms>", "Preflight connectivity check timeout in milliseconds").option("--retries <n>", "Number of retries for failed tests", "0").option(
   "--only <items>",
   'Only run matching categories or test IDs, comma-separated (e.g., "transport,lifecycle" or "transport-post,lifecycle-init")',
   parseList
@@ -4862,48 +5248,92 @@ ${defs.length} tests would run for transport=${transportKind}`));
         },
         config
       );
-      if (opts.format === "terminal") {
-        console.log(chalk2.dim(`
-Testing ${describeTarget(transportTarget)}...
-`));
-      }
       const only = opts.only ?? config?.only;
       const skip = opts.skip ?? config?.skip;
       const verbose = opts.verbose ?? config?.verbose;
-      const report = await runComplianceSuite(transportTarget, {
-        timeout: parsePositiveInt(opts.timeout, "--timeout", 1),
-        preflightTimeout: opts.preflightTimeout ? parsePositiveInt(opts.preflightTimeout, "--preflight-timeout", 1) : config?.preflightTimeout,
-        retries: parsePositiveInt(opts.retries, "--retries"),
-        only,
-        skip,
-        onProgress: verbose ? (testId, passed, details) => {
-          const icon = passed ? chalk2.green("PASS") : chalk2.red("FAIL");
-          console.log(`  ${icon} ${testId} \u2014 ${details}`);
-        } : void 0
-      });
-      if (verbose && opts.format === "terminal") {
-        console.log("");
-      }
-      if (opts.format === "json") {
-        console.log(formatJson(report));
-      } else if (opts.format === "sarif") {
-        console.log(formatSarif(report));
-      } else if (opts.format === "github") {
-        console.log(formatGithub(report));
-      } else if (opts.format === "markdown") {
-        console.log(formatMarkdown(report));
-      } else {
-        console.log(formatTerminal(report));
-      }
-      if (opts.output) {
-        const svg = renderBadgeSvg({ grade: report.grade, score: report.score, timestamp: report.timestamp });
-        writeFileSync2(opts.output, svg, "utf8");
+      const strict = opts.strict ?? config?.strict;
+      async function runOnce() {
         if (opts.format === "terminal") {
           console.log(chalk2.dim(`
+Testing ${describeTarget(transportTarget)}...
+`));
+        }
+        const report2 = await runComplianceSuite(transportTarget, {
+          timeout: parsePositiveInt(opts.timeout, "--timeout", 1),
+          preflightTimeout: opts.preflightTimeout ? parsePositiveInt(opts.preflightTimeout, "--preflight-timeout", 1) : config?.preflightTimeout,
+          retries: parsePositiveInt(opts.retries, "--retries"),
+          only,
+          skip,
+          onProgress: verbose ? (testId, passed, details) => {
+            const icon = passed ? chalk2.green("PASS") : chalk2.red("FAIL");
+            console.log(`  ${icon} ${testId} \u2014 ${details}`);
+          } : void 0
+        });
+        if (verbose && opts.format === "terminal") {
+          console.log("");
+        }
+        if (opts.format === "json") {
+          console.log(formatJson(report2));
+        } else if (opts.format === "sarif") {
+          console.log(formatSarif(report2));
+        } else if (opts.format === "github") {
+          console.log(formatGithub(report2));
+        } else if (opts.format === "markdown") {
+          console.log(formatMarkdown(report2));
+        } else if (opts.format === "html") {
+          console.log(formatHtml(report2));
+        } else {
+          console.log(formatTerminal(report2));
+        }
+        if (opts.output) {
+          const svg = renderBadgeSvg({ grade: report2.grade, score: report2.score, timestamp: report2.timestamp });
+          writeFileSync2(opts.output, svg, "utf8");
+          if (opts.format === "terminal") {
+            console.log(chalk2.dim(`
 Badge SVG written to ${opts.output}`));
+          }
         }
+        return report2;
       }
-      const strict = opts.strict ?? config?.strict;
+      if (opts.watch) {
+        if (transportTarget.type !== "stdio") {
+          console.error(chalk2.red("\nError: --watch only applies to stdio targets (HTTP servers are remote).\n"));
+          process.exit(1);
+        }
+        await runOnce();
+        let pending = null;
+        let running = false;
+        const watcher = fsWatch(process.cwd(), { recursive: true }, (_event, filename) => {
+          if (!filename) return;
+          const f = String(filename).replace(/\\/g, "/");
+          if (/(^|\/)(node_modules|\.git|dist|coverage|\.next|\.cache|\.turbo)(\/|$)/.test(f)) return;
+          if (/\.(log|swp|tmp)$|~$/.test(f)) return;
+          if (pending) clearTimeout(pending);
+          pending = setTimeout(async () => {
+            if (running) return;
+            running = true;
+            try {
+              console.log(chalk2.dim(`
+[watch] ${f} changed \u2014 re-running...
+`));
+              await runOnce();
+            } catch (err) {
+              console.error(chalk2.red(`[watch] ${err instanceof Error ? err.message : String(err)}`));
+            } finally {
+              running = false;
+            }
+          }, 500);
+        });
+        process.on("SIGINT", () => {
+          watcher.close();
+          console.log(chalk2.dim("\n[watch] stopped"));
+          process.exit(0);
+        });
+        await new Promise(() => {
+        });
+        return;
+      }
+      const report = await runOnce();
       if (strict && report.overall === "fail") {
         process.exit(1);
       }
@@ -5058,6 +5488,55 @@ Error: ${message}
     process.exit(1);
   }
 });
+program.command("benchmark").description("Measure ping latency and throughput against an MCP server (URL or stdio command)").argument("[target]", "Server URL or stdio command").argument("[extraArgs...]", "Additional args for stdio command").option("-r, --requests <n>", "Number of ping requests to send", "100").option("-c, --concurrency <n>", "Concurrent in-flight requests", "1").option("--timeout <ms>", "Per-request timeout in milliseconds", "15000").option("--config <path>", "Load options from a config file").option("--format <format>", "terminal or json", "terminal").option("-H, --header <header>", "HTTP header (repeatable)", parseHeaderArg, {}).option("--auth <token>", 'Shorthand for -H "Authorization: <token>"').option("-E, --env <var>", "Env var for stdio (repeatable)", parseEnvVar, {}).option("--env-file <path>", "Load env vars from file").option("--cwd <dir>", "Working directory for stdio command").action(
+  async (target, extraArgs, opts) => {
+    try {
+      const config = loadConfig(opts.config);
+      const t = resolveTarget(
+        target,
+        extraArgs,
+        { header: opts.header, auth: opts.auth, env: opts.env, envFile: opts.envFile, cwd: opts.cwd },
+        config
+      );
+      const result = await runBenchmark(t, {
+        requests: parsePositiveInt(opts.requests, "--requests", 1),
+        concurrency: parsePositiveInt(opts.concurrency, "--concurrency", 1),
+        timeout: parsePositiveInt(opts.timeout, "--timeout", 1)
+      });
+      if (opts.format === "json") {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatBenchmark(result));
+      }
+      if (result.failed > 0) process.exit(1);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(chalk2.red(`
+Error: ${message}
+`));
+      process.exit(1);
+    }
+  }
+);
+program.command("diff").description("Compare two compliance JSON reports; exit 1 if there are regressions").argument("<baseline>", "Baseline report JSON file").argument("<current>", "Current report JSON file").option("--format <format>", "terminal or json", "terminal").action((baselinePath, currentPath, opts) => {
+  try {
+    const baseline = JSON.parse(readFileSync4(baselinePath, "utf8"));
+    const current = JSON.parse(readFileSync4(currentPath, "utf8"));
+    const summary = diffReports(baseline, current);
+    if (opts.format === "json") {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(formatDiff(summary));
+    }
+    if (hasRegressions(summary)) process.exit(1);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(chalk2.red(`
+Error: ${message}
+`));
+    process.exit(1);
+  }
+});
 program.command("init").description("Scaffold a mcp-compliance.config.json in the current directory").option("--force", "Overwrite an existing config file without asking").action(async (opts) => {
   const { existsSync: existsSync4, writeFileSync: write } = await import("fs");
   const { join: joinPath } = await import("path");