@webhooks-cc/mcp 0.3.0 → 1.0.0

package/dist/index.mjs

@@ -1,97 +1,591 @@
 // src/index.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebhooksCC } from "@webhooks-cc/sdk";
 
-// src/tools.ts
+// src/prompts.ts
 import { z } from "zod";
+function registerPrompts(server) {
+  server.registerPrompt(
+    "debug_webhook_delivery",
+    {
+      title: "Debug Webhook Delivery",
+      description: "Guide an agent through diagnosing why webhook delivery is failing or missing.",
+      argsSchema: {
+        provider: z.string().optional().describe("Webhook provider, if known"),
+        endpointSlug: z.string().optional().describe("Hosted endpoint slug, if known"),
+        targetUrl: z.string().optional().describe("Your app's receiving URL, if known")
+      }
+    },
+    async ({ provider, endpointSlug, targetUrl }) => {
+      const scope = [
+        provider ? `Provider: ${provider}.` : null,
+        endpointSlug ? `Endpoint slug: ${endpointSlug}.` : null,
+        targetUrl ? `Target URL: ${targetUrl}.` : null
+      ].filter(Boolean).join(" ");
+      return {
+        description: "Diagnose a missing or broken webhook delivery.",
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                scope,
+                "Diagnose webhook delivery step by step.",
+                "Use list_endpoints or get_endpoint to confirm the endpoint and URL.",
+                "Use list_requests, wait_for_request, or wait_for_requests to check whether anything arrived.",
+                "If the provider is known, use preview_webhook or send_webhook to reproduce the webhook with realistic signing.",
+                "Use verify_signature when a secret is available.",
+                "Use compare_requests to compare retries or changed payloads.",
+                "Conclude with the most likely cause and the next concrete fix."
+              ].filter(Boolean).join(" ")
+            }
+          }
+        ]
+      };
+    }
+  );
+  server.registerPrompt(
+    "setup_provider_testing",
+    {
+      title: "Setup Provider Testing",
+      description: "Guide an agent through setting up webhook testing for a provider.",
+      argsSchema: {
+        provider: z.string().describe("Webhook provider to test"),
+        targetUrl: z.string().optional().describe("Optional local or remote target URL")
+      }
+    },
+    async ({ provider, targetUrl }) => {
+      return {
+        description: `Set up webhook testing for ${provider}.`,
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Set up webhook testing for ${provider}.`,
+                "Use list_provider_templates to inspect supported templates and signing details first.",
+                "Create an endpoint with create_endpoint, preferably ephemeral.",
+                "If a target URL is provided, use preview_webhook before send_to so the request shape is visible.",
+                targetUrl ? `Target URL: ${targetUrl}.` : null,
+                "Send a realistic provider webhook, wait for capture, and verify the signature if a secret is available.",
+                "Return the endpoint URL, the exact tools used, and the next step for the developer."
+              ].filter(Boolean).join(" ")
+            }
+          }
+        ]
+      };
+    }
+  );
+  server.registerPrompt(
+    "compare_webhook_attempts",
+    {
+      title: "Compare Webhook Attempts",
+      description: "Guide an agent through comparing two webhook deliveries or retries.",
+      argsSchema: {
+        endpointSlug: z.string().optional().describe("Endpoint slug to inspect for recent attempts"),
+        leftRequestId: z.string().optional().describe("First request ID, if already known"),
+        rightRequestId: z.string().optional().describe("Second request ID, if already known")
+      }
+    },
+    async ({ endpointSlug, leftRequestId, rightRequestId }) => {
+      return {
+        description: "Compare two webhook deliveries and explain the difference.",
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                endpointSlug ? `Endpoint slug: ${endpointSlug}.` : null,
+                leftRequestId && rightRequestId ? `Compare request ${leftRequestId} against ${rightRequestId}.` : "Find the most relevant two webhook attempts first.",
+                "Use compare_requests for the structured diff.",
+                "If request IDs are not provided, use list_requests or the endpoint recent resource to find the last two attempts.",
+                "Explain what changed in the body, headers, or timing, and whether the difference looks expected, retried, or broken."
+              ].filter(Boolean).join(" ")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+var ENDPOINTS_RESOURCE_URI = "webhooks://endpoints";
+var ENDPOINT_RECENT_TEMPLATE_URI = "webhooks://endpoint/{slug}/recent";
+var REQUEST_TEMPLATE_URI = "webhooks://request/{id}";
+var MAX_ENDPOINT_RESOURCE_ITEMS = 25;
+var RECENT_REQUEST_LIMIT = 10;
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+function summarizeRequest(request) {
+  return {
+    id: request.id,
+    method: request.method,
+    path: request.path,
+    receivedAt: request.receivedAt,
+    contentType: request.contentType ?? null
+  };
+}
+function variableToString(value, name) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  throw new Error(`Missing resource variable "${name}"`);
+}
+async function listEndpointSummaries(client) {
+  const endpoints = (await client.endpoints.list()).slice().sort((left, right) => right.createdAt - left.createdAt);
+  const truncated = endpoints.length > MAX_ENDPOINT_RESOURCE_ITEMS;
+  const visible = endpoints.slice(0, MAX_ENDPOINT_RESOURCE_ITEMS);
+  const summaries = await Promise.all(
+    visible.map(async (endpoint) => {
+      const recent = await client.requests.list(endpoint.slug, { limit: 1 });
+      return {
+        ...endpoint,
+        lastRequest: recent[0] ? summarizeRequest(recent[0]) : null
+      };
+    })
+  );
+  return {
+    endpoints: summaries,
+    total: endpoints.length,
+    truncated
+  };
+}
+function registerResources(server, client) {
+  server.registerResource(
+    "endpoints-overview",
+    ENDPOINTS_RESOURCE_URI,
+    {
+      title: "Endpoints Overview",
+      description: "All endpoints with a summary of recent activity.",
+      mimeType: "application/json"
+    },
+    async () => {
+      return jsonResource(ENDPOINTS_RESOURCE_URI, await listEndpointSummaries(client));
+    }
+  );
+  server.registerResource(
+    "endpoint-recent-requests",
+    new ResourceTemplate(ENDPOINT_RECENT_TEMPLATE_URI, {
+      list: async () => {
+        const endpoints = await client.endpoints.list();
+        return {
+          resources: endpoints.map((endpoint) => ({
+            uri: `webhooks://endpoint/${endpoint.slug}/recent`,
+            name: `${endpoint.slug} recent requests`,
+            description: `Recent requests for endpoint ${endpoint.slug}`,
+            mimeType: "application/json"
+          }))
+        };
+      },
+      complete: {
+        slug: async (value) => {
+          const endpoints = await client.endpoints.list();
+          return endpoints.map((endpoint) => endpoint.slug).filter((slug) => slug.startsWith(value)).slice(0, 20);
+        }
+      }
+    }),
+    {
+      title: "Endpoint Recent Requests",
+      description: "Last 10 captured requests for an endpoint.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const slug = variableToString(variables.slug, "slug");
+      const [endpoint, requests] = await Promise.all([
+        client.endpoints.get(slug),
+        client.requests.list(slug, { limit: RECENT_REQUEST_LIMIT })
+      ]);
+      return jsonResource(uri.toString(), {
+        endpoint,
+        requests
+      });
+    }
+  );
+  server.registerResource(
+    "request-details",
+    new ResourceTemplate(REQUEST_TEMPLATE_URI, {
+      list: void 0,
+      complete: {}
+    }),
+    {
+      title: "Request Details",
+      description: "Full details for a captured request by ID.",
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      const id = variableToString(variables.id, "id");
+      const request = await client.requests.get(id);
+      return jsonResource(uri.toString(), request);
+    }
+  );
+}
+
+// src/tools.ts
+import { z as z2 } from "zod";
+import {
+  diffRequests,
+  extractJsonField,
+  NotFoundError,
+  RateLimitError,
+  TimeoutError,
+  UnauthorizedError,
+  verifySignature,
+  WebhooksCCError
+} from "@webhooks-cc/sdk";
 var MAX_BODY_SIZE = 32768;
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+var TEMPLATE_PROVIDER_VALUES = [
+  "stripe",
+  "github",
+  "shopify",
+  "twilio",
+  "slack",
+  "paddle",
+  "linear",
+  "standard-webhooks"
+];
+var VERIFY_PROVIDER_VALUES = [
+  ...TEMPLATE_PROVIDER_VALUES,
+  "discord"
+];
+var TIME_SEPARATOR = " \u2014 ";
+var httpUrlSchema = z2.string().url().refine(
+  (value) => {
+    try {
+      const protocol = new URL(value).protocol;
+      return protocol === "http:" || protocol === "https:";
+    } catch {
+      return false;
+    }
+  },
+  { message: "Only http and https URLs are supported" }
+);
+var methodSchema = z2.enum(HTTP_METHODS).default("POST").describe("HTTP method (default: POST)");
+var durationOrTimestampSchema = z2.union([z2.string(), z2.number()]);
+var mockResponseSchema = z2.object({
+  status: z2.number().int().min(100).max(599).describe("HTTP status code (100-599)"),
+  body: z2.string().default("").describe("Response body string (default: empty)"),
+  headers: z2.record(z2.string()).default({}).describe("Response headers (default: none)")
+});
 function textContent(text) {
   return { content: [{ type: "text", text }] };
 }
