@webhooks-cc/mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,100 @@
+# @webhooks-cc/mcp
+
+MCP server for [webhooks.cc](https://webhooks.cc). Connects AI coding agents to webhook endpoints — create, inspect, test, and replay webhooks through natural language.
+
+Works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop.
+
+## Install
+
+### One-click
+
+- **Cursor**: [Add to Cursor](https://cursor.com/en/install-mcp?name=webhooks-cc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZWJob29rcy1jYy9tY3AiXSwiZW52Ijp7IldIS19BUElfS0VZIjoid2hjY18uLi4ifX0=) (paste your API key after install)
+- **VS Code**: [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=webhooks-cc&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40webhooks-cc%2Fmcp%22%5D%2C%22env%22%3A%7B%22WHK_API_KEY%22%3A%22%24%7Binput%3Awhk_api_key%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22whk_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22webhooks.cc%20API%20key%20%28get%20yours%20at%20webhooks.cc%2Faccount%29%22%2C%22password%22%3Atrue%7D%5D) (prompts for your key)
+
+### CLI
+
+```bash
+# Claude Code
+claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
+
+# Cursor
+npx @webhooks-cc/mcp setup cursor --api-key whcc_...
+
+# VS Code
+npx @webhooks-cc/mcp setup vscode --api-key whcc_...
+
+# OpenAI Codex
+codex mcp add webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
+
+# Windsurf
+npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
+
+# Claude Desktop
+npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
+```
+
+### Manual JSON config
+
+For any tool that reads an MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "webhooks-cc": {
+      "command": "npx",
+      "args": ["-y", "@webhooks-cc/mcp"],
+      "env": {
+        "WHK_API_KEY": "whcc_..."
+      }
+    }
+  }
+}
+```
+
+Get your API key at [webhooks.cc/account](https://webhooks.cc/account).
+
+## Tools
+
+The MCP server exposes 11 tools:
+
+| Tool               | Description                               |
+| ------------------ | ----------------------------------------- |
+| `create_endpoint`  | Create a new webhook endpoint             |
+| `list_endpoints`   | List all your endpoints                   |
+| `get_endpoint`     | Get details for an endpoint by slug       |
+| `update_endpoint`  | Update an endpoint name or mock response  |
+| `delete_endpoint`  | Delete an endpoint and its requests       |
+| `list_requests`    | List captured requests for an endpoint    |
+| `get_request`      | Get full details of a captured request    |
+| `send_webhook`     | Send a test webhook to an endpoint        |
+| `wait_for_request` | Wait for an incoming request (polling)    |
+| `replay_request`   | Replay a captured request to a target URL |
+| `describe`         | Describe all available SDK operations     |
+
+## Example conversation
+
+```
+You: "Create a webhook endpoint for testing Stripe"
+Agent: Created endpoint "stripe-test" at https://go.webhooks.cc/w/abc123
+
+You: "Set it to return 201 with {"received": true}"
+Agent: Updated mock response for stripe-test
+
+You: "Send a test POST with a checkout.session.completed event"
+Agent: Sent POST to stripe-test with event payload
+
+You: "Show me what was captured"
+Agent: 1 request captured:
+  POST /w/abc123 — {"event": "checkout.session.completed", ...}
+
+You: "Replay that to my local server"
+Agent: Replayed to http://localhost:3000/webhooks — got 200 OK
+```
+
+## Documentation
+
+Full setup guide with interactive API key filling: [webhooks.cc/docs/mcp](https://webhooks.cc/docs/mcp)
+
+## License
+
+MIT

package/dist/bin/mcp.js

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+"use strict";
+
+// bin/mcp.ts
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+
+// src/index.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_sdk = require("@webhooks-cc/sdk");
+
+// src/tools.ts
+var import_zod = require("zod");
+var MAX_BODY_SIZE = 32768;
+function textContent(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function readBodyTruncated(response, limit = MAX_BODY_SIZE) {
+  const text = await response.text();
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + `
+... [truncated, ${text.length} chars total]`;
+}
+function withErrorHandling(handler) {
+  return async (args2) => {
+    try {
+      return await handler(args2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { ...textContent(`Error: ${message}`), isError: true };
+    }
+  };
+}
+function registerTools(server, client) {
+  server.tool(
+    "create_endpoint",
+    "Create a new webhook endpoint. Returns the endpoint URL and slug.",
+    { name: import_zod.z.string().optional().describe("Display name for the endpoint") },
+    withErrorHandling(async ({ name }) => {
+      const endpoint = await client.endpoints.create({ name });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "list_endpoints",
+    "List all webhook endpoints for the authenticated user. Returns an array of endpoints with their slugs, names, and URLs.",
+    {},
+    withErrorHandling(async () => {
+      const endpoints = await client.endpoints.list();
+      return textContent(JSON.stringify(endpoints, null, 2));
+    })
+  );
+  server.tool(
+    "get_endpoint",
+    "Get details for a specific webhook endpoint by its slug.",
+    { slug: import_zod.z.string().describe("The endpoint slug (from the URL)") },
+    withErrorHandling(async ({ slug }) => {
+      const endpoint = await client.endpoints.get(slug);
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "update_endpoint",
+    "Update an endpoint's name or mock response configuration.",
+    {
+      slug: import_zod.z.string().describe("The endpoint slug to update"),
+      name: import_zod.z.string().optional().describe("New display name"),
+      mockResponse: import_zod.z.object({
+        status: import_zod.z.number().min(100).max(599).describe("HTTP status code (100-599)"),
+        body: import_zod.z.string().default("").describe("Response body string (default: empty)"),
+        headers: import_zod.z.record(import_zod.z.string()).default({}).describe("Response headers (default: none)")
+      }).nullable().optional().describe("Mock response config, or null to clear it")
+    },
+    withErrorHandling(async ({ slug, name, mockResponse }) => {
+      const endpoint = await client.endpoints.update(slug, { name, mockResponse });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "delete_endpoint",
+    "Delete a webhook endpoint and all its captured requests.",
+    { slug: import_zod.z.string().describe("The endpoint slug to delete") },
+    withErrorHandling(async ({ slug }) => {
+      await client.endpoints.delete(slug);
+      return textContent(`Endpoint "${slug}" deleted.`);
+    })
+  );
+  server.tool(
+    "send_webhook",
+    "Send a test webhook to an endpoint. Useful for testing webhook handling code.",
+    {
+      slug: import_zod.z.string().describe("The endpoint slug to send to"),
+      method: import_zod.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).default("POST").describe("HTTP method (default: POST)"),
+      headers: import_zod.z.record(import_zod.z.string()).optional().describe("HTTP headers to include"),
+      body: import_zod.z.unknown().optional().describe("Request body (will be JSON-serialized)")
+    },
+    withErrorHandling(async ({ slug, method, headers, body }) => {
+      const response = await client.endpoints.send(slug, { method, headers, body });
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "list_requests",
+    "List captured webhook requests for an endpoint. Returns the most recent requests (default: 25).",
+    {
+      endpointSlug: import_zod.z.string().describe("The endpoint slug"),
+      limit: import_zod.z.number().default(25).describe("Max number of requests to return (default: 25)"),
+      since: import_zod.z.number().optional().describe("Only return requests after this timestamp (ms)")
+    },
+    withErrorHandling(async ({ endpointSlug, limit, since }) => {
+      const requests = await client.requests.list(endpointSlug, { limit, since });
+      return textContent(JSON.stringify(requests, null, 2));
+    })
+  );
+  server.tool(
+    "get_request",
+    "Get full details of a specific captured webhook request by its ID. Includes method, headers, body, path, and timestamp.",
+    { requestId: import_zod.z.string().describe("The request ID") },
+    withErrorHandling(async ({ requestId }) => {
+      const request = await client.requests.get(requestId);
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "wait_for_request",
+    "Wait for a webhook request to arrive at an endpoint. Polls until a request is captured or timeout expires. Use this after sending a webhook to verify it was received.",
+    {
+      endpointSlug: import_zod.z.string().describe("The endpoint slug to monitor"),
+      timeout: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).default("30s").describe('How long to wait (e.g. "30s", "5m", or milliseconds as number)'),
+      pollInterval: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).optional().describe('Interval between polls (e.g. "1s", "500", or milliseconds). Default: 500ms')
+    },
+    withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
+      const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "replay_request",
+    "Replay a previously captured webhook request to a target URL. Sends the original method, headers, and body to the specified URL. Only use with URLs you trust \u2014 the original request data is forwarded.",
+    {
+      requestId: import_zod.z.string().describe("The ID of the captured request to replay"),
+      targetUrl: import_zod.z.string().url().refine(
+        (u) => {
+          try {
+            const p = new URL(u).protocol;
+            return p === "http:" || p === "https:";
+          } catch {
+            return false;
+          }
+        },
+        { message: "Only http and https URLs are supported" }
+      ).describe("The URL to send the replayed request to (http or https only)")
+    },
+    withErrorHandling(async ({ requestId, targetUrl }) => {
+      const response = await client.requests.replay(requestId, targetUrl);
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "describe",
+    "Describe all available SDK operations, their parameters, and types. Useful for discovering what actions are possible.",
+    {},
+    withErrorHandling(async () => {
+      const description = client.describe();
+      return textContent(JSON.stringify(description, null, 2));
+    })
+  );
+}
+
+// src/index.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+function createServer(options = {}) {
+  const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+  }
+  const client = new import_sdk.WebhooksCC({
+    apiKey,
+    webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
+    baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
+  });
+  const server = new import_mcp.McpServer({
+    name: "webhooks-cc",
+    version: VERSION
+  });
+  registerTools(server, client);
+  return server;
+}
+
+// src/setup.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_child_process = require("child_process");
+var import_os = require("os");
+var TOOLS = ["claude-code", "claude-desktop", "cursor", "vscode", "codex", "windsurf"];
+var API_KEY_REGEX = /^whcc_[a-zA-Z0-9_-]+$/;
+function validateApiKeyFormat(key) {
+  if (!API_KEY_REGEX.test(key)) {
+    console.error("Error: Invalid API key format. Keys must start with 'whcc_' and contain only");
+    console.error("alphanumeric characters, hyphens, and underscores.");
+    process.exit(1);
+  }
+}
+function mcpServerConfig(apiKey) {
+  return {
+    command: "npx",
+    args: ["-y", "@webhooks-cc/mcp"],
+    env: { WHK_API_KEY: apiKey }
+  };
+}
+function resolveApiKey(flags) {
+  return flags["api-key"] ?? process.env.WHK_API_KEY ?? null;
+}
+function mergeJsonConfig(filePath, serverName, serverConfig) {
+  let existing = {};
+  if ((0, import_fs.existsSync)(filePath)) {
+    try {
+      existing = JSON.parse((0, import_fs.readFileSync)(filePath, "utf-8"));
+    } catch {
+      console.warn(`Warning: ${filePath} contains invalid JSON and will be overwritten.`);
+      console.warn(`A backup has been saved to ${filePath}.bak`);
+      (0, import_fs.copyFileSync)(filePath, `${filePath}.bak`);
+    }
+  }
+  const mcpServers = existing.mcpServers ?? {};
+  mcpServers[serverName] = serverConfig;
+  existing.mcpServers = mcpServers;
+  const dir = (0, import_path.dirname)(filePath);
+  if (!(0, import_fs.existsSync)(dir)) (0, import_fs.mkdirSync)(dir, { recursive: true });
+  (0, import_fs.writeFileSync)(filePath, JSON.stringify(existing, null, 2) + "\n");
+}
+function getClaudeDesktopConfigPath() {
+  const os = (0, import_os.platform)();
+  if (os === "darwin") {
+    return (0, import_path.join)(
+      (0, import_os.homedir)(),
+      "Library",
+      "Application Support",
+      "Claude",
+      "claude_desktop_config.json"
+    );
+  }
+  if (os === "win32") {
+    return (0, import_path.join)(
+      process.env.APPDATA ?? (0, import_path.join)((0, import_os.homedir)(), "AppData", "Roaming"),
+      "Claude",
+      "claude_desktop_config.json"
+    );
+  }
+  return (0, import_path.join)((0, import_os.homedir)(), ".config", "Claude", "claude_desktop_config.json");
+}
+function setupClaudeCode(apiKey) {
+  try {
+    (0, import_child_process.execFileSync)(
+      "claude",
+      [
+        "mcp",
+        "add",
+        "-s",
+        "user",
+        "--transport",
+        "stdio",
+        "webhooks-cc",
+        "-e",
+        `WHK_API_KEY=${apiKey}`,
+        "--",
+        "npx",
+        "-y",
+        "@webhooks-cc/mcp"
+      ],
+      { stdio: "inherit" }
+    );
+    console.log("\nDone! webhooks-cc MCP server added to Claude Code (user scope).");
+    console.log("It will be available in all your Claude Code sessions.");
+  } catch {
+    console.error("\nFailed to run 'claude mcp add'. Is Claude Code CLI installed?");
+    console.error("Install it: npm install -g @anthropic-ai/claude-code");
+    console.error("\nManual alternative \u2014 run this command:");
+    console.error(
+      `  claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=<your-key> -- npx -y @webhooks-cc/mcp`
+    );
+    process.exit(1);
+  }
+}
+function setupClaudeDesktop(apiKey) {
+  const configPath = getClaudeDesktopConfigPath();
+  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  console.log(`Done! Config written to ${configPath}`);
+  console.log("Restart Claude Desktop for changes to take effect.");
+}
+function setupCursor(apiKey) {
+  const configPath = (0, import_path.join)(process.cwd(), ".cursor", "mcp.json");
+  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  console.log(`Done! Config written to ${configPath}`);
+  console.log("Restart Cursor or reload the window for changes to take effect.");
+}
+function setupVSCode(apiKey) {
+  const configPath = (0, import_path.join)(process.cwd(), ".vscode", "mcp.json");
+  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  console.log(`Done! Config written to ${configPath}`);
+  console.log("Reload VS Code window for changes to take effect.");
+}
+function setupCodex(apiKey) {
+  try {
+    (0, import_child_process.execFileSync)(
+      "codex",
+      [
+        "mcp",
+        "add",
+        "webhooks-cc",
+        "-e",
+        `WHK_API_KEY=${apiKey}`,
+        "--",
+        "npx",
+        "-y",
+        "@webhooks-cc/mcp"
+      ],
+      { stdio: "inherit" }
+    );
+    console.log("\nDone! webhooks-cc MCP server added to Codex.");
+  } catch {
+    console.error("\nFailed to run 'codex mcp add'. Is OpenAI Codex CLI installed?");
+    console.error("\nManual alternative \u2014 add to ~/.codex/config.toml:");
+    console.error(`
+[mcp.webhooks-cc]
+command = "npx"
+args = ["-y", "@webhooks-cc/mcp"]
+
+[mcp.webhooks-cc.env]
+WHK_API_KEY = "<your-key>"
+`);
+    process.exit(1);
+  }
+}
+function setupWindsurf(apiKey) {
+  const configPath = (0, import_path.join)((0, import_os.homedir)(), ".codeium", "windsurf", "mcp_config.json");
+  mergeJsonConfig(configPath, "webhooks-cc", mcpServerConfig(apiKey));
+  console.log(`Done! Config written to ${configPath}`);
+  console.log("Restart Windsurf for changes to take effect.");
+}
+function printUsage() {
+  console.log(`
+@webhooks-cc/mcp setup \u2014 Configure the MCP server for your AI tool
+
+Usage:
+  npx @webhooks-cc/mcp setup <tool> [--api-key <key>]
+
+Tools:
+  claude-code      Claude Code CLI (runs 'claude mcp add')
+  claude-desktop   Claude Desktop app
+  cursor           Cursor editor (writes .cursor/mcp.json)
+  vscode           VS Code Copilot (writes .vscode/mcp.json)
+  codex            OpenAI Codex CLI (runs 'codex mcp add')
+  windsurf         Windsurf editor
+
+Options:
+  --api-key <key>  Your webhooks.cc API key (or set WHK_API_KEY env var)
+
+Examples:
+  npx @webhooks-cc/mcp setup claude-code --api-key whcc_abc123
+  WHK_API_KEY=whcc_abc123 npx @webhooks-cc/mcp setup cursor
+  npx @webhooks-cc/mcp setup vscode --api-key whcc_abc123
+`);
+}
+function runSetup(args2) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args2.length; i++) {
+    if (args2[i] === "--api-key" && i + 1 < args2.length) {
+      flags["api-key"] = args2[++i];
+    } else if (args2[i].startsWith("--api-key=")) {
+      flags["api-key"] = args2[i].slice("--api-key=".length);
+    } else if (!args2[i].startsWith("-")) {
+      positional.push(args2[i]);
+    }
+  }
+  const tool = positional[0];
+  if (!tool || !TOOLS.includes(tool)) {
+    printUsage();
+    if (tool) {
+      console.error(`Unknown tool: "${tool}"
+`);
+    }
+    process.exit(tool ? 1 : 0);
+  }
+  const apiKey = resolveApiKey(flags);
+  if (!apiKey) {
+    console.error("Error: API key required. Pass --api-key or set WHK_API_KEY env var.");
+    console.error("Get your API key at https://webhooks.cc/account\n");
+    process.exit(1);
+  }
+  validateApiKeyFormat(apiKey);
+  console.log(`Setting up webhooks-cc MCP server for ${tool}...
+`);
+  switch (tool) {
+    case "claude-code":
+      setupClaudeCode(apiKey);
+      break;
+    case "claude-desktop":
+      setupClaudeDesktop(apiKey);
+      break;
+    case "cursor":
+      setupCursor(apiKey);
+      break;
+    case "vscode":
+      setupVSCode(apiKey);
+      break;
+    case "codex":
+      setupCodex(apiKey);
+      break;
+    case "windsurf":
+      setupWindsurf(apiKey);
+      break;
+  }
+}
+
+// bin/mcp.ts
+var args = process.argv.slice(2);
+var command = args[0];
+if (command === "setup") {
+  runSetup(args.slice(1));
+} else if (command === "--help" || command === "-h") {
+  console.log(`
+@webhooks-cc/mcp \u2014 MCP server for webhooks.cc
+
+Usage:
+  npx @webhooks-cc/mcp                    Start stdio MCP server
+  npx @webhooks-cc/mcp setup <tool>       Configure for an AI tool
+  npx @webhooks-cc/mcp --help             Show this help
+
+Environment:
+  WHK_API_KEY        Your webhooks.cc API key (required)
+  WHK_WEBHOOK_URL    Custom webhook receiver URL (optional)
+  WHK_BASE_URL       Custom API base URL (optional)
+
+Setup:
+  npx @webhooks-cc/mcp setup claude-code --api-key whcc_...
+  npx @webhooks-cc/mcp setup cursor --api-key whcc_...
+  npx @webhooks-cc/mcp setup vscode --api-key whcc_...
+  npx @webhooks-cc/mcp setup codex --api-key whcc_...
+  npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
+  npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
+
+Get your API key at https://webhooks.cc/account
+`);
+} else if (command && command !== "--") {
+  console.error(`Unknown command: "${command}". Run with --help for usage.`);
+  process.exit(1);
+} else {
+  const server = createServer();
+  const transport = new import_stdio.StdioServerTransport();
+  server.connect(transport).catch((error) => {
+    console.error("Fatal:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  });
+}

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebhooksCC } from '@webhooks-cc/sdk';
+
+/** Register all 11 webhook tools on an MCP server instance. */
+declare function registerTools(server: McpServer, client: WebhooksCC): void;
+
+interface CreateServerOptions {
+    /** API key for webhooks.cc (default: reads WHK_API_KEY env var) */
+    apiKey?: string;
+    /** Custom webhook receiver URL (default: reads WHK_WEBHOOK_URL or https://go.webhooks.cc) */
+    webhookUrl?: string;
+    /** Custom API base URL (default: https://webhooks.cc) */
+    baseUrl?: string;
+}
+/**
+ * Create an MCP server with all webhooks.cc tools registered.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from "@webhooks-cc/mcp";
+ * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ * const server = createServer({ apiKey: "whcc_..." });
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+declare function createServer(options?: CreateServerOptions): McpServer;
+
+export { type CreateServerOptions, createServer, registerTools };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebhooksCC } from '@webhooks-cc/sdk';
+
+/** Register all 11 webhook tools on an MCP server instance. */
+declare function registerTools(server: McpServer, client: WebhooksCC): void;
+
+interface CreateServerOptions {
+    /** API key for webhooks.cc (default: reads WHK_API_KEY env var) */
+    apiKey?: string;
+    /** Custom webhook receiver URL (default: reads WHK_WEBHOOK_URL or https://go.webhooks.cc) */
+    webhookUrl?: string;
+    /** Custom API base URL (default: https://webhooks.cc) */
+    baseUrl?: string;
+}
+/**
+ * Create an MCP server with all webhooks.cc tools registered.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from "@webhooks-cc/mcp";
+ * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ * const server = createServer({ apiKey: "whcc_..." });
+ * await server.connect(new StdioServerTransport());
+ * ```
+ */
+declare function createServer(options?: CreateServerOptions): McpServer;
+
+export { type CreateServerOptions, createServer, registerTools };

