@webhooks-cc/mcp 1.24.0 → 2.0.0

package/dist/index.mjs

@@ -1,37 +1,229 @@
 import {
+  ENABLE_TOOLS,
   REMOTE_MAX_WAIT_MS,
+  TOOL_CATALOG,
+  TOOL_GROUPS,
+  TOOL_GROUP_NAMES,
+  clientLoadsEverything,
   compactRequest,
   createEndpointShape,
+  defaultToolGroups,
   deleteEndpointShape,
   getEndpointShape,
   getRequestShape,
   jsonContent,
   listEndpointsShape,
   listRequestsShape,
+  parseToolGroups,
   payloadSchemaResult,
   payloadSchemaShape,
   registerTools,
+  toolAnnotations,
+  toolTitle,
   waitForRequestShape,
   withErrorHandling
-} from "./chunk-SOQIUGLA.mjs";
+} from "./chunk-VANGXSK7.mjs";
 
 // src/index.ts
-import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { WebhooksCC as WebhooksCC2 } from "@webhooks-cc/sdk";
 
-// src/prompts.ts
+// src/local-tools.ts
+import { CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
 import { z } from "zod";
+function asToolServer(server) {
+  return {
+    tool(name, description, shape, handler, annotations) {
+      const registered = server.registerTool(
+        name,
+        {
+          title: annotations?.title,
+          description,
+          inputSchema: z.object(shape),
+          annotations
+        },
+        async (args) => handler(args)
+      );
+      return { remove: () => registered.remove() };
+    }
+  };
+}
+var warned = /* @__PURE__ */ new Set();
+function toolSelection(options = {}) {
+  const fromOption = options.tools !== void 0;
+  const parsed = parseToolGroups(fromOption ? options.tools : process.env.WHK_MCP_TOOLS);
+  const setting = fromOption ? options.tools : process.env.WHK_MCP_TOOLS;
+  if (parsed && parsed.unknown.length > 0 && !warned.has(setting ?? "")) {
+    warned.add(setting ?? "");
+    console.error(
+      `webhooks-cc-mcp: unknown tool groups in ${fromOption ? "tools" : "WHK_MCP_TOOLS"}: ${parsed.unknown.join(", ")} (known: all, ${TOOL_GROUP_NAMES.join(", ")})`
+    );
+  }
+  const readOnly = options.readOnly ?? /^(1|true|yes|on)$/i.test((process.env.WHK_MCP_READ_ONLY ?? "").trim());
+  return { groups: parsed?.groups ?? null, readOnly };
+}
+var EXTRA_GROUPS = TOOL_GROUP_NAMES.filter((group) => group !== "core");
+var ENABLE_TOOLS_ANNOTATIONS = {
+  title: toolTitle(ENABLE_TOOLS),
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var LocalToolGroups = class {
+  constructor(server, selection) {
+    this.server = server;
+    this.selection = selection;
+    this.client = null;
+    this.loaded = /* @__PURE__ */ new Set();
+    this.handles = [];
+    this.enableTools = null;
+    this.clientKnown = false;
+  }
+  /** The groups an account's tools start with. */
+  startingGroups() {
+    if (this.selection.groups) return [...this.selection.groups];
+    return this.clientKnown && clientLoadsEverything(this.clientName) ? [...TOOL_GROUP_NAMES] : ["core"];
+  }
+  /** Registers the tools for an account; the handle removes them all again. */
+  show(client) {
+    this.hide();
+    this.client = client;
+    this.load(this.startingGroups());
+    return { remove: () => this.hide() };
+  }
+  /** Removes every account tool, enable_tools included. */
+  hide() {
+    for (const handle of this.handles) handle.remove();
+    this.enableTools?.remove();
+    this.handles = [];
+    this.enableTools = null;
+    this.loaded.clear();
+    this.client = null;
+  }
+  /** The groups loaded now. */
+  loadedGroups() {
+    return TOOL_GROUP_NAMES.filter((group) => this.loaded.has(group));
+  }
+  /**
+   * The client named itself (initialize, or a 2026-07-28 request's _meta).
+   * Without a WHK_MCP_TOOLS setting, a client that takes long tool lists
+   * gets every group. Only the first name counts.
+   */
+  clientIdentified(name) {
+    if (this.clientKnown) return;
+    this.clientKnown = true;
+    this.clientName = name;
+    if (this.selection.groups || !clientLoadsEverything(name)) return;
+    if (this.client) this.load(TOOL_GROUP_NAMES);
+  }
+  /** Registers the groups not loaded yet; returns the tools each one added. */
+  load(groups) {
+    const client = this.client;
+    const fresh = groups.filter((group) => !this.loaded.has(group));
+    if (!client || fresh.length === 0) return {};
+    const added = {};
+    for (const group of fresh) added[group] = [];
+    const server = this.server;
+    const recorder = {
+      tool(name, description, shape, handler, annotations) {
+        added[TOOL_CATALOG[name].group]?.push(name);
+        return server.tool(name, description, shape, handler, annotations);
+      }
+    };
+    this.handles.push(
+      ...registerTools(recorder, client, {
+        groups: new Set(fresh),
+        readOnly: this.selection.readOnly
+      })
+    );
+    for (const group of fresh) this.loaded.add(group);
+    this.showEnableTools();
+    return added;
+  }
+  /** (Re)registers enable_tools with the current groups, or drops it once all are loaded. */
+  showEnableTools() {
+    this.enableTools?.remove();
+    this.enableTools = null;
+    const left = EXTRA_GROUPS.filter((group) => !this.loaded.has(group));
+    if (!this.client || left.length === 0) return;
+    const lines = EXTRA_GROUPS.map(
+      (group) => `- ${group}${this.loaded.has(group) ? " (loaded)" : ""}: ${TOOL_GROUPS[group]}`
+    );
+    const description = [
+      "Load more webhooks.cc tools into this session. This server lists its core tools by default; the rest come in groups. If a tool you need is missing, load its group, then look at the tool list again.",
+      "Groups:",
+      ...lines,
+      this.selection.readOnly ? "This server is read-only (WHK_MCP_READ_ONLY): a group brings only its tools that change nothing." : null
+    ].filter(Boolean).join("\n");
+    this.enableTools = this.server.tool(
+      ENABLE_TOOLS,
+      description,
+      {
+        groups: z.array(z.enum([...EXTRA_GROUPS, "all"])).min(1).describe('Groups to load, or ["all"]')
+      },
+      withErrorHandling(async ({ groups }) => {
+        const wanted = groups.includes("all") ? [...TOOL_GROUP_NAMES] : groups;
+        const already = wanted.filter((group) => group !== "core" && this.loaded.has(group));
+        const added = this.load(wanted);
+        const loadedNow = Object.keys(added).length > 0;
+        return jsonContent({
+          added,
+          ...already.length > 0 ? { alreadyLoaded: [...new Set(already)] } : {},
+          loaded: this.loadedGroups(),
+          ...this.selection.readOnly ? { readOnly: true } : {},
+          note: loadedNow ? "The tool list changed. If your client does not show the new tools, ask the user to set WHK_MCP_TOOLS (for example all) and restart the server." : "Nothing new to load."
+        });
+      }),
+      ENABLE_TOOLS_ANNOTATIONS
+    );
+  }
+};
+function modernClientName(message) {
+  if (typeof message !== "object" || message === null) return null;
+  const params = message.params;
+  const info = params?._meta?.[CLIENT_INFO_META_KEY];
+  if (typeof info !== "object" || info === null) return null;
+  const name = info.name;
+  return typeof name === "string" ? name : void 0;
+}
+function watchClient(server, groups) {
+  const low = server.server;
+  const initialized = low.oninitialized;
+  low.oninitialized = () => {
+    initialized?.();
+    groups.clientIdentified(low.getClientVersion()?.name);
+  };
+  const connect = server.connect.bind(server);
+  server.connect = async (transport) => {
+    const previous = transport.onmessage;
+    transport.onmessage = (message, extra) => {
+      const name = modernClientName(message);
+      if (name !== null) groups.clientIdentified(name);
+      previous?.call(transport, message, extra);
+    };
+    return connect(transport);
+  };
+}
+function localToolGroups(server, selection) {
+  const groups = new LocalToolGroups(asToolServer(server), selection);
+  watchClient(server, groups);
+  return groups;
+}
+
+// src/prompts.ts
+import { z as z2 } 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")
-      }
+      argsSchema: z2.object({
+        provider: z2.string().optional().describe("Webhook provider, if known"),
+        endpointSlug: z2.string().optional().describe("Hosted endpoint slug, if known"),
+        targetUrl: z2.string().optional().describe("Your app's receiving URL, if known")
+      })
     },
     async ({ provider, endpointSlug, targetUrl }) => {
       const scope = [
@@ -67,10 +259,10 @@ function registerPrompts(server) {
     {
       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")
-      }
+      argsSchema: z2.object({
+        provider: z2.string().describe("Webhook provider to test"),
+        targetUrl: z2.string().optional().describe("Optional local or remote target URL")
+      })
     },
     async ({ provider, targetUrl }) => {
       return {
@@ -101,11 +293,11 @@ function registerPrompts(server) {
     {
       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")
-      }
+      argsSchema: z2.object({
+        endpointSlug: z2.string().optional().describe("Endpoint slug to inspect for recent attempts"),
+        leftRequestId: z2.string().optional().describe("First request ID, if already known"),
+        rightRequestId: z2.string().optional().describe("Second request ID, if already known")
+      })
     },
     async ({ endpointSlug, leftRequestId, rightRequestId }) => {
       return {
@@ -131,7 +323,7 @@ function registerPrompts(server) {
 }
 
 // src/resources.ts
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
 var ENDPOINTS_RESOURCE_URI = "webhooks://endpoints";
 var ENDPOINT_RECENT_TEMPLATE_URI = "webhooks://endpoint/{slug}/recent";
 var REQUEST_TEMPLATE_URI = "webhooks://request/{id}";
@@ -253,7 +445,7 @@ function registerResources(server, client) {
 }
 
 // src/sandbox-tools.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 import {
   AgentAuthError,
   AgentCredentialStore,
@@ -262,7 +454,7 @@ import {
 } from "@webhooks-cc/sdk";
 
 // src/version.ts
-var VERSION = true ? "1.24.0" : "0.0.0-dev";
+var VERSION = true ? "2.0.0" : "0.0.0-dev";
 var MCP_USER_AGENT = `webhooks-cc-mcp/${VERSION}`;
 
 // src/sandbox-tools.ts
@@ -379,6 +571,8 @@ function registerSandboxTools(server, options = {}) {
     options.clientName ?? "webhooks-cc-mcp",
     options.credentialsFile
   );
+  const target = asToolServer(server);
+  const groups = options.toolGroups ?? localToolGroups(server, toolSelection(options));
   let handles = [];
   let shown = 0;
   const swap = (register) => {
@@ -386,7 +580,9 @@ function registerSandboxTools(server, options = {}) {
     for (const handle of handles) handle.remove();
     handles = register(id);
   };
-  const showSandbox = () => swap(() => sandboxToolSet(server, session, showAccount));
+  const showSandbox = () => swap(
+    () => sandboxToolSet(sandboxTarget(target, groups.selection.readOnly), session, showAccount, groups)
+  );
   const savedAccount = (id) => options.credentialsFile === false ? null : WebhooksCC.fromSavedConnection({
     baseUrl,
     webhookUrl,
@@ -399,18 +595,54 @@ function registerSandboxTools(server, options = {}) {
     })
   });
   function showAccount(client) {
-    swap((id) => registerTools(server, savedAccount(id) ?? client));
+    swap((id) => [groups.show(savedAccount(id) ?? client)]);
     options.onConnected?.(client);
   }
   const saved = savedAccount(1);
   if (saved) {
-    swap(() => registerTools(server, saved));
+    swap(() => [groups.show(saved)]);
     options.onConnected?.(saved);
   } else {
     showSandbox();
   }
 }
-function sandboxToolSet(server, session, showAccount) {
+var SANDBOX_ONLY_TOOLS = {
+  // A new code each time.
+  connect_account: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false
+  },
+  // Changes this session's tools once the human has connected.
+  wait_for_connection: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  },
+  about_sandbox: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+};
+var CONNECT_TOOLS = /* @__PURE__ */ new Set(["connect_account", "wait_for_connection"]);
+function sandboxTarget(target, readOnly) {
+  return {
+    tool(name, description, shape, handler) {
+      const own = SANDBOX_ONLY_TOOLS[name];
+      const annotations = own ? { title: toolTitle(name), ...own } : toolAnnotations(name);
+      if (readOnly && !annotations.readOnlyHint && !CONNECT_TOOLS.has(name)) {
+        return { remove() {
+        } };
+      }
+      return target.tool(name, description, shape, handler, annotations);
+    }
+  };
+}
+function sandboxToolSet(server, session, showAccount, groups) {
   const tools = [];
   const limits = `up to ${SANDBOX.maxEndpoints} endpoints at a time, ${SANDBOX.requestsPerEndpoint} captured requests each and ${SANDBOX.requests} in all, deleted ${SANDBOX.lifetimeHours} hours after the sandbox was created`;
   const file = savedTo(session.credentialsFile);
@@ -525,7 +757,7 @@ function sandboxToolSet(server, session, showAccount) {
       "connect_account",
       "Connect this agent to a human's webhooks.cc account, for the full tool set (mock responses, signatures, email, teams) and to keep the sandbox endpoints. Returns a link and a 6-digit code: show both to the human, who signs in or signs up with that email and enters the code. Then call wait_for_connection. Calling again gives a new code.",
       {
-        email: z2.string().email({ message: "Invalid email address" }).describe(
+        email: z3.string().email({ message: "Invalid email address" }).describe(
           "The email the human signs in to webhooks.cc with (their GitHub or Google primary email if they sign in that way); only someone signed in as it can connect"
         )
       },
@@ -578,7 +810,7 @@ function sandboxToolSet(server, session, showAccount) {
       "wait_for_connection",
       `Wait for the human to enter the code from connect_account. On success the full webhooks.cc tools for their account replace these sandbox tools. Returns after timeoutSeconds (default ${DEFAULT_WAIT_SECONDS}) if they have not finished yet; call it again to keep waiting.`,
       {
-        timeoutSeconds: z2.number().int().min(1).max(MAX_WAIT_SECONDS).optional().describe(`How long to wait, in seconds (default ${DEFAULT_WAIT_SECONDS})`)
+        timeoutSeconds: z3.number().int().min(1).max(MAX_WAIT_SECONDS).optional().describe(`How long to wait, in seconds (default ${DEFAULT_WAIT_SECONDS})`)
       },
       withErrorHandling(async ({ timeoutSeconds }) => {
         const pending = session.connect;
@@ -621,7 +853,7 @@ function sandboxToolSet(server, session, showAccount) {
         return jsonContent({
           connected: true,
           email: pending.email,
-          message: `Connected to the webhooks.cc account of ${pending.email}. The full tool set has replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${movedEndpoints ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} ${file ? `The connection is saved in ${file}, so later sessions, the whk CLI and the SDKs start connected; it lasts 90 days, and the human can remove it under Account, Connected agents.` : "This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY."}`
+          message: `Connected to the webhooks.cc account of ${pending.email}. The account's tools have replaced the sandbox tools (the tool list changed; if your client does not pick that up, ask the user to restart it).${groups.loadedGroups().length < TOOL_GROUP_NAMES.length ? " More tools load in groups: see enable_tools." : ""}${movedEndpoints ? " The sandbox endpoints are now that account's endpoints, with what they captured." : ""} ${file ? `The connection is saved in ${file}, so later sessions, the whk CLI and the SDKs start connected; it lasts 90 days, and the human can remove it under Account, Connected agents.` : "This connection lasts while this MCP server runs; for a lasting setup, the human can create an API key under Account and set WHK_API_KEY."}`
         });
       })
     )
@@ -663,32 +895,56 @@ function registerAgentRegistrationTools(server) {
 }
 
 // src/index.ts
+var INSTRUCTIONS = "webhooks.cc captures webhooks and inbound email for testing. Start with create_endpoint, send to its URL (or point a provider at it), then wait_for_request and get_request to inspect what arrived. send_webhook sends a signed test webhook to an endpoint; verify_signature checks a captured request. With an account the tools come in groups: when a tool you need is missing, enable_tools loads its group (teams, domains, Google Sheets, billing and keys, and more).";
 function createServer(options = {}) {
   const apiKey = options.apiKey ?? process.env.WHK_API_KEY;
   const webhookUrl = options.webhookUrl ?? process.env.WHK_WEBHOOK_URL;
   const baseUrl = options.baseUrl ?? process.env.WHK_BASE_URL;
-  const server = new McpServer2(
-    { name: "webhooks-cc", version: VERSION },
-    // Connecting an account swaps every tool at once: one list_changed, not dozens.
-    { debouncedNotificationMethods: ["notifications/tools/list_changed"] }
+  const server = new McpServer(
+    { name: "webhooks-cc", title: "webhooks.cc", version: VERSION },
+    {
+      capabilities: { tools: { listChanged: true } },
+      instructions: INSTRUCTIONS,
+      // Connecting an account or loading groups changes many tools at once:
+      // one list_changed, not dozens.
+      debouncedNotificationMethods: ["notifications/tools/list_changed"]
+    }
   );
+  const groups = localToolGroups(server, toolSelection(options));
   if (!apiKey) {
-    registerSandboxTools(server, { baseUrl, webhookUrl, credentialsFile: options.credentialsFile });
+    registerSandboxTools(server, {
+      baseUrl,
+      webhookUrl,
+      credentialsFile: options.credentialsFile,
+      toolGroups: groups
+    });
     registerPrompts(server);
     return server;
   }
   const client = new WebhooksCC2({ apiKey, webhookUrl, baseUrl, userAgent: MCP_USER_AGENT });
-  registerTools(server, client);
+  groups.show(client);
   registerPrompts(server);
   registerResources(server, client);
   return server;
 }
 export {
+  ENABLE_TOOLS,
+  LocalToolGroups,
   REMOTE_MAX_WAIT_MS,
+  TOOL_CATALOG,
+  TOOL_GROUPS,
+  TOOL_GROUP_NAMES,
+  asToolServer,
+  clientLoadsEverything,
   createServer,
+  defaultToolGroups,
+  localToolGroups,
+  parseToolGroups,
   registerAgentRegistrationTools,
   registerPrompts,
   registerResources,
   registerSandboxTools,
-  registerTools
+  registerTools,
+  toolAnnotations,
+  toolSelection
 };