+function serializeJson(value, limit = MAX_BODY_SIZE) {
+  const full = JSON.stringify(value, null, 2);
+  if (full.length <= limit) {
+    return full;
+  }
+  if (Array.isArray(value)) {
+    let low = 0;
+    let high = value.length;
+    let best = JSON.stringify(
+      { items: [], truncated: true, total: value.length, returned: 0 },
+      null,
+      2
+    );
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      const candidate = JSON.stringify(
+        {
+          items: value.slice(0, mid),
+          truncated: true,
+          total: value.length,
+          returned: mid
+        },
+        null,
+        2
+      );
+      if (candidate.length <= limit) {
+        best = candidate;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    return best;
+  }
+  return full.slice(0, limit) + `
+... [truncated, ${full.length} chars total]`;
+}
+function jsonContent(value) {
+  return textContent(serializeJson(value));
+}
 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 sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function splitHint(message) {
+  const separatorIndex = message.indexOf(TIME_SEPARATOR);
+  if (separatorIndex === -1) {
+    return { message, hint: null };
+  }
+  return {
+    message: message.slice(0, separatorIndex),
+    hint: message.slice(separatorIndex + TIME_SEPARATOR.length) || null
+  };
+}
+function serializeError(error) {
+  const rawMessage = error instanceof Error ? error.message : String(error);
+  const { message, hint } = splitHint(rawMessage);
+  const payload = {
+    error: true,
+    code: "validation_error",
+    message,
+    hint,
+    retryAfter: null
+  };
+  if (error instanceof UnauthorizedError) {
+    payload.code = "unauthorized";
+  } else if (error instanceof NotFoundError) {
+    payload.code = "not_found";
+  } else if (error instanceof RateLimitError) {
+    payload.code = "rate_limited";
+    payload.retryAfter = error.retryAfter ?? null;
+  } else if (error instanceof TimeoutError) {
+    payload.code = "timeout";
+  } else if (error instanceof WebhooksCCError) {
+    payload.code = error.statusCode >= 500 ? "server_error" : "validation_error";
+  }
+  return JSON.stringify(payload, null, 2);
+}
 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 };