package/dist/index.js

@@ -0,0 +1,225 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createServer: () => createServer,
+  registerTools: () => registerTools
+});
+module.exports = __toCommonJS(index_exports);
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_sdk = require("@webhooks-cc/sdk");
+
+// src/tools.ts
+var import_zod = require("zod");
+var MAX_BODY_SIZE = 32768;
+function textContent(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function readBodyTruncated(response, limit = MAX_BODY_SIZE) {
+  const text = await response.text();
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + `
+... [truncated, ${text.length} chars total]`;
+}
+function withErrorHandling(handler) {
+  return async (args) => {
+    try {
+      return await handler(args);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { ...textContent(`Error: ${message}`), isError: true };
+    }
+  };
+}
+function registerTools(server, client) {
+  server.tool(
+    "create_endpoint",
+    "Create a new webhook endpoint. Returns the endpoint URL and slug.",
+    { name: import_zod.z.string().optional().describe("Display name for the endpoint") },
+    withErrorHandling(async ({ name }) => {
+      const endpoint = await client.endpoints.create({ name });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "list_endpoints",
+    "List all webhook endpoints for the authenticated user. Returns an array of endpoints with their slugs, names, and URLs.",
+    {},
+    withErrorHandling(async () => {
+      const endpoints = await client.endpoints.list();
+      return textContent(JSON.stringify(endpoints, null, 2));
+    })
+  );
+  server.tool(
+    "get_endpoint",
+    "Get details for a specific webhook endpoint by its slug.",
+    { slug: import_zod.z.string().describe("The endpoint slug (from the URL)") },
+    withErrorHandling(async ({ slug }) => {
+      const endpoint = await client.endpoints.get(slug);
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "update_endpoint",
+    "Update an endpoint's name or mock response configuration.",
+    {
+      slug: import_zod.z.string().describe("The endpoint slug to update"),
+      name: import_zod.z.string().optional().describe("New display name"),
+      mockResponse: import_zod.z.object({
+        status: import_zod.z.number().min(100).max(599).describe("HTTP status code (100-599)"),
+        body: import_zod.z.string().default("").describe("Response body string (default: empty)"),
+        headers: import_zod.z.record(import_zod.z.string()).default({}).describe("Response headers (default: none)")
+      }).nullable().optional().describe("Mock response config, or null to clear it")
+    },
+    withErrorHandling(async ({ slug, name, mockResponse }) => {
+      const endpoint = await client.endpoints.update(slug, { name, mockResponse });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "delete_endpoint",
+    "Delete a webhook endpoint and all its captured requests.",
+    { slug: import_zod.z.string().describe("The endpoint slug to delete") },
+    withErrorHandling(async ({ slug }) => {
+      await client.endpoints.delete(slug);
+      return textContent(`Endpoint "${slug}" deleted.`);
+    })
+  );
+  server.tool(
+    "send_webhook",
+    "Send a test webhook to an endpoint. Useful for testing webhook handling code.",
+    {
+      slug: import_zod.z.string().describe("The endpoint slug to send to"),
+      method: import_zod.z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).default("POST").describe("HTTP method (default: POST)"),
+      headers: import_zod.z.record(import_zod.z.string()).optional().describe("HTTP headers to include"),
+      body: import_zod.z.unknown().optional().describe("Request body (will be JSON-serialized)")
+    },
+    withErrorHandling(async ({ slug, method, headers, body }) => {
+      const response = await client.endpoints.send(slug, { method, headers, body });
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "list_requests",
+    "List captured webhook requests for an endpoint. Returns the most recent requests (default: 25).",
+    {
+      endpointSlug: import_zod.z.string().describe("The endpoint slug"),
+      limit: import_zod.z.number().default(25).describe("Max number of requests to return (default: 25)"),
+      since: import_zod.z.number().optional().describe("Only return requests after this timestamp (ms)")
+    },
+    withErrorHandling(async ({ endpointSlug, limit, since }) => {
+      const requests = await client.requests.list(endpointSlug, { limit, since });
+      return textContent(JSON.stringify(requests, null, 2));
+    })
+  );
+  server.tool(
+    "get_request",
+    "Get full details of a specific captured webhook request by its ID. Includes method, headers, body, path, and timestamp.",
+    { requestId: import_zod.z.string().describe("The request ID") },
+    withErrorHandling(async ({ requestId }) => {
+      const request = await client.requests.get(requestId);
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "wait_for_request",
+    "Wait for a webhook request to arrive at an endpoint. Polls until a request is captured or timeout expires. Use this after sending a webhook to verify it was received.",
+    {
+      endpointSlug: import_zod.z.string().describe("The endpoint slug to monitor"),
+      timeout: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).default("30s").describe('How long to wait (e.g. "30s", "5m", or milliseconds as number)'),
+      pollInterval: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).optional().describe('Interval between polls (e.g. "1s", "500", or milliseconds). Default: 500ms')
+    },
+    withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
+      const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "replay_request",
+    "Replay a previously captured webhook request to a target URL. Sends the original method, headers, and body to the specified URL. Only use with URLs you trust \u2014 the original request data is forwarded.",
+    {
+      requestId: import_zod.z.string().describe("The ID of the captured request to replay"),
+      targetUrl: import_zod.z.string().url().refine(
+        (u) => {
+          try {
+            const p = new URL(u).protocol;
+            return p === "http:" || p === "https:";
+          } catch {
+            return false;
+          }
+        },
+        { message: "Only http and https URLs are supported" }
+      ).describe("The URL to send the replayed request to (http or https only)")
+    },
+    withErrorHandling(async ({ requestId, targetUrl }) => {
+      const response = await client.requests.replay(requestId, targetUrl);
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "describe",
+    "Describe all available SDK operations, their parameters, and types. Useful for discovering what actions are possible.",
+    {},
+    withErrorHandling(async () => {
+      const description = client.describe();
+      return textContent(JSON.stringify(description, null, 2));
+    })
+  );
+}
+
+// src/index.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+function createServer(options = {}) {
+  const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+  }
+  const client = new import_sdk.WebhooksCC({
+    apiKey,
+    webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
+    baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
+  });
+  const server = new import_mcp.McpServer({
+    name: "webhooks-cc",
+    version: VERSION
+  });
+  registerTools(server, client);
+  return server;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createServer,
+  registerTools
+});

package/dist/index.mjs

@@ -0,0 +1,199 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebhooksCC } from "@webhooks-cc/sdk";
+
+// src/tools.ts
+import { z } from "zod";
+var MAX_BODY_SIZE = 32768;
+function textContent(text) {
+  return { content: [{ type: "text", text }] };
+}
+async function readBodyTruncated(response, limit = MAX_BODY_SIZE) {
+  const text = await response.text();
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + `
+... [truncated, ${text.length} chars total]`;
+}
+function withErrorHandling(handler) {
+  return async (args) => {
+    try {
+      return await handler(args);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return { ...textContent(`Error: ${message}`), isError: true };
+    }
+  };
+}
+function registerTools(server, client) {
+  server.tool(
+    "create_endpoint",
+    "Create a new webhook endpoint. Returns the endpoint URL and slug.",
+    { name: z.string().optional().describe("Display name for the endpoint") },
+    withErrorHandling(async ({ name }) => {
+      const endpoint = await client.endpoints.create({ name });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "list_endpoints",
+    "List all webhook endpoints for the authenticated user. Returns an array of endpoints with their slugs, names, and URLs.",
+    {},
+    withErrorHandling(async () => {
+      const endpoints = await client.endpoints.list();
+      return textContent(JSON.stringify(endpoints, null, 2));
+    })
+  );
+  server.tool(
+    "get_endpoint",
+    "Get details for a specific webhook endpoint by its slug.",
+    { slug: z.string().describe("The endpoint slug (from the URL)") },
+    withErrorHandling(async ({ slug }) => {
+      const endpoint = await client.endpoints.get(slug);
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "update_endpoint",
+    "Update an endpoint's name or mock response configuration.",
+    {
+      slug: z.string().describe("The endpoint slug to update"),
+      name: z.string().optional().describe("New display name"),
+      mockResponse: z.object({
+        status: z.number().min(100).max(599).describe("HTTP status code (100-599)"),
+        body: z.string().default("").describe("Response body string (default: empty)"),
+        headers: z.record(z.string()).default({}).describe("Response headers (default: none)")
+      }).nullable().optional().describe("Mock response config, or null to clear it")
+    },
+    withErrorHandling(async ({ slug, name, mockResponse }) => {
+      const endpoint = await client.endpoints.update(slug, { name, mockResponse });
+      return textContent(JSON.stringify(endpoint, null, 2));
+    })
+  );
+  server.tool(
+    "delete_endpoint",
+    "Delete a webhook endpoint and all its captured requests.",
+    { slug: z.string().describe("The endpoint slug to delete") },
+    withErrorHandling(async ({ slug }) => {
+      await client.endpoints.delete(slug);
+      return textContent(`Endpoint "${slug}" deleted.`);
+    })
+  );
+  server.tool(
+    "send_webhook",
+    "Send a test webhook to an endpoint. Useful for testing webhook handling code.",
+    {
+      slug: z.string().describe("The endpoint slug to send to"),
+      method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).default("POST").describe("HTTP method (default: POST)"),
+      headers: z.record(z.string()).optional().describe("HTTP headers to include"),
+      body: z.unknown().optional().describe("Request body (will be JSON-serialized)")
+    },
+    withErrorHandling(async ({ slug, method, headers, body }) => {
+      const response = await client.endpoints.send(slug, { method, headers, body });
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "list_requests",
+    "List captured webhook requests for an endpoint. Returns the most recent requests (default: 25).",
+    {
+      endpointSlug: z.string().describe("The endpoint slug"),
+      limit: z.number().default(25).describe("Max number of requests to return (default: 25)"),
+      since: z.number().optional().describe("Only return requests after this timestamp (ms)")
+    },
+    withErrorHandling(async ({ endpointSlug, limit, since }) => {
+      const requests = await client.requests.list(endpointSlug, { limit, since });
+      return textContent(JSON.stringify(requests, null, 2));
+    })
+  );
+  server.tool(
+    "get_request",
+    "Get full details of a specific captured webhook request by its ID. Includes method, headers, body, path, and timestamp.",
+    { requestId: z.string().describe("The request ID") },
+    withErrorHandling(async ({ requestId }) => {
+      const request = await client.requests.get(requestId);
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "wait_for_request",
+    "Wait for a webhook request to arrive at an endpoint. Polls until a request is captured or timeout expires. Use this after sending a webhook to verify it was received.",
+    {
+      endpointSlug: z.string().describe("The endpoint slug to monitor"),
+      timeout: z.union([z.string(), z.number()]).default("30s").describe('How long to wait (e.g. "30s", "5m", or milliseconds as number)'),
+      pollInterval: z.union([z.string(), z.number()]).optional().describe('Interval between polls (e.g. "1s", "500", or milliseconds). Default: 500ms')
+    },
+    withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
+      const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
+      return textContent(JSON.stringify(request, null, 2));
+    })
+  );
+  server.tool(
+    "replay_request",
+    "Replay a previously captured webhook request to a target URL. Sends the original method, headers, and body to the specified URL. Only use with URLs you trust \u2014 the original request data is forwarded.",
+    {
+      requestId: z.string().describe("The ID of the captured request to replay"),
+      targetUrl: z.string().url().refine(
+        (u) => {
+          try {
+            const p = new URL(u).protocol;
+            return p === "http:" || p === "https:";
+          } catch {
+            return false;
+          }
+        },
+        { message: "Only http and https URLs are supported" }
+      ).describe("The URL to send the replayed request to (http or https only)")
+    },
+    withErrorHandling(async ({ requestId, targetUrl }) => {
+      const response = await client.requests.replay(requestId, targetUrl);
+      const responseBody = await readBodyTruncated(response);
+      return textContent(
+        JSON.stringify(
+          { status: response.status, statusText: response.statusText, body: responseBody },
+          null,
+          2
+        )
+      );
+    })
+  );
+  server.tool(
+    "describe",
+    "Describe all available SDK operations, their parameters, and types. Useful for discovering what actions are possible.",
+    {},
+    withErrorHandling(async () => {
+      const description = client.describe();
+      return textContent(JSON.stringify(description, null, 2));
+    })
+  );
+}
+
+// src/index.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+function createServer(options = {}) {
+  const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
+  if (!apiKey) {
+    throw new Error("Missing API key. Set WHK_API_KEY environment variable or pass apiKey option.");
+  }
+  const client = new WebhooksCC({
+    apiKey,
+    webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
+    baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
+  });
+  const server = new McpServer({
+    name: "webhooks-cc",
+    version: VERSION
+  });
+  registerTools(server, client);
+  return server;
+}
+export {
+  createServer,
+  registerTools
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@webhooks-cc/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for webhooks.cc — AI agent integration for webhook testing",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "webhooks-cc-mcp": "dist/bin/mcp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "webhook",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "webhooks-cc"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webhooks-cc/webhooks-cc",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://webhooks.cc",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.0",
+    "@webhooks-cc/sdk": "0.3.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}