@webhooks-cc/mcp 1.23.0 → 1.24.0

package/README.md

@@ -34,7 +34,7 @@ For other agents, `npx skills add kroqdotdev/webhooks-cc` installs the same skil
 - **claude.ai and Claude Desktop**: Settings, Connectors, add a custom connector with the URL `https://webhooks.cc/mcp`
 - **ChatGPT**: add it as a custom connector (developer mode)
 
-A client that can send headers may use an API key instead: `Authorization: Bearer whcc_...`. The remote server has 54 tools: `send_to`, `replay_request` and `share_port` are left out and `targetUrl` is refused, because a hosted server cannot reach your machine, and waits are capped at 50 seconds. It needs an account (no sandbox), and serves tools only, without prompts or resources.
+A client that can send headers may use an API key instead: `Authorization: Bearer whcc_...`. The remote server has 91 tools: `send_to`, `replay_request` and `share_port` are left out and `targetUrl` is refused, because a hosted server cannot reach your machine, and waits are capped at 50 seconds. It needs an account (no sandbox), and serves tools only, without prompts or resources.
 
 ### One-click
 
@@ -83,7 +83,7 @@ Leave out `env` to start without a key. Get your API key at [webhooks.cc/account
 
 ## What it exposes
 
-The server exposes `57` tools, `3` prompts, and `3` resource surfaces with an API key, the same `57` tools and the prompts with a saved connection, and `11` sandbox tools otherwise. The remote server exposes `54` tools.
+The server exposes `94` tools, `3` prompts, and `3` resource surfaces with an API key, the same `94` tools and the prompts with a saved connection, and `11` sandbox tools otherwise. The remote server exposes `91` tools.
 
 ### Endpoint tools
 
@@ -257,7 +257,7 @@ Use `list_provider_templates` to inspect templates, default events, signature he
 Typical agent flows:
 
 - Create an ephemeral endpoint, send a provider-signed webhook, and wait for capture
-- Search retained requests across endpoints with full-text filters
+- Search retained requests across endpoints by substring, continuing with the cursor through long histories
 - Compare two webhook attempts and extract only the JSON fields you care about
 - Verify a captured signature against a known secret
 - Run `test_webhook_flow` to create, send, capture, verify, replay, and clean up in one tool call

package/dist/bin/mcp.js

@@ -456,7 +456,7 @@ var import_zod3 = require("zod");
 var import_sdk2 = require("@webhooks-cc/sdk");
 
 // src/version.ts
-var VERSION = true ? "1.23.0" : "0.0.0-dev";
+var VERSION = true ? "1.24.0" : "0.0.0-dev";
 var MCP_USER_AGENT = `webhooks-cc-mcp/${VERSION}`;
 
 // src/tools.ts
@@ -721,6 +721,14 @@ ${JSON.stringify(result, null, 2)}`;
   if (typeof result.url === "string") {
     return `Approved. The share link is ${result.url} (anyone with it can read the copy until ${String(result.expiresAt)}).`;
   }
+  if (typeof result.invitedEmail === "string") {
+    const team = typeof result.teamName === "string" ? ` to "${result.teamName}"` : "";
+    const warning = typeof result.warning === "string" ? ` ${result.warning} Tell them to sign up with that address and accept from their Teams page.` : " They get an email; accepting claims one of the team's seats.";
+    return `Approved. Invited ${result.invitedEmail}${team} (invite ${String(result.id)}).${warning}`;
+  }
+  if (typeof result.deleted === "string" && typeof result.teamId === "string") {
+    return `Approved. The team ${result.deleted ? `"${result.deleted}" ` : ""}was deleted; its subscription has ended.`;
+  }
   if (typeof result.removed === "string") {
     return `Approved. The domain ${result.removed} was removed; mail to it is refused now.`;
   }
@@ -795,6 +803,75 @@ function fitArrayField(value, key) {
   }
   return cut(low);
 }
+function isoTime(ms) {
+  if (ms === null || !Number.isFinite(ms)) return null;
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function searchStoppedNote(searchedUntil, order, hasCursor) {
+  const [direction, rest] = order === "asc" ? ["forward", "newer"] : ["back", "older"];
+  const reached = searchedUntil ? `Searched ${direction} to ${searchedUntil}; ${rest} requests were not searched yet.` : `The search stopped before it read everything; ${rest} requests were not searched yet.`;
+  return hasCursor ? `${reached} Call search_requests again with cursor to continue.` : reached;
+}
+var FULL_REQUEST_HINT = "The full request is available from the API (GET /api/requests/{id}), the SDKs (requests.get(id)) or the CLI (whk requests get <id>).";
+var SEARCH_SHORTENED_NOTE = `Some requests were shortened to fit the output (bodyTruncated with bodySize, or shortened: true for a summary); get_request with the id returns as much of one request as fits. ${FULL_REQUEST_HINT}`;
+var REQUEST_SHORTENED_NOTE = `This request was cut to fit the output: its body (bodyTruncated, with bodySize), or everything but a summary (shortened: true). ${FULL_REQUEST_HINT}`;
+function clip(value, max) {
+  return typeof value === "string" ? sliceText(value, max) : void 0;
+}
+function listedSize(request) {
+  return jsonSize([[request]]) - 8;
+}
+function fitSearchRequests(requests, room) {
+  const share = Math.floor(room / Math.max(1, requests.length));
+  const fitted = requests.map(
+    (request) => shortenRequest(request, share, listedSize)
+  );
+  if (fitted.every((request) => listedSize(request) <= share)) return fitted;
+  return requests.map((request) => {
+    const { id, receivedAt } = request;
+    return { id, receivedAt, shortened: true };
+  });
+}
+function shortenRequest(request, share, sizeOf) {
+  if (sizeOf(request) <= share) return request;
+  if (typeof request.body === "string") {
+    const body = request.body;
+    let keep = body.length - (sizeOf(request) - share) - 96;
+    while (keep > 0) {
+      const cut = {
+        ...request,
+        body: sliceText(body, keep),
+        bodyTruncated: true,
+        bodySize: body.length
+      };
+      if (sizeOf(cut) <= share) return cut;
+      keep = Math.floor(keep / 2);
+    }
+  }
+  const email = request.email;
+  const summary = {
+    id: request.id,
+    slug: clip(request.slug, 64),
+    method: clip(request.method, 16),
+    path: clip(request.path, 200),
+    contentType: clip(request.contentType, 100),
+    size: request.size,
+    receivedAt: request.receivedAt,
+    kind: request.kind,
+    ...email ? { subject: clip(email.subject, 200) } : {},
+    shortened: true,
+    ...typeof request.note === "string" ? { note: request.note } : {}
+  };
+  return summary;
+}
+function requestContent(request) {
+  const compact = compactRequest(request);
+  if (jsonSize(compact) <= MAX_BODY_SIZE) return jsonContent(compact);
+  return jsonContent(
+    shortenRequest({ ...compact, note: REQUEST_SHORTENED_NOTE }, MAX_BODY_SIZE, jsonSize)
+  );
+}
 function jsonContent(value) {
   return textContent(serializeJson(value));
 }
@@ -839,6 +916,13 @@ function serializeError(error) {
   } else if (error instanceof import_sdk.WebhooksCCError) {
     payload.code = error.statusCode >= 500 ? "server_error" : "validation_error";
   }
+  if (error instanceof import_sdk.WebhooksCCError && payload.hint === null) {
+    if (error.code === "invalid_cursor") {
+      payload.hint = "The cursor is not one this search returned, or the order changed since. Pass a cursor exactly as a result gave it, or search again without one.";
+    } else if (error.code === "search_busy") {
+      payload.hint = "The account's other searches are still running. Wait retryAfter seconds, then call again with the same inputs.";
+    }
+  }
   return JSON.stringify(payload, null, 2);
 }
 function withErrorHandling(handler) {
@@ -1290,6 +1374,124 @@ function registerTools(target, client, options = {}) {
       return jsonContent({ shared: false, slug, teamId });
     })
   );
+  server.tool(
+    "create_team",
+    "Create a team you own, to share endpoints with its members under a pooled quota. It does nothing until it has a subscription, which the person starts in the browser (Account > Teams); until then it is suspended.",
+    { name: import_zod2.z.string().trim().min(1).max(100).describe("The team's name") },
+    withErrorHandling(async ({ name }) => jsonContent(await client.teams.create(name)))
+  );
+  server.tool(
+    "rename_team",
+    "Rename a team you own.",
+    {
+      teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)"),
+      name: import_zod2.z.string().trim().min(1).max(100).describe("The new name")
+    },
+    withErrorHandling(async ({ teamId, name }) => {
+      await client.teams.rename(teamId, name);
+      return jsonContent({ renamed: true, teamId, name });
+    })
+  );
+  server.tool(
+    "delete_team",
+    "Delete a team you own: its subscription ends at once, every member loses the endpoints shared with it, and it cannot be undone. Only when the person asks for it. The team's owner must approve it: this returns a link and a code to show them, then call wait_for_approval.",
+    { teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)") },
+    withErrorHandling(async ({ teamId }) => {
+      const pending = await client.teams.delete(teamId);
+      if (!pending.id) return textContent(`Deleted the team ${teamId}.`);
+      return textContent(approvalAskText(pending));
+    })
+  );
+  server.tool(
+    "remove_team_member",
+    "Remove a member from a team you own: the endpoints they shared with the team stop being shared, and their seat is free for someone else. Only when the person asks for it.",
+    {
+      teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)"),
+      userId: import_zod2.z.string().min(1).describe("The member's userId (from list_team_members)")
+    },
+    withErrorHandling(async ({ teamId, userId }) => {
+      await client.teams.removeMember(teamId, userId);
+      return jsonContent({ removed: true, teamId, userId });
+    })
+  );
+  server.tool(
+    "leave_team",
+    "Leave a team you belong to: the endpoints you shared with it stop being shared, and you lose access to the ones shared with you through it. An owner cannot leave; they delete the team instead (delete_team). Only when the person asks for it.",
+    { teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)") },
+    withErrorHandling(async ({ teamId }) => {
+      await client.teams.leave(teamId);
+      return jsonContent({ left: true, teamId });
+    })
+  );
+  server.tool(
+    "invite_to_team",
+    "Invite an email address to a team you own. It emails that address, so the team's owner must approve it: this returns a link and a code to show them, then call wait_for_approval, which returns the invite. Accepting the invite claims one of the team's paid seats. Only when the person asks for it.",
+    {
+      teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)"),
+      email: import_zod2.z.string().trim().email().describe("The address to invite")
+    },
+    withErrorHandling(async ({ teamId, email }) => {
+      const pending = await client.teams.invite(teamId, email);
+      if (!pending.id) return textContent(approvalResultText({ ...await pending.wait() }));
+      return textContent(approvalAskText(pending));
+    })
+  );
+  server.tool(
+    "list_invites",
+    "List the team invites waiting for you to answer: team, who invited you, when, and the invite id for answer_invite.",
+    {},
+    withErrorHandling(async () => jsonContent(await client.teams.invites.list()))
+  );
+  server.tool(
+    "answer_invite",
+    "Accept or decline a team invite waiting for you (from list_invites). Accepting claims one of the team's paid seats and you join the team, seeing the endpoints shared with it; it fails when the team is full or suspended. Only when the person says which.",
+    {
+      inviteId: import_zod2.z.string().min(1).describe("The invite's id, from list_invites"),
+      answer: import_zod2.z.enum(["accept", "decline"]).describe("accept joins the team; decline turns it down")
+    },
+    withErrorHandling(async ({ inviteId, answer }) => {
+      if (answer === "accept") {
+        await client.teams.invites.accept(inviteId);
+        return jsonContent({ accepted: true, inviteId });
+      }
+      await client.teams.invites.decline(inviteId);
+      return jsonContent({ declined: true, inviteId });
+    })
+  );
+  server.tool(
+    "withdraw_invite",
+    "Withdraw an invite to a team you own before it is answered (pending invites and their ids are in list_team_members). The invite link stops working.",
+    {
+      teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)"),
+      inviteId: import_zod2.z.string().min(1).describe("The invite's id (from list_team_members' pendingInvites)")
+    },
+    withErrorHandling(async ({ teamId, inviteId }) => {
+      await client.teams.withdrawInvite(teamId, inviteId);
+      return jsonContent({ withdrawn: true, teamId, inviteId });
+    })
+  );
+  server.tool(
+    "quote_team_change",
+    "What changing a team's seat count or plan would cost, read only (owner only): what is due now, any credit, and the price from the renewal. Give seats, or plan (with interval). The change itself is made by the person in the browser.",
+    {
+      teamId: import_zod2.z.string().min(1).describe("Team id (from list_teams)"),
+      seats: import_zod2.z.number().int().min(1).optional().describe("Price this seat count"),
+      plan: import_zod2.z.enum(["team", "team_business"]).optional().describe("Price a move to this plan: team (Teams) or team_business (Team Business)"),
+      interval: import_zod2.z.enum(["month", "year"]).optional().describe("Billing interval for plan (default month; Teams is monthly only)")
+    },
+    withErrorHandling(async ({ teamId, seats, plan, interval }) => {
+      if (seats === void 0 === (plan === void 0)) {
+        throw new Error("Give seats or plan, not both.");
+      }
+      if (seats !== void 0) {
+        if (interval !== void 0) throw new Error("interval goes with plan, not seats.");
+        return jsonContent(await client.billing.quoteTeamSeats(teamId, seats));
+      }
+      return jsonContent(
+        await client.billing.quoteTeamPlan(teamId, plan, interval)
+      );
+    })
+  );
   server.tool(
     "get_endpoint",
     "Get details for a specific webhook endpoint by slug.",
@@ -1383,6 +1585,35 @@ function registerTools(target, client, options = {}) {
       return jsonContent(holder);
     })
   );
+  server.tool(
+    "list_layout_templates",
+    "List the ready-made email layouts (order emails from Shopify, WooCommerce, Etsy and more, payments, bookings, attachments): each with its id, sender, kind, description, the fields it reads and whether it reads line items. Add one with add_layout_template.",
+    { slug: import_zod2.z.string().describe("The endpoint slug") },
+    withErrorHandling(async ({ slug }) => jsonContent(await client.endpoints.layoutTemplates(slug)))
+  );
+  server.tool(
+    "add_layout_template",
+    "Add a ready-made layout (an id from list_layout_templates) to the end of an endpoint's layouts. Emails it matches are parsed from the next one on; check it on a captured email with preview_layouts. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      template: import_zod2.z.string().min(1).describe("The template's id, from list_layout_templates")
+    },
+    withErrorHandling(
+      async ({ slug, template }) => jsonContent(await client.endpoints.addLayoutTemplate(slug, template))
+    )
+  );
+  server.tool(
+    "preview_email_fields",
+    "Dry run of an endpoint's named email fields on a captured email: each field's value (null where it finds nothing), and problems with fields you pass. Nothing is saved. Pass emailFields to try fields before saving them with update_endpoint. Owner only.",
+    {
+      slug: import_zod2.z.string().describe("The endpoint slug"),
+      requestId: import_zod2.z.string().optional().describe("A captured email on the endpoint (default: the newest)"),
+      emailFields: import_zod2.z.array(emailFieldSchema).max(20).optional().describe("Unsaved fields to try instead of the saved ones")
+    },
+    withErrorHandling(
+      async ({ slug, requestId, emailFields }) => jsonContent(await client.endpoints.previewEmailFields(slug, { requestId, emailFields }))
+    )
+  );
   server.tool(
     "preview_response",
     "Dry run of an endpoint's responses: which response rule answers a captured request, and the response with its {{ placeholders }} filled in, exactly as the receiver would send it. Nothing is sent. Pass mockResponse or responseRules to try settings before saving them with update_endpoint.",
@@ -1518,56 +1749,95 @@ function registerTools(target, client, options = {}) {
   );
   server.tool(
     "search_requests",
-    "Search captured webhook requests across endpoints using retained full-text search.",
+    "Search captured requests and emails across endpoints: a substring match on path, headers, body and decoded email fields. One call reads back through history for about 2 seconds and returns { requests, complete, searchedUntil, cursor }. When complete is false, older requests were not searched yet: call again with the cursor and the same filters to continue.",
     {
       slug: import_zod2.z.string().optional().describe("Filter to a specific endpoint slug"),
       method: import_zod2.z.string().optional().describe("Filter by HTTP method"),
       kind: kindSchema,
-      q: import_zod2.z.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"'),
+      q: import_zod2.z.string().optional().describe(
+        "Substring to find in the path, headers, body and decoded email fields (up to 1,000 characters)"
+      ),
+      from: durationOrTimestampSchema.optional().describe(
+        'Start time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      to: durationOrTimestampSchema.optional().describe(
+        'End time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
       limit: import_zod2.z.number().int().min(1).max(200).default(50).describe("Max results to return"),
-      offset: import_zod2.z.number().int().min(0).max(1e4).default(0).describe("Result offset"),
-      order: import_zod2.z.enum(["asc", "desc"]).default("desc").describe("Sort order by received time")
+      offset: import_zod2.z.number().int().min(0).max(1e4).default(0).describe("Matches to skip (first call only; a cursor carries what is left of it)"),
+      order: import_zod2.z.enum(["asc", "desc"]).default("desc").describe("Sort order by received time"),
+      cursor: import_zod2.z.string().optional().describe(
+        "The cursor from a previous search_requests result, to continue that search. Keep the other inputs the same."
+      )
     },
-    withErrorHandling(async ({ slug, method, kind, q, from, to, limit, offset, order }) => {
-      const results = await client.requests.search({
-        slug,
-        method,
-        kind,
-        q,
-        from,
-        to,
-        limit,
-        offset,
-        order
-      });
-      return jsonContent(results.map(compactRequest));
+    withErrorHandling(async ({ slug, method, kind, q, from, to, limit, offset, order, cursor }) => {
+      const page = await client.requests.searchPage(
+        { slug, method, kind, q, from, to, limit, offset, order },
+        { cursor }
+      );
+      const searchedUntil = isoTime(page.searchedUntil);
+      const envelope = (requests2, shortened) => {
+        const notes = [
+          ...page.complete ? [] : [searchStoppedNote(searchedUntil, order, Boolean(page.cursor))],
+          ...shortened ? [SEARCH_SHORTENED_NOTE] : []
+        ];
+        return {
+          requests: requests2,
+          complete: page.complete,
+          searchedUntil,
+          cursor: page.cursor,
+          ...notes.length > 0 ? { note: notes.join(" ") } : {}
+        };
+      };
+      const requests = page.requests.map(compactRequest);
+      if (jsonSize(envelope(requests, false)) <= MAX_BODY_SIZE) {
+        return jsonContent(envelope(requests, false));
+      }
+      const room = MAX_BODY_SIZE - jsonSize(envelope([], true)) - 8;
+      return jsonContent(envelope(fitSearchRequests(requests, room), true));
     })
   );
   server.tool(
     "count_requests",
-    "Count captured webhook requests that match the given filters.",
+    "Count captured requests and emails that match the given filters (q is a substring match on path, headers, body and decoded email fields). Returns { count, exact, searchedUntil, cursor }. With q or method a call counts back through history for about 2 seconds: when exact is false, count covers history back to searchedUntil only, and calling again with the cursor counts the next stretch (add the counts up).",
     {
       slug: import_zod2.z.string().optional().describe("Filter to a specific endpoint slug"),
       method: import_zod2.z.string().optional().describe("Filter by HTTP method"),
       kind: kindSchema,
-      q: import_zod2.z.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"')
+      q: import_zod2.z.string().optional().describe(
+        "Substring to find in the path, headers, body and decoded email fields (up to 1,000 characters)"
+      ),
+      from: durationOrTimestampSchema.optional().describe(
+        'Start time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      to: durationOrTimestampSchema.optional().describe(
+        'End time as a timestamp (Unix ms) or a duration back from now like "1h" or "7d". A duration is counted from each call, so when you continue with a cursor pass a timestamp to keep the same range.'
+      ),
+      cursor: import_zod2.z.string().optional().describe(
+        "The cursor from a previous count_requests result, to count the next stretch. Keep the other inputs the same."
+      )
     },
-    withErrorHandling(async ({ slug, method, kind, q, from, to }) => {
-      const count = await client.requests.count({ slug, method, kind, q, from, to });
-      return jsonContent({ count });
+    withErrorHandling(async ({ slug, method, kind, q, from, to, cursor }) => {
+      const page = await client.requests.countPage({ slug, method, kind, q, from, to }, { cursor });
+      const searchedUntil = isoTime(page.searchedUntil);
+      return jsonContent({
+        count: page.count,
+        exact: page.exact,
+        searchedUntil,
+        cursor: page.cursor,
+        ...page.exact ? {} : {
+          note: `At least ${page.count}, counted ${searchedUntil ? `back to ${searchedUntil}` : "over part of the history"}; ${page.cursor ? "call count_requests again with cursor to count further (the counts add up)." : "there is no cursor to count further with."}`
+        }
+      });
     })
   );
   server.tool(
     "get_request",
-    "Get full details for a specific captured request by ID.",
+    "Get the details of a captured request by ID: method, path, headers and body. A request larger than the tool output has its body cut (bodyTruncated, bodySize) and a note saying where the whole request is available.",
     getRequestShape,
     withErrorHandling(async ({ requestId }) => {
       const request = await client.requests.get(requestId);
-      return jsonContent(compactRequest(request));
+      return requestContent(request);
     })
   );
   server.tool(
@@ -1576,7 +1846,7 @@ function registerTools(target, client, options = {}) {
     waitForRequestShape,
     withErrorHandling(async ({ endpointSlug, timeout, pollInterval }) => {
       const request = await client.requests.waitFor(endpointSlug, { timeout, pollInterval });
-      return jsonContent(compactRequest(request));
+      return requestContent(request);
     })
   );
   server.tool(
@@ -2330,7 +2600,7 @@ function registerTools(target, client, options = {}) {
   );
   server.tool(
     "wait_for_approval",
-    "Wait for the account's owner to answer an approval (from create_api_key, create_share_link, remove_domain, rename_account, connect_google, pick_spreadsheet or ai_setup) and collect what it grants or did, such as the new API key, the share link or AI setup's proposals. If they have not answered yet, call it again.",
+    "Wait for the account's owner to answer an approval (from create_api_key, create_share_link, remove_domain, rename_account, delete_team, invite_to_team, connect_google, pick_spreadsheet or ai_setup) and collect what it grants or did, such as the new API key, the share link or AI setup's proposals. If they have not answered yet, call it again.",
     {
       id: import_zod2.z.string().describe("The approval id"),
       timeout: durationOrTimestampSchema.default("45s").describe('How long to wait for the person, for example "45s"')