+      return { ...textContent(serializeError(error)), isError: true };
+    }
+  };
+}
+function filterRequestsByMethod(requests, method) {
+  if (!method) {
+    return requests;
+  }
+  const target = method.toUpperCase();
+  return requests.filter((request) => request.method.toUpperCase() === target);
+}
+async function waitForMultipleRequests(client, endpointSlug, options) {
+  const timeoutMs = typeof options.timeout === "number" ? options.timeout : options.timeout ? Number.isNaN(Number(options.timeout)) ? parseDurationLike(options.timeout) : Number(options.timeout) : 3e4;
+  const pollIntervalMs = typeof options.pollInterval === "number" ? options.pollInterval : options.pollInterval ? Number.isNaN(Number(options.pollInterval)) ? parseDurationLike(options.pollInterval) : Number(options.pollInterval) : 500;
+  const startedAt = Date.now();
+  let since = startedAt;
+  const seenIds = /* @__PURE__ */ new Set();
+  const requests = [];
+  while (Date.now() - startedAt < timeoutMs) {
+    const checkTime = Date.now();
+    const page = await client.requests.list(endpointSlug, {
+      since,
+      limit: Math.max(100, options.count * 5)
+    });
+    since = checkTime;
+    const filtered = filterRequestsByMethod(page, options.method).slice().sort((left, right) => left.receivedAt - right.receivedAt);
+    for (const request of filtered) {
+      if (seenIds.has(request.id)) {
+        continue;
+      }
+      seenIds.add(request.id);
+      requests.push(request);
+      if (requests.length >= options.count) {
+        return {
+          requests,
+          complete: true,
+          timedOut: false,
+          expectedCount: options.count
+        };
+      }
+    }
+    await sleep(Math.max(10, pollIntervalMs));
+  }
+  return {
+    requests,
+    complete: requests.length >= options.count,
+    timedOut: true,
+    expectedCount: options.count
+  };
+}
+function parseDurationLike(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error("Duration value cannot be empty");
+  }
+  const numeric = Number(trimmed);
+  if (!Number.isNaN(numeric)) {
+    return numeric;
+  }
+  const match = trimmed.match(/^(\d+)\s*(ms|s|m|h|d)$/i);
+  if (!match) {
+    throw new Error(`Invalid duration: "${value}"`);
+  }
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1e3 : unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5;
+  return amount * multiplier;
+}
+function ensureVerifyArgs(args) {
+  if (args.provider === "discord") {
+    const publicKey = args.publicKey?.trim();
+    if (!publicKey) {
+      throw new Error('verify_signature for provider "discord" requires publicKey');
     }
+    return {
+      provider: "discord",
+      publicKey
+    };
+  }
+  const secret = args.secret?.trim();
+  if (!secret) {
+    throw new Error(`verify_signature for provider "${args.provider}" requires secret`);
+  }
+  return {
+    provider: args.provider,
+    secret,
+    ...args.url ? { url: args.url } : {}
+  };
+}
+async function summarizeResponse(response) {
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    body: await readBodyTruncated(response)
   };
 }
 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));
