webhook-crash-lab-mcp 0.0.0-stage → 0.2.0

package/.agents/skills/webhook-crash-lab/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: webhook-crash-lab
+description: Test and fix webhook handlers (Stripe, GitHub) so they survive duplicate, concurrent and out-of-order deliveries and reject forged, missing or stale signatures. Use when writing, reviewing or debugging a webhook endpoint, after generating webhook code, or when a user reports double credits, double emails, "No signatures found matching the expected signature", or webhooks failing in production.
+---
+
+# webhook-crash-lab
+
+Webhook providers deliver events **at least once**: retries, duplicates, parallel copies, wrong order.
+webhook-crash-lab replays those deliveries against the real handler and checks both HTTP status and
+business state (for example "credits granted exactly once").
+
+## Loop
+
+1. **Find the handler** (`/webhook` route, `app/api/webhooks/*/route.ts`, `constructEvent` call).
+2. **Config.** If no `crash-lab.config.{mjs,js,ts}` exists, run `npx webhook-crash-lab init` and fill it in:
+   - `target`: the local dev URL of the webhook route, or an in-process `(req: Request) => Response` handler.
+   - `secret`: a **test** signing secret the handler verifies with (set it in the handler's env too).
+   - `event`: a realistic event (for example `checkout.session.completed`).
+   - `adapter` (`reset` / `snapshot`) + `expect.once`: needed for the duplicate scenarios. Point it at a
+     **test database only**, because `reset()` wipes state before every scenario.
+   - `sequence`: real event order, for the out-of-order scenario.
+3. **Run.** Call the `run_crash_lab` MCP tool with `{ configPath, cwd }`. Without the MCP server, use
+   `npx webhook-crash-lab run crash-lab.config.mjs --json crash-lab-report.json`, then
+   `explain_report` or read the JSON. Exit codes: 0 pass, 1 failures, 2 config error.
+4. **Fix the handler**, one failure at a time, in the order returned (signature → body → duplicates → ordering).
+   Use each failure's `fix` hint. Typical fixes:
+   - raw body for signature checks (`express.raw()`, `await req.text()`), never `express.json()` first;
+   - a unique insert on `event.id` (processed-events table) **before** side effects, in the same transaction;
+   - BullMQ `queue.add(name, data, { jobId: event.id })`;
+   - ignore events older than the latest one already applied for that object.
+5. **Re-run** the same tool with the same arguments. Repeat until `ok` is `true`. Do not weaken the config
+   or remove scenarios to make it pass.
+6. Suggest adding `npx webhook-crash-lab run` to CI, and the ESLint plugins
+   `eslint-plugin-webhook-safety` / `eslint-plugin-bullmq` for the static versions of these checks.
+
+## Rules
+
+- Never point crash-lab at production URLs, production databases or live secrets.
+- `not-tested` means the config lacks what that scenario needs (adapter / expect.once / sequence). Say so; do not report it as passing.
+- `run_demo` (no config needed) shows a broken vs fixed app if the user wants to see what is checked.

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "webhook-crash-lab",
+  "owner": {
+    "name": "Krrish Kumar",
+    "url": "https://github.com/Krrishkumar125"
+  },
+  "metadata": {
+    "description": "Webhook reliability tools for coding agents: run webhook-crash-lab, fix, re-run."
+  },
+  "plugins": [
+    {
+      "name": "webhook-crash-lab",
+      "source": "./",
+      "description": "Test webhook handlers against duplicate, concurrent, out-of-order and forged deliveries, then fix and re-run until they pass."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "webhook-crash-lab",
+  "version": "0.2.0",
+  "description": "Test webhook handlers against duplicate, concurrent, out-of-order and forged deliveries, then fix and re-run until they pass.",
+  "author": { "name": "Krrish Kumar", "url": "https://github.com/Krrishkumar125" },
+  "homepage": "https://github.com/Krrishkumar125/webhook-crash-lab",
+  "repository": "https://github.com/Krrishkumar125/webhook-crash-lab-mcp",
+  "license": "MIT",
+  "keywords": ["webhooks", "stripe", "idempotency", "testing", "bullmq"]
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "webhook-crash-lab": {
+      "command": "npx",
+      "args": ["-y", "webhook-crash-lab-mcp"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.2.0 (2026-10-22)
+
+- `run_crash_lab` accepts TypeScript configs (`.ts`/`.mts`/`.cts`) by delegating config loading to
+  webhook-crash-lab 0.3.0; jiti is bundled so this works on Node 20 too.
+
+## 0.1.0 (2026-10-22)
+
+- MCP server with `run_crash_lab`, `run_demo`, `explain_report`, `list_scenarios`.
+- Claude Code plugin (manifest, marketplace, skill, `.mcp.json`) and Codex skill + AGENTS.md snippet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krrish Kumar
+
+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

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# webhook-crash-lab-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Krrishkumar125/webhook-crash-lab-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Krrishkumar125/webhook-crash-lab-mcp/actions/workflows/ci.yml)
+
+Coding agents write webhook handlers that work for one test event and break in production on
+retries, duplicates and forged signatures. This package gives them a loop: **run
+[webhook-crash-lab](https://github.com/Krrishkumar125/webhook-crash-lab) → read structured failures with fix hints → fix → re-run**.
+
+It ships three things:
+
+|                         | What                                                                  | Where                                       |
+| ----------------------- | --------------------------------------------------------------------- | ------------------------------------------- |
+| MCP server              | `webhook-crash-lab-mcp` (stdio, official MCP TypeScript SDK)          | `src/`                                      |
+| Claude Code plugin      | skill + MCP server config                                             | `.claude-plugin/`, `skills/`, `.mcp.json`   |
+| Codex / any-agent skill | same skill in the open Agent Skills format, plus an AGENTS.md snippet | `.agents/skills/`, `docs/AGENTS-snippet.md` |
+
+## Tools
+
+| Tool             | Input                                                               | Returns                                                                                             |
+| ---------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `run_crash_lab`  | `configPath`, `cwd?`, `scenarios?`, `reportPath?`                   | `ok`, counts, `failures[]` (id, failed checks, why, fix) in fix order, `notTested[]`, `nextSteps[]` |
+| `run_demo`       | `mode: "broken" \| "fixed"`                                         | same shape, against the built-in demo app (no config needed)                                        |
+| `explain_report` | `reportPath` or `report` (JSON from `webhook-crash-lab run --json`) | same shape, e.g. for a CI report                                                                    |
+| `list_scenarios` | –                                                                   | every scenario with what / why / fix                                                                |
+
+Every result comes back as text for the model and `structuredContent` (with an `outputSchema`) for clients.
+Errors such as a missing or invalid config come back as `isError` results, not crashes.
+
+## 60-second start
+
+**Claude Code**
+
+```sh
+claude mcp add webhook-crash-lab -- npx -y webhook-crash-lab-mcp
+# or the full plugin (MCP server + skill):
+#   /plugin marketplace add Krrishkumar125/webhook-crash-lab-mcp
+#   /plugin install webhook-crash-lab@webhook-crash-lab
+```
+
+**Codex**
+
+```sh
+codex mcp add webhook-crash-lab -- npx -y webhook-crash-lab-mcp
+mkdir -p .agents/skills && cp -r node_modules/webhook-crash-lab-mcp/.agents/skills/webhook-crash-lab .agents/skills/
+```
+
+**Cursor / other MCP clients**
+
+```json
+{
+  "mcpServers": {
+    "webhook-crash-lab": { "command": "npx", "args": ["-y", "webhook-crash-lab-mcp"] }
+  }
+}
+```
+
+Then ask: _"Run the webhook crash lab demo"_, or _"Make my Stripe webhook pass webhook-crash-lab"_.
+Paste [`docs/AGENTS-snippet.md`](docs/AGENTS-snippet.md) into `AGENTS.md` / `CLAUDE.md` to make it a standing rule.
+
+## Safety
+
+`run_crash_lab` imports your crash-lab config (`.mjs`/`.js`/`.cjs`, or `.ts`/`.mts`/`.cts` via the bundled jiti) (it is code, like any config file) and sends requests to
+its `target`. Point configs at a local server and a **test** database and secret only. The skill tells
+agents never to use production URLs or live secrets.
+
+## Related
+
+- [webhook-crash-lab](https://github.com/Krrishkumar125/webhook-crash-lab): the CLI/library this wraps
+- [eslint-plugin-webhook-safety](https://github.com/Krrishkumar125/eslint-plugin-webhook-safety) and
+  [eslint-plugin-bullmq](https://github.com/Krrishkumar125/eslint-plugin-bullmq): the same bugs, caught statically
+
+## License
+
+MIT © Krrish Kumar

package/dist/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import {
+  createServer
+} from "./chunk-UR6UXUAN.js";
+
+// src/bin.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+var server = createServer();
+await server.connect(new StdioServerTransport());
+console.error("webhook-crash-lab MCP server running on stdio");
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { createServer } from './server.js';\n\nconst server = createServer();\nawait server.connect(new StdioServerTransport());\n// stdout is the protocol channel; log only to stderr.\nconsole.error('webhook-crash-lab MCP server running on stdio');\n"],"mappings":";;;;;;AACA,SAAS,4BAA4B;AAGrC,IAAM,SAAS,aAAa;AAC5B,MAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;AAE/C,QAAQ,MAAM,+CAA+C;","names":[]}

package/dist/chunk-UR6UXUAN.js

@@ -0,0 +1,256 @@
+// src/core.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import {
+  demoConfig,
+  loadConfig as loadLabConfig,
+  runCrashLab,
+  SCENARIOS,
+  toJson
+} from "webhook-crash-lab";
+var PRIORITY = [
+  "missing-signature",
+  "invalid-signature",
+  "stale-timestamp",
+  "malformed-json",
+  "single-valid",
+  "duplicate-sequential",
+  "duplicate-concurrent",
+  "out-of-order"
+];
+var SCENARIO_IDS = SCENARIOS.map((s) => s.id);
+function summarize(result, reportPath) {
+  const rank = (id) => PRIORITY.indexOf(id);
+  const failures = result.scenarios.filter((s) => s.status === "fail").sort((a, b) => rank(a.id) - rank(b.id)).map((s) => ({
+    id: s.id,
+    title: s.title,
+    why: s.why,
+    fix: s.fix,
+    failedChecks: s.checks.filter((c) => c.status === "fail").map(({ name, detail }) => ({ name, detail })),
+    responses: s.responses
+  }));
+  const notTested = result.scenarios.filter((s) => s.status === "not-tested").map((s) => s.id);
+  const nextSteps = [];
+  if (failures.length) {
+    nextSteps.push(
+      `Fix in this order: ${failures.map((f) => f.id).join(" \u2192 ")}. Each failure has a "fix" hint.`,
+      "Change the webhook handler (not the test config), then re-run the same tool with the same arguments. Stop when ok is true.",
+      "Static checks for the same bugs: eslint-plugin-webhook-safety and eslint-plugin-bullmq."
+    );
+  } else {
+    nextSteps.push(
+      "All scenarios pass. Keep `npx webhook-crash-lab run` in CI so this stays true."
+    );
+  }
+  if (notTested.length) {
+    nextSteps.push(
+      `${notTested.length} scenario(s) not tested (${notTested.join(", ")}): duplicate checks need an \`adapter\` + \`expect.once\`; out-of-order needs \`sequence\` in the config.`
+    );
+  }
+  return {
+    name: result.name,
+    ok: result.ok,
+    summary: result.summary,
+    failures,
+    notTested,
+    scenarios: result.scenarios.map((s) => ({ id: s.id, status: s.status })),
+    nextSteps,
+    ...reportPath ? { reportPath } : {}
+  };
+}
+function writeReport(result, reportPath) {
+  mkdirSync(dirname(reportPath), { recursive: true });
+  writeFileSync(reportPath, toJson(result));
+}
+async function loadConfig(configPath, cwd = process.cwd()) {
+  return loadLabConfig(configPath, cwd);
+}
+async function runFromConfig(opts) {
+  for (const id of opts.scenarios ?? []) {
+    if (!SCENARIO_IDS.includes(id)) {
+      throw new Error(`Unknown scenario "${id}". Known: ${SCENARIO_IDS.join(", ")}`);
+    }
+  }
+  const config = await loadConfig(opts.configPath, opts.cwd);
+  const result = await runCrashLab(
+    opts.scenarios?.length ? { ...config, scenarios: opts.scenarios } : config
+  );
+  const reportPath = opts.reportPath && resolve(opts.cwd ?? process.cwd(), opts.reportPath);
+  if (reportPath) writeReport(result, reportPath);
+  return summarize(result, reportPath);
+}
+async function runDemo(mode) {
+  return summarize(await runCrashLab(demoConfig(mode)));
+}
+function isReport(x) {
+  const r = x;
+  return !!r && typeof r === "object" && typeof r.ok === "boolean" && Array.isArray(r.scenarios) && !!r.summary;
+}
+function explainReport(input) {
+  let report = input.report;
+  if (input.reportPath) {
+    const path = resolve(input.cwd ?? process.cwd(), input.reportPath);
+    if (!existsSync(path)) throw new Error(`Report not found: ${path}`);
+    report = readFileSync(path, "utf8");
+  }
+  if (report === void 0)
+    throw new Error("Pass reportPath or report (the JSON from `webhook-crash-lab run --json`).");
+  if (typeof report === "string") {
+    try {
+      report = JSON.parse(report);
+    } catch {
+      throw new Error("Report is not valid JSON.");
+    }
+  }
+  if (!isReport(report))
+    throw new Error(
+      "This is not a webhook-crash-lab JSON report (expected ok, summary, scenarios)."
+    );
+  return summarize(report, input.reportPath);
+}
+function listScenarios() {
+  return SCENARIOS.map(({ id, title, what, why, fix }) => ({ id, title, what, why, fix }));
+}
+function renderSummary(s) {
+  const lines = [
+    `${s.ok ? "PASS" : "FAIL"} ${s.name}: ${s.summary.pass} pass, ${s.summary.fail} fail, ${s.summary.notTested} not tested`
+  ];
+  for (const f of s.failures) {
+    lines.push("", `\u2717 ${f.id}: ${f.title}`);
+    for (const c of f.failedChecks) lines.push(`  ${c.name}: ${c.detail}`);
+    lines.push(`  why: ${f.why}`, `  fix: ${f.fix}`);
+  }
+  lines.push("", "Next steps:", ...s.nextSteps.map((n) => `- ${n}`));
+  if (s.reportPath) lines.push(`Report written to ${s.reportPath}`);
+  return lines.join("\n");
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+var VERSION = "0.2.0";
+var summaryShape = {
+  name: z.string(),
+  ok: z.boolean(),
+  summary: z.object({ pass: z.number(), fail: z.number(), notTested: z.number() }),
+  failures: z.array(
+    z.object({
+      id: z.string(),
+      title: z.string(),
+      why: z.string(),
+      fix: z.string(),
+      failedChecks: z.array(z.object({ name: z.string(), detail: z.string() })),
+      responses: z.array(z.number())
+    })
+  ),
+  notTested: z.array(z.string()),
+  scenarios: z.array(z.object({ id: z.string(), status: z.string() })),
+  nextSteps: z.array(z.string()),
+  reportPath: z.string().optional()
+};
+async function respond(work) {
+  try {
+    const s = await work();
+    return {
+      content: [{ type: "text", text: renderSummary(s) }],
+      structuredContent: s
+    };
+  } catch (err) {
+    return { isError: true, content: [{ type: "text", text: err.message }] };
+  }
+}
+function createServer() {
+  const server = new McpServer({ name: "webhook-crash-lab", version: VERSION });
+  server.registerTool(
+    "run_crash_lab",
+    {
+      title: "Run webhook-crash-lab",
+      description: "Replay hostile webhook deliveries (duplicates, concurrent duplicates, out-of-order events, forged/missing/stale signatures, malformed JSON) against the handler described by a crash-lab config file, and return structured failures with fix hints. Use a TEST database and test secret only. Create a config with `npx webhook-crash-lab init` if none exists.",
+      inputSchema: {
+        configPath: z.string().describe(
+          "Path to a crash-lab config (.mjs, .js, .cjs, .ts, .mts or .cts), relative to cwd"
+        ),
+        cwd: z.string().optional().describe("Project directory; defaults to the server working directory"),
+        scenarios: z.array(z.enum(SCENARIO_IDS)).optional().describe("Run only these scenarios"),
+        reportPath: z.string().optional().describe("Also write the full JSON report here")
+      },
+      outputSchema: summaryShape,
+      annotations: { readOnlyHint: false, openWorldHint: true }
+    },
+    (args) => respond(() => runFromConfig(args))
+  );
+  server.registerTool(
+    "run_demo",
+    {
+      title: "Run the built-in demo",
+      description: 'Run crash-lab against its built-in demo credits app. "broken" shows the typical AI-generated Stripe handler failing; "fixed" shows the same app done right. Needs no config. Use it to show what crash-lab checks before setting up a real config.',
+      inputSchema: { mode: z.enum(["broken", "fixed"]).default("broken") },
+      outputSchema: summaryShape,
+      annotations: { readOnlyHint: true, openWorldHint: false }
+    },
+    ({ mode }) => respond(() => runDemo(mode))
+  );
+  server.registerTool(
+    "explain_report",
+    {
+      title: "Explain a crash-lab report",
+      description: "Read a JSON report produced by `webhook-crash-lab run --json <file>` (e.g. from CI) and return the failures in fix order, with why/fix hints and next steps.",
+      inputSchema: {
+        reportPath: z.string().optional(),
+        report: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("Report JSON, as text or object"),
+        cwd: z.string().optional()
+      },
+      outputSchema: summaryShape,
+      annotations: { readOnlyHint: true, openWorldHint: false }
+    },
+    (args) => respond(() => explainReport(args))
+  );
+  server.registerTool(
+    "list_scenarios",
+    {
+      title: "List crash-lab scenarios",
+      description: "List every scenario crash-lab can run, with what it sends, why it matters in production, and how to fix a failure.",
+      inputSchema: {},
+      outputSchema: {
+        scenarios: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            what: z.string(),
+            why: z.string(),
+            fix: z.string()
+          })
+        )
+      },
+      annotations: { readOnlyHint: true, openWorldHint: false }
+    },
+    () => {
+      const scenarios = listScenarios();
+      return {
+        content: [
+          {
+            type: "text",
+            text: scenarios.map((s) => `${s.id}: ${s.what}
+  fix: ${s.fix}`).join("\n")
+          }
+        ],
+        structuredContent: { scenarios }
+      };
+    }
+  );
+  return server;
+}
+
+export {
+  SCENARIO_IDS,
+  summarize,
+  loadConfig,
+  runFromConfig,
+  runDemo,
+  explainReport,
+  listScenarios,
+  renderSummary,
+  VERSION,
+  createServer
+};
+//# sourceMappingURL=chunk-UR6UXUAN.js.map

package/dist/chunk-UR6UXUAN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/server.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';\nimport { dirname, resolve } from 'node:path';\nimport {\n  demoConfig,\n  loadConfig as loadLabConfig,\n  runCrashLab,\n  SCENARIOS,\n  toJson,\n  type CrashLabConfig,\n  type CrashLabResult,\n  type ScenarioId,\n} from 'webhook-crash-lab';\n\nexport type { CrashLabResult, ScenarioId };\n\n/** Fix security first, then duplicates, then ordering: later fixes depend on earlier ones. */\nconst PRIORITY: ScenarioId[] = [\n  'missing-signature',\n  'invalid-signature',\n  'stale-timestamp',\n  'malformed-json',\n  'single-valid',\n  'duplicate-sequential',\n  'duplicate-concurrent',\n  'out-of-order',\n];\nexport const SCENARIO_IDS = SCENARIOS.map((s) => s.id) as ScenarioId[];\n\nexport interface Failure {\n  id: ScenarioId;\n  title: string;\n  why: string;\n  fix: string;\n  failedChecks: { name: string; detail: string }[];\n  responses: number[];\n}\n\nexport interface Summary {\n  name: string;\n  ok: boolean;\n  summary: { pass: number; fail: number; notTested: number };\n  /** Failing scenarios, most important first. */\n  failures: Failure[];\n  notTested: ScenarioId[];\n  scenarios: { id: ScenarioId; status: string }[];\n  nextSteps: string[];\n  reportPath?: string;\n}\n\nexport function summarize(result: CrashLabResult, reportPath?: string): Summary {\n  const rank = (id: ScenarioId) => PRIORITY.indexOf(id);\n  const failures = result.scenarios\n    .filter((s) => s.status === 'fail')\n    .sort((a, b) => rank(a.id) - rank(b.id))\n    .map<Failure>((s) => ({\n      id: s.id,\n      title: s.title,\n      why: s.why,\n      fix: s.fix,\n      failedChecks: s.checks\n        .filter((c) => c.status === 'fail')\n        .map(({ name, detail }) => ({ name, detail })),\n      responses: s.responses,\n    }));\n  const notTested = result.scenarios.filter((s) => s.status === 'not-tested').map((s) => s.id);\n\n  const nextSteps: string[] = [];\n  if (failures.length) {\n    nextSteps.push(\n      `Fix in this order: ${failures.map((f) => f.id).join(' → ')}. Each failure has a \"fix\" hint.`,\n      'Change the webhook handler (not the test config), then re-run the same tool with the same arguments. Stop when ok is true.',\n      'Static checks for the same bugs: eslint-plugin-webhook-safety and eslint-plugin-bullmq.',\n    );\n  } else {\n    nextSteps.push(\n      'All scenarios pass. Keep `npx webhook-crash-lab run` in CI so this stays true.',\n    );\n  }\n  if (notTested.length) {\n    nextSteps.push(\n      `${notTested.length} scenario(s) not tested (${notTested.join(', ')}): duplicate checks need an \\`adapter\\` + \\`expect.once\\`; out-of-order needs \\`sequence\\` in the config.`,\n    );\n  }\n  return {\n    name: result.name,\n    ok: result.ok,\n    summary: result.summary,\n    failures,\n    notTested,\n    scenarios: result.scenarios.map((s) => ({ id: s.id, status: s.status })),\n    nextSteps,\n    ...(reportPath ? { reportPath } : {}),\n  };\n}\n\nfunction writeReport(result: CrashLabResult, reportPath: string): void {\n  mkdirSync(dirname(reportPath), { recursive: true });\n  writeFileSync(reportPath, toJson(result));\n}\n\nexport interface RunOptions {\n  configPath: string;\n  /** Directory relative paths resolve against. Defaults to process.cwd(). */\n  cwd?: string;\n  scenarios?: ScenarioId[];\n  /** If set, the JSON report is written here too. */\n  reportPath?: string;\n}\n\n/**\n * Load a crash-lab config (.mjs/.js/.cjs, or .ts/.mts/.cts via jiti or Node type stripping).\n * Delegates to webhook-crash-lab so the CLI and the MCP server accept exactly the same files,\n * and re-reads the file each call so an agent re-running after edits gets the new config.\n */\nexport async function loadConfig(configPath: string, cwd = process.cwd()): Promise<CrashLabConfig> {\n  return loadLabConfig(configPath, cwd);\n}\n\nexport async function runFromConfig(opts: RunOptions): Promise<Summary> {\n  for (const id of opts.scenarios ?? []) {\n    if (!SCENARIO_IDS.includes(id)) {\n      throw new Error(`Unknown scenario \"${id}\". Known: ${SCENARIO_IDS.join(', ')}`);\n    }\n  }\n  const config = await loadConfig(opts.configPath, opts.cwd);\n  const result = await runCrashLab(\n    opts.scenarios?.length ? { ...config, scenarios: opts.scenarios } : config,\n  );\n  const reportPath = opts.reportPath && resolve(opts.cwd ?? process.cwd(), opts.reportPath);\n  if (reportPath) writeReport(result, reportPath);\n  return summarize(result, reportPath);\n}\n\nexport async function runDemo(mode: 'broken' | 'fixed'): Promise<Summary> {\n  return summarize(await runCrashLab(demoConfig(mode)));\n}\n\nfunction isReport(x: unknown): x is CrashLabResult {\n  const r = x as CrashLabResult;\n  return (\n    !!r &&\n    typeof r === 'object' &&\n    typeof r.ok === 'boolean' &&\n    Array.isArray(r.scenarios) &&\n    !!r.summary\n  );\n}\n\nexport function explainReport(input: {\n  reportPath?: string;\n  report?: unknown;\n  cwd?: string;\n}): Summary {\n  let report: unknown = input.report;\n  if (input.reportPath) {\n    const path = resolve(input.cwd ?? process.cwd(), input.reportPath);\n    if (!existsSync(path)) throw new Error(`Report not found: ${path}`);\n    report = readFileSync(path, 'utf8');\n  }\n  if (report === undefined)\n    throw new Error('Pass reportPath or report (the JSON from `webhook-crash-lab run --json`).');\n  if (typeof report === 'string') {\n    try {\n      report = JSON.parse(report);\n    } catch {\n      throw new Error('Report is not valid JSON.');\n    }\n  }\n  if (!isReport(report))\n    throw new Error(\n      'This is not a webhook-crash-lab JSON report (expected ok, summary, scenarios).',\n    );\n  return summarize(report, input.reportPath);\n}\n\nexport function listScenarios() {\n  return SCENARIOS.map(({ id, title, what, why, fix }) => ({ id, title, what, why, fix }));\n}\n\n/** Short human/agent-readable rendering of a summary. */\nexport function renderSummary(s: Summary): string {\n  const lines = [\n    `${s.ok ? 'PASS' : 'FAIL'} ${s.name}: ${s.summary.pass} pass, ${s.summary.fail} fail, ${s.summary.notTested} not tested`,\n  ];\n  for (const f of s.failures) {\n    lines.push('', `✗ ${f.id}: ${f.title}`);\n    for (const c of f.failedChecks) lines.push(`  ${c.name}: ${c.detail}`);\n    lines.push(`  why: ${f.why}`, `  fix: ${f.fix}`);\n  }\n  lines.push('', 'Next steps:', ...s.nextSteps.map((n) => `- ${n}`));\n  if (s.reportPath) lines.push(`Report written to ${s.reportPath}`);\n  return lines.join('\\n');\n}\n","import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { z } from 'zod';\nimport {\n  explainReport,\n  listScenarios,\n  renderSummary,\n  runDemo,\n  runFromConfig,\n  SCENARIO_IDS,\n  type Summary,\n} from './core.js';\n\nexport const VERSION = '0.2.0';\n\nconst summaryShape = {\n  name: z.string(),\n  ok: z.boolean(),\n  summary: z.object({ pass: z.number(), fail: z.number(), notTested: z.number() }),\n  failures: z.array(\n    z.object({\n      id: z.string(),\n      title: z.string(),\n      why: z.string(),\n      fix: z.string(),\n      failedChecks: z.array(z.object({ name: z.string(), detail: z.string() })),\n      responses: z.array(z.number()),\n    }),\n  ),\n  notTested: z.array(z.string()),\n  scenarios: z.array(z.object({ id: z.string(), status: z.string() })),\n  nextSteps: z.array(z.string()),\n  reportPath: z.string().optional(),\n};\n\nasync function respond(work: () => Promise<Summary> | Summary) {\n  try {\n    const s = await work();\n    return {\n      content: [{ type: 'text' as const, text: renderSummary(s) }],\n      structuredContent: s as unknown as Record<string, unknown>,\n    };\n  } catch (err) {\n    return { isError: true, content: [{ type: 'text' as const, text: (err as Error).message }] };\n  }\n}\n\nexport function createServer(): McpServer {\n  const server = new McpServer({ name: 'webhook-crash-lab', version: VERSION });\n\n  server.registerTool(\n    'run_crash_lab',\n    {\n      title: 'Run webhook-crash-lab',\n      description:\n        'Replay hostile webhook deliveries (duplicates, concurrent duplicates, out-of-order events, forged/missing/stale signatures, malformed JSON) against the handler described by a crash-lab config file, and return structured failures with fix hints. Use a TEST database and test secret only. Create a config with `npx webhook-crash-lab init` if none exists.',\n      inputSchema: {\n        configPath: z\n          .string()\n          .describe(\n            'Path to a crash-lab config (.mjs, .js, .cjs, .ts, .mts or .cts), relative to cwd',\n          ),\n        cwd: z\n          .string()\n          .optional()\n          .describe('Project directory; defaults to the server working directory'),\n        scenarios: z\n          .array(z.enum(SCENARIO_IDS as [string, ...string[]]))\n          .optional()\n          .describe('Run only these scenarios'),\n        reportPath: z.string().optional().describe('Also write the full JSON report here'),\n      },\n      outputSchema: summaryShape,\n      annotations: { readOnlyHint: false, openWorldHint: true },\n    },\n    (args) => respond(() => runFromConfig(args as Parameters<typeof runFromConfig>[0])),\n  );\n\n  server.registerTool(\n    'run_demo',\n    {\n      title: 'Run the built-in demo',\n      description:\n        'Run crash-lab against its built-in demo credits app. \"broken\" shows the typical AI-generated Stripe handler failing; \"fixed\" shows the same app done right. Needs no config. Use it to show what crash-lab checks before setting up a real config.',\n      inputSchema: { mode: z.enum(['broken', 'fixed']).default('broken') },\n      outputSchema: summaryShape,\n      annotations: { readOnlyHint: true, openWorldHint: false },\n    },\n    ({ mode }) => respond(() => runDemo(mode)),\n  );\n\n  server.registerTool(\n    'explain_report',\n    {\n      title: 'Explain a crash-lab report',\n      description:\n        'Read a JSON report produced by `webhook-crash-lab run --json <file>` (e.g. from CI) and return the failures in fix order, with why/fix hints and next steps.',\n      inputSchema: {\n        reportPath: z.string().optional(),\n        report: z\n          .union([z.string(), z.record(z.string(), z.unknown())])\n          .optional()\n          .describe('Report JSON, as text or object'),\n        cwd: z.string().optional(),\n      },\n      outputSchema: summaryShape,\n      annotations: { readOnlyHint: true, openWorldHint: false },\n    },\n    (args) => respond(() => explainReport(args)),\n  );\n\n  server.registerTool(\n    'list_scenarios',\n    {\n      title: 'List crash-lab scenarios',\n      description:\n        'List every scenario crash-lab can run, with what it sends, why it matters in production, and how to fix a failure.',\n      inputSchema: {},\n      outputSchema: {\n        scenarios: z.array(\n          z.object({\n            id: z.string(),\n            title: z.string(),\n            what: z.string(),\n            why: z.string(),\n            fix: z.string(),\n          }),\n        ),\n      },\n      annotations: { readOnlyHint: true, openWorldHint: false },\n    },\n    () => {\n      const scenarios = listScenarios();\n      return {\n        content: [\n          {\n            type: 'text',\n            text: scenarios.map((s) => `${s.id}: ${s.what}\\n  fix: ${s.fix}`).join('\\n'),\n          },\n        ],\n        structuredContent: { scenarios },\n      };\n    },\n  );\n\n  return server;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+import { ScenarioId, CrashLabConfig, CrashLabResult } from 'webhook-crash-lab';
+export { CrashLabResult, ScenarioId } from 'webhook-crash-lab';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+declare const SCENARIO_IDS: ScenarioId[];
+interface Failure {
+    id: ScenarioId;
+    title: string;
+    why: string;
+    fix: string;
+    failedChecks: {
+        name: string;
+        detail: string;
+    }[];
+    responses: number[];
+}
+interface Summary {
+    name: string;
+    ok: boolean;
+    summary: {
+        pass: number;
+        fail: number;
+        notTested: number;
+    };
+    /** Failing scenarios, most important first. */
+    failures: Failure[];
+    notTested: ScenarioId[];
+    scenarios: {
+        id: ScenarioId;
+        status: string;
+    }[];
+    nextSteps: string[];
+    reportPath?: string;
+}
+declare function summarize(result: CrashLabResult, reportPath?: string): Summary;
+interface RunOptions {
+    configPath: string;
+    /** Directory relative paths resolve against. Defaults to process.cwd(). */
+    cwd?: string;
+    scenarios?: ScenarioId[];
+    /** If set, the JSON report is written here too. */
+    reportPath?: string;
+}
+/**
+ * Load a crash-lab config (.mjs/.js/.cjs, or .ts/.mts/.cts via jiti or Node type stripping).
+ * Delegates to webhook-crash-lab so the CLI and the MCP server accept exactly the same files,
+ * and re-reads the file each call so an agent re-running after edits gets the new config.
+ */
+declare function loadConfig(configPath: string, cwd?: string): Promise<CrashLabConfig>;
+declare function runFromConfig(opts: RunOptions): Promise<Summary>;
+declare function runDemo(mode: 'broken' | 'fixed'): Promise<Summary>;
+declare function explainReport(input: {
+    reportPath?: string;
+    report?: unknown;
+    cwd?: string;
+}): Summary;
+declare function listScenarios(): {
+    id: ScenarioId;
+    title: string;
+    what: string;
+    why: string;
+    fix: string;
+}[];
+/** Short human/agent-readable rendering of a summary. */
+declare function renderSummary(s: Summary): string;
+
+declare const VERSION = "0.2.0";
+declare function createServer(): McpServer;
+
+export { type Failure, type RunOptions, SCENARIO_IDS, type Summary, VERSION, createServer, explainReport, listScenarios, loadConfig, renderSummary, runDemo, runFromConfig, summarize };

package/dist/index.js

@@ -0,0 +1,25 @@
+import {
+  SCENARIO_IDS,
+  VERSION,
+  createServer,
+  explainReport,
+  listScenarios,
+  loadConfig,
+  renderSummary,
+  runDemo,
+  runFromConfig,
+  summarize
+} from "./chunk-UR6UXUAN.js";
+export {
+  SCENARIO_IDS,
+  VERSION,
+  createServer,
+  explainReport,
+  listScenarios,
+  loadConfig,
+  renderSummary,
+  runDemo,
+  runFromConfig,
+  summarize
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/AGENTS-snippet.md

@@ -0,0 +1,10 @@
+<!-- Paste into AGENTS.md (Codex, Cursor, others) or CLAUDE.md. -->
+
+## Webhooks
+
+- Any change to a webhook handler must pass webhook-crash-lab before it is done:
+  `npx webhook-crash-lab run crash-lab.config.mjs --json crash-lab-report.json` (exit 0 = pass).
+  If the `webhook-crash-lab` MCP server is available, use its `run_crash_lab` tool instead.
+- On failure: fix the handler using each failure's `fix` hint, then re-run. Never edit the config or drop scenarios to make it pass.
+- Signature checks need the raw body (`express.raw()` / `await req.text()`). Dedupe on `event.id` before side effects. BullMQ jobs from webhooks use `jobId: event.id`.
+- Crash-lab configs must use a test database and test secrets only.

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "webhook-crash-lab-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server (plus Claude Code plugin and Codex skill) that lets coding agents run webhook-crash-lab, read structured failures with fix hints, and re-run until the webhook handler survives retries, duplicates and forged signatures.",
+  "license": "MIT",
+  "author": "Krrish Kumar (https://github.com/Krrishkumar125)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Krrishkumar125/webhook-crash-lab-mcp.git"
+  },
+  "homepage": "https://github.com/Krrishkumar125/webhook-crash-lab-mcp#readme",
+  "bugs": "https://github.com/Krrishkumar125/webhook-crash-lab-mcp/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "agent-skills",
+    "webhook",
+    "stripe",
+    "idempotency",
+    "testing"
+  ],
+  "type": "module",
+  "bin": {
+    "webhook-crash-lab-mcp": "dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin",
+    ".mcp.json",
+    ".agents",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check:exports": "publint && attw --pack . --profile esm-only",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "jiti": "^2.7.0",
+    "webhook-crash-lab": "^0.3.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^20.19.43",
+    "@vitest/coverage-v8": "^4.1.12",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9",
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^4.1.12"
+  }
+}

package/skills/webhook-crash-lab/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: webhook-crash-lab
+description: Test and fix webhook handlers (Stripe, GitHub) so they survive duplicate, concurrent and out-of-order deliveries and reject forged, missing or stale signatures. Use when writing, reviewing or debugging a webhook endpoint, after generating webhook code, or when a user reports double credits, double emails, "No signatures found matching the expected signature", or webhooks failing in production.
+---
+
+# webhook-crash-lab
+
+Webhook providers deliver events **at least once**: retries, duplicates, parallel copies, wrong order.
+webhook-crash-lab replays those deliveries against the real handler and checks both HTTP status and
+business state (for example "credits granted exactly once").
+
+## Loop
+
+1. **Find the handler** (`/webhook` route, `app/api/webhooks/*/route.ts`, `constructEvent` call).
+2. **Config.** If no `crash-lab.config.{mjs,js,ts}` exists, run `npx webhook-crash-lab init` and fill it in:
+   - `target`: the local dev URL of the webhook route, or an in-process `(req: Request) => Response` handler.
+   - `secret`: a **test** signing secret the handler verifies with (set it in the handler's env too).
+   - `event`: a realistic event (for example `checkout.session.completed`).
+   - `adapter` (`reset` / `snapshot`) + `expect.once`: needed for the duplicate scenarios. Point it at a
+     **test database only**, because `reset()` wipes state before every scenario.
+   - `sequence`: real event order, for the out-of-order scenario.
+3. **Run.** Call the `run_crash_lab` MCP tool with `{ configPath, cwd }`. Without the MCP server, use
+   `npx webhook-crash-lab run crash-lab.config.mjs --json crash-lab-report.json`, then
+   `explain_report` or read the JSON. Exit codes: 0 pass, 1 failures, 2 config error.
+4. **Fix the handler**, one failure at a time, in the order returned (signature → body → duplicates → ordering).
+   Use each failure's `fix` hint. Typical fixes:
+   - raw body for signature checks (`express.raw()`, `await req.text()`), never `express.json()` first;
+   - a unique insert on `event.id` (processed-events table) **before** side effects, in the same transaction;
+   - BullMQ `queue.add(name, data, { jobId: event.id })`;
+   - ignore events older than the latest one already applied for that object.
+5. **Re-run** the same tool with the same arguments. Repeat until `ok` is `true`. Do not weaken the config
+   or remove scenarios to make it pass.
+6. Suggest adding `npx webhook-crash-lab run` to CI, and the ESLint plugins
+   `eslint-plugin-webhook-safety` / `eslint-plugin-bullmq` for the static versions of these checks.
+
+## Rules
+
+- Never point crash-lab at production URLs, production databases or live secrets.
+- `not-tested` means the config lacks what that scenario needs (adapter / expect.once / sequence). Say so; do not report it as passing.
+- `run_demo` (no config needed) shows a broken vs fixed app if the user wants to see what is checked.