+    "Create a webhook endpoint. Returns the endpoint slug, URL, and metadata.",
+    {
+      name: z2.string().optional().describe("Display name for the endpoint"),
+      ephemeral: z2.boolean().optional().describe("Create a temporary endpoint that auto-expires"),
+      expiresIn: durationOrTimestampSchema.optional().describe('Auto-expire after this duration, for example "12h"'),
+      mockResponse: mockResponseSchema.optional().describe("Optional mock response to return when the endpoint receives a request")
+    },
+    withErrorHandling(async ({ name, ephemeral, expiresIn, mockResponse }) => {
+      const endpoint = await client.endpoints.create({ name, ephemeral, expiresIn, mockResponse });
+      return jsonContent(endpoint);
     })
   );
   server.tool(
     "list_endpoints",
-    "List all webhook endpoints for the authenticated user. Returns an array of endpoints with their slugs, names, and URLs.",
+    "List all webhook endpoints for the authenticated user.",
     {},
     withErrorHandling(async () => {
       const endpoints = await client.endpoints.list();
-      return textContent(JSON.stringify(endpoints, null, 2));
+      return jsonContent(endpoints);
     })
   );
   server.tool(
     "get_endpoint",
-    "Get details for a specific webhook endpoint by its slug.",
-    { slug: z.string().describe("The endpoint slug (from the URL)") },
+    "Get details for a specific webhook endpoint by slug.",
+    { slug: z2.string().describe("The endpoint slug") },
     withErrorHandling(async ({ slug }) => {
       const endpoint = await client.endpoints.get(slug);
-      return textContent(JSON.stringify(endpoint, null, 2));
+      return jsonContent(endpoint);
     })
   );
   server.tool(
     "update_endpoint",
-    "Update an endpoint's name or mock response configuration.",
+    "Update an endpoint 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")
+      slug: z2.string().describe("The endpoint slug to update"),
+      name: z2.string().optional().describe("New display name"),
+      mockResponse: mockResponseSchema.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));
+      return jsonContent(endpoint);
     })
   );
   server.tool(
     "delete_endpoint",
     "Delete a webhook endpoint and all its captured requests.",
-    { slug: z.string().describe("The endpoint slug to delete") },
+    { slug: z2.string().describe("The endpoint slug to delete") },
     withErrorHandling(async ({ slug }) => {
       await client.endpoints.delete(slug);
       return textContent(`Endpoint "${slug}" deleted.`);
     })
   );
+  server.tool(
+    "create_endpoints",
+    "Create multiple webhook endpoints in one call.",
+    {
+      count: z2.number().int().min(1).max(20).describe("Number of endpoints to create"),
+      namePrefix: z2.string().optional().describe("Optional prefix for endpoint names"),
+      ephemeral: z2.boolean().optional().describe("Create temporary endpoints that auto-expire"),
+      expiresIn: durationOrTimestampSchema.optional().describe('Auto-expire after this duration, for example "12h"')
+    },
+    withErrorHandling(async ({ count, namePrefix, ephemeral, expiresIn }) => {
+      const endpoints = await Promise.all(
+        Array.from(
+          { length: count },
+          (_, index) => client.endpoints.create({
+            name: namePrefix ? `${namePrefix}-${index + 1}` : void 0,
+            ephemeral,
+            expiresIn
+          })
+        )
+      );
+      return jsonContent({ endpoints });
+    })
+  );
+  server.tool(
+    "delete_endpoints",
+    "Delete multiple webhook endpoints in one call.",
+    {
+      slugs: z2.array(z2.string()).min(1).max(100).describe("Endpoint slugs to delete")
+    },
+    withErrorHandling(async ({ slugs }) => {
+      const settled = await Promise.allSettled(
+        slugs.map(async (slug) => {
+          await client.endpoints.delete(slug);
+          return slug;
+        })
+      );
+      return jsonContent({
+        deleted: settled.filter(
+          (result) => result.status === "fulfilled"
+        ).map((result) => result.value),
+        failed: settled.flatMap(
+          (result, index) => result.status === "rejected" ? [
+            {
+              slug: slugs[index],
+              message: result.reason instanceof Error ? result.reason.message : String(result.reason)
+            }
+          ] : []
+        )
+      });
+    })
+  );
   server.tool(
     "send_webhook",
-    "Send a test webhook to an endpoint. Useful for testing webhook handling code.",
+    "Send a test webhook to a hosted endpoint. Supports provider templates and signing.",
     {
-      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)"),
-      provider: z.enum(["stripe", "github", "shopify", "twilio", "standard-webhooks"]).optional().describe("Optional provider template to send with signed headers"),
-      template: z.string().optional().describe("Optional provider-specific template preset (for example: pull_request.opened)"),
-      event: z.string().optional().describe("Optional provider event/topic name when provider template is used"),
-      secret: z.string().optional().describe(
-        "Shared secret for provider signature generation (required when provider is set)"
-      )
+      slug: z2.string().describe("The endpoint slug to send to"),
+      method: methodSchema,
+      headers: z2.record(z2.string()).optional().describe("HTTP headers to include"),
+      body: z2.unknown().optional().describe("Request body"),
+      provider: z2.enum(TEMPLATE_PROVIDER_VALUES).optional().describe("Optional provider template to send with signed headers"),
+      template: z2.string().optional().describe("Provider-specific template preset"),
+      event: z2.string().optional().describe("Provider event or topic name"),
+      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
     },
     withErrorHandling(
       async ({ slug, method, headers, body, provider, template, event, secret }) => {
@@ -114,104 +608,204 @@ function registerTools(server, client) {
           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
-          )
-        );
+        return jsonContent({
+          status: response.status,
+          statusText: response.statusText,
+          body: responseBody
+        });
       }
     )
   );
   server.tool(
     "list_requests",
-    "List captured webhook requests for an endpoint. Returns the most recent requests (default: 25).",
+    "List recent captured requests for an endpoint.",
     {
-      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)")
+      endpointSlug: z2.string().describe("The endpoint slug"),
+      limit: z2.number().int().min(1).max(100).default(25).describe("Max requests to return"),
+      since: z2.number().optional().describe("Only return requests after this timestamp in ms")
     },
     withErrorHandling(async ({ endpointSlug, limit, since }) => {
       const requests = await client.requests.list(endpointSlug, { limit, since });
-      return textContent(JSON.stringify(requests, null, 2));
+      return jsonContent(requests);
+    })
+  );
+  server.tool(
+    "search_requests",
+    "Search captured webhook requests across endpoints using retained full-text search.",
+    {
+      slug: z2.string().optional().describe("Filter to a specific endpoint slug"),
+      method: z2.string().optional().describe("Filter by HTTP method"),
+      q: z2.string().optional().describe("Free-text search across path, body, and headers"),
+      from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
+      to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"'),
+      limit: z2.number().int().min(1).max(200).default(50).describe("Max results to return"),
+      offset: z2.number().int().min(0).max(1e4).default(0).describe("Result offset"),
+      order: z2.enum(["asc", "desc"]).default("desc").describe("Sort order by received time")
+    },
+    withErrorHandling(async ({ slug, method, q, from, to, limit, offset, order }) => {
+      const results = await client.requests.search({
+        slug,
+        method,
+        q,
+        from,
+        to,
+        limit,
+        offset,
+        order
+      });
+      return jsonContent(results);
+    })
+  );
+  server.tool(
+    "count_requests",
+    "Count captured webhook requests that match the given filters.",
+    {
+      slug: z2.string().optional().describe("Filter to a specific endpoint slug"),
+      method: z2.string().optional().describe("Filter by HTTP method"),
+      q: z2.string().optional().describe("Free-text search across path, body, and headers"),
+      from: durationOrTimestampSchema.optional().describe('Start time as a timestamp or duration like "1h" or "7d"'),
+      to: durationOrTimestampSchema.optional().describe('End time as a timestamp or duration like "1h" or "7d"')
+    },
+    withErrorHandling(async ({ slug, method, q, from, to }) => {
+      const count = await client.requests.count({ slug, method, q, from, to });
+      return jsonContent({ count });
     })
   );
   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") },
+    "Get full details for a specific captured request by ID.",
+    { requestId: z2.string().describe("The request ID") },
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
-      return textContent(JSON.stringify(request, null, 2));
+      return jsonContent(request);
     })
   );
   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.",
+    "Wait for a request to arrive at an endpoint.",
     {
-      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')
+      endpointSlug: z2.string().describe("The endpoint slug to monitor"),
+      timeout: durationOrTimestampSchema.default("30s").describe('How long to wait, for example "30s"'),
+      pollInterval: durationOrTimestampSchema.optional().describe('Interval between polls, for example "500ms" or "1s"')
     },
     withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
       const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
-      return textContent(JSON.stringify(request, null, 2));
+      return jsonContent(request);
+    })
+  );
+  server.tool(
+    "wait_for_requests",
+    "Wait for multiple requests to arrive at an endpoint.",
+    {
+      endpointSlug: z2.string().describe("The endpoint slug to monitor"),
+      count: z2.number().int().min(1).max(20).describe("Number of requests to collect"),
+      timeout: durationOrTimestampSchema.default("30s").describe('How long to wait, for example "30s"'),
+      pollInterval: durationOrTimestampSchema.optional().describe('Interval between polls, for example "500ms" or "1s"'),
+      method: z2.string().optional().describe("Only collect requests with this HTTP method")
+    },
+    withErrorHandling(async ({ endpointSlug, count, timeout, pollInterval, method }) => {
+      const result = await waitForMultipleRequests(client, endpointSlug, {
+        count,
+        timeout,
+        pollInterval,
+        method
+      });
+      return jsonContent(result);
     })
   );
   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.",
+    "Replay a previously captured request to a target URL.",
     {
-      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)")
+      requestId: z2.string().describe("The captured request ID"),
+      targetUrl: httpUrlSchema.describe("The URL to replay the request to")
     },
     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
-        )
+      return jsonContent({
+        status: response.status,
+        statusText: response.statusText,
+        body: responseBody
+      });
+    })
+  );
+  server.tool(
+    "compare_requests",
+    "Compare two captured requests and show the structured differences.",
+    {
+      leftRequestId: z2.string().describe("The first request ID"),
+      rightRequestId: z2.string().describe("The second request ID"),
+      ignoreHeaders: z2.array(z2.string()).optional().describe("Headers to ignore during comparison")
+    },
+    withErrorHandling(async ({ leftRequestId, rightRequestId, ignoreHeaders }) => {
+      const [leftRequest, rightRequest] = await Promise.all([
+        client.requests.get(leftRequestId),
+        client.requests.get(rightRequestId)
+      ]);
+      const diff = diffRequests(leftRequest, rightRequest, { ignoreHeaders });
+      return jsonContent(diff);
+    })
+  );
+  server.tool(
+    "extract_from_request",
+    "Extract specific JSON fields from a captured request body.",
+    {
+      requestId: z2.string().describe("The request ID"),
+      jsonPaths: z2.array(z2.string()).min(1).max(50).describe("Dot-notation JSON paths to extract")
+    },
+    withErrorHandling(async ({ requestId, jsonPaths }) => {
+      const request = await client.requests.get(requestId);
+      const extracted = Object.fromEntries(
+        jsonPaths.map((path) => [path, extractJsonField(request, path) ?? null])
       );
+      return jsonContent(extracted);
+    })
+  );
+  server.tool(
+    "verify_signature",
+    "Verify the webhook signature on a captured request.",
+    {
+      requestId: z2.string().describe("The captured request ID"),
+      provider: z2.enum(VERIFY_PROVIDER_VALUES).describe("Provider whose signature scheme should be verified"),
+      secret: z2.string().optional().describe("Shared signing secret. Required for non-Discord providers."),
+      publicKey: z2.string().optional().describe("Discord application public key. Required for provider=discord."),
+      url: httpUrlSchema.optional().describe("Original signed URL. Required for Twilio verification.")
+    },
+    withErrorHandling(async ({ requestId, provider, secret, publicKey, url }) => {
+      const request = await client.requests.get(requestId);
+      const verificationOptions = ensureVerifyArgs({ provider, secret, publicKey, url });
+      const result = await verifySignature(request, verificationOptions);
+      return jsonContent({
+        valid: result.valid,
+        details: result.valid ? "Signature is valid." : "Signature did not match."
+      });
+    })
+  );
+  server.tool(
+    "clear_requests",
+    "Delete captured requests for an endpoint without deleting the endpoint itself.",
+    {
+      slug: z2.string().describe("The endpoint slug to clear"),
+      before: durationOrTimestampSchema.optional().describe('Only clear requests older than this timestamp or duration like "1h"')
+    },
+    withErrorHandling(async ({ slug, before }) => {
+      await client.requests.clear(slug, { before });
+      return jsonContent({ slug, cleared: true, before: before ?? null });
     })
   );
   server.tool(
     "send_to",
-    "Send a webhook directly to any URL with optional provider signing. Use this for local integration testing \u2014 send properly signed webhooks to localhost handlers without routing through webhooks.cc infrastructure.",
+    "Send a webhook directly to any URL with optional provider signing.",
     {
-      url: 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("Target URL to send the webhook 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)"),
-      provider: z.enum(["stripe", "github", "shopify", "twilio", "standard-webhooks"]).optional().describe("Optional provider template for signing"),
-      template: z.string().optional().describe("Provider-specific template preset (not used for standard-webhooks)"),
-      event: z.string().optional().describe("Provider event/topic name"),
-      secret: z.string().optional().describe(
-        "Shared secret for provider signature generation (required when provider is set)"
-      )
+      url: httpUrlSchema.describe("Target URL"),
+      method: methodSchema,
+      headers: z2.record(z2.string()).optional().describe("HTTP headers to include"),
+      body: z2.unknown().optional().describe("Request body"),
+      provider: z2.enum(TEMPLATE_PROVIDER_VALUES).optional().describe("Optional provider template for signing"),
+      template: z2.string().optional().describe("Provider-specific template preset"),
+      event: z2.string().optional().describe("Provider event or topic name"),
+      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
     },
     withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
       const response = await client.sendTo(url, {
@@ -224,28 +818,152 @@ function registerTools(server, client) {
         secret
       });
       const responseBody = await readBodyTruncated(response);
-      return textContent(
-        JSON.stringify(
-          { status: response.status, statusText: response.statusText, body: responseBody },
-          null,
-          2
-        )
+      return jsonContent({
+        status: response.status,
+        statusText: response.statusText,
+        body: responseBody
+      });
+    })
+  );
+  server.tool(
+    "preview_webhook",
+    "Preview a webhook request without sending it. Returns the exact URL, method, headers, and body.",
+    {
+      url: httpUrlSchema.describe("Target URL"),
+      method: methodSchema,
+      headers: z2.record(z2.string()).optional().describe("HTTP headers to include"),
+      body: z2.unknown().optional().describe("Request body"),
+      provider: z2.enum(TEMPLATE_PROVIDER_VALUES).optional().describe("Optional provider template for signing"),
+      template: z2.string().optional().describe("Provider-specific template preset"),
+      event: z2.string().optional().describe("Provider event or topic name"),
+      secret: z2.string().optional().describe("Signing secret. Required when provider is set.")
+    },
+    withErrorHandling(async ({ url, method, headers, body, provider, template, event, secret }) => {
+      const preview = await client.buildRequest(url, {
+        method,
+        headers,
+        body,
+        provider,
+        template,
+        event,
+        secret
+      });
+      return jsonContent(preview);
+    })
+  );
+  server.tool(
+    "list_provider_templates",
+    "List supported webhook providers, templates, and signing metadata.",
+    {
+      provider: z2.enum(TEMPLATE_PROVIDER_VALUES).optional().describe("Filter to a single provider")
+    },
+    withErrorHandling(async ({ provider }) => {
+      if (provider) {
+        return jsonContent([client.templates.get(provider)]);
+      }
+      return jsonContent(
+        client.templates.listProviders().map((name) => client.templates.get(name))
       );
     })
   );
+  server.tool(
+    "get_usage",
+    "Check current request usage, remaining quota, plan, and period end.",
+    {},
+    withErrorHandling(async () => {
+      const usage = await client.usage();
+      return jsonContent({
+        ...usage,
+        periodEnd: usage.periodEnd ? new Date(usage.periodEnd).toISOString() : null
+      });
+    })
+  );
+  server.tool(
+    "test_webhook_flow",
+    "Run a full webhook test flow: create endpoint, optionally mock, send, wait, verify, replay, and clean up.",
+    {
+      provider: z2.enum(TEMPLATE_PROVIDER_VALUES).optional().describe("Optional provider template to use when sending the webhook"),
+      event: z2.string().optional().describe("Optional provider event or topic name"),
+      secret: z2.string().optional().describe(
+        "Signing secret. Required when provider is set or signature verification is enabled."
+      ),
+      mockStatus: z2.number().int().min(100).max(599).optional().describe("Optional mock response status to configure before sending"),
+      targetUrl: httpUrlSchema.optional().describe("Optional URL to replay the captured request to after capture"),
+      verifySignature: z2.boolean().default(false).describe("Verify the captured request signature after capture"),
+      cleanup: z2.boolean().default(true).describe("Delete the created endpoint after the flow completes")
+    },
+    withErrorHandling(
+      async ({
+        provider,
+        event,
+        secret,
+        mockStatus,
+        targetUrl,
+        verifySignature: shouldVerify,
+        cleanup
+      }) => {
+        const flow = client.flow().createEndpoint({ expiresIn: "1h" }).waitForCapture({ timeout: "30s" });
+        if (mockStatus !== void 0) {
+          flow.setMock({
+            status: mockStatus,
+            body: "",
+            headers: {}
+          });
+        }
+        if (provider) {
+          const templateSecret = secret?.trim();
+          if (!templateSecret) {
+            throw new Error(
+              "test_webhook_flow with provider templates requires a non-empty secret"
+            );
+          }
+          flow.sendTemplate({
+            provider,
+            event,
+            secret: templateSecret
+          });
+          if (shouldVerify) {
+            flow.verifySignature({
+              provider,
+              secret: templateSecret
+            });
+          }
+        } else {
+          if (shouldVerify) {
+            throw new Error("test_webhook_flow cannot verify signatures without a provider");
+          }
+          flow.send();
+        }
+        if (targetUrl) {
+          flow.replayTo(targetUrl);
+        }
+        if (cleanup) {
+          flow.cleanup();
+        }
+        const result = await flow.run();
+        return jsonContent({
+          endpoint: result.endpoint,
+          request: result.request ?? null,
+          verification: result.verification ?? null,
+          replayResponse: result.replayResponse ? await summarizeResponse(result.replayResponse) : null,
+          cleanedUp: result.cleanedUp
+        });
+      }
+    )
+  );
   server.tool(
     "describe",
-    "Describe all available SDK operations, their parameters, and types. Useful for discovering what actions are possible.",
+    "Describe all available SDK operations, parameters, and types.",
     {},
     withErrorHandling(async () => {
       const description = client.describe();
-      return textContent(JSON.stringify(description, null, 2));
+      return jsonContent(description);
     })
   );
 }
 
 // src/index.ts
-var VERSION = true ? "0.3.0" : "0.0.0-dev";
+var VERSION = true ? "1.0.0" : "0.0.0-dev";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
   if (!apiKey) {
@@ -256,14 +974,18 @@ function createServer(options = {}) {
     webhookUrl: options.webhookUrl ?? process.env.WHK_WEBHOOK_URL,
     baseUrl: options.baseUrl ?? process.env.WHK_BASE_URL
   });
-  const server = new McpServer({
+  const server = new McpServer2({
     name: "webhooks-cc",
     version: VERSION
   });
   registerTools(server, client);
+  registerPrompts(server);
+  registerResources(server, client);
   return server;
 }
 export {
   createServer,
+  registerPrompts,
+  registerResources,
   registerTools
 };