@webhooks-cc/mcp 1.24.0 → 2.0.0

package/dist/{chunk-SOQIUGLA.mjs → chunk-VANGXSK7.mjs}

@@ -241,6 +241,209 @@ function compactRequest(request) {
   return compact;
 }
 
+// src/catalog.ts
+var TOOL_GROUPS = {
+  core: "Endpoints, captured requests and emails, sending test webhooks, signatures, forwarding destinations, deliveries, previews of your local app and their logs, usage and approvals",
+  forwarding: "The rest of forwarding: preview what a destination would send, the endpoint's forwarding settings and signing secret, test deliveries",
+  layouts: "Email layouts and named fields: try layouts and fields on a captured email, add ready-made layouts, and AI setup",
+  extras: "Bulk endpoint changes, favourites, request counts and payload schemas",
+  teams: "Teams: members, invites, sharing endpoints with a team, and pricing team changes",
+  account: "The account: billing, API keys, connected agents, public share links to requests, and the display name",
+  domains: "Custom inbound email domains: add, verify, route and remove them",
+  sheets: "Google Sheets destinations: Google accounts, spreadsheets and their tabs",
+  names: "Preview names: reserve, release and password-protect them"
+};
+var TOOL_GROUP_NAMES = Object.keys(TOOL_GROUPS);
+var read = { readOnly: true };
+var write = {};
+var update = { idempotent: true };
+var remove = { destructive: true, idempotent: true };
+var replace = { destructive: true, idempotent: true };
+var outward = { openWorld: true };
+function group(name, tools) {
+  return Object.fromEntries(
+    Object.entries(tools).map(([tool, behaviour]) => [tool, { group: name, ...behaviour }])
+  );
+}
+var TOOL_CATALOG = {
+  ...group("core", {
+    create_endpoint: write,
+    list_endpoints: read,
+    get_endpoint: read,
+    // Replaces what it is given (a mock response, the signing secret).
+    update_endpoint: replace,
+    delete_endpoint: remove,
+    list_requests: read,
+    search_requests: read,
+    get_request: read,
+    wait_for_request: read,
+    wait_for_requests: read,
+    replay_request: outward,
+    compare_requests: read,
+    extract_from_request: read,
+    clear_requests: remove,
+    send_webhook: write,
+    send_to: outward,
+    test_webhook_flow: outward,
+    preview_webhook: read,
+    preview_response: read,
+    list_provider_templates: read,
+    verify_signature: read,
+    list_emails: read,
+    get_email: read,
+    wait_for_email: read,
+    send_test_email: write,
+    render_email: outward,
+    list_destinations: read,
+    add_destination: write,
+    update_destination: replace,
+    remove_destination: remove,
+    list_deliveries: read,
+    redeliver: outward,
+    share_port: outward,
+    list_shares: read,
+    share_requests: read,
+    stop_share: remove,
+    get_usage: read,
+    // Collecting an approved key hands it over once: not a pure read.
+    wait_for_approval: write,
+    describe: read
+  }),
+  ...group("forwarding", {
+    preview_destination: read,
+    configure_forwarding: replace,
+    // rotate: true replaces the secret, and receivers holding the old one fail.
+    get_forwarding_secret: { destructive: true },
+    test_forwarding: outward
+  }),
+  ...group("layouts", {
+    preview_layouts: read,
+    list_layout_templates: read,
+    add_layout_template: write,
+    preview_email_fields: read,
+    ai_setup_status: read,
+    // Sends the chosen emails to Anthropic once the owner approves.
+    ai_setup: outward
+  }),
+  ...group("extras", {
+    create_endpoints: write,
+    delete_endpoints: remove,
+    favorite_endpoint: update,
+    count_requests: read,
+    generate_payload_schema: read
+  }),
+  ...group("teams", {
+    list_teams: read,
+    list_team_members: read,
+    share_endpoint: update,
+    unshare_endpoint: remove,
+    create_team: write,
+    rename_team: update,
+    delete_team: remove,
+    remove_team_member: remove,
+    leave_team: remove,
+    invite_to_team: outward,
+    list_invites: read,
+    answer_invite: write,
+    withdraw_invite: remove,
+    quote_team_change: read
+  }),
+  ...group("account", {
+    get_billing: read,
+    list_api_keys: read,
+    create_api_key: write,
+    revoke_api_key: remove,
+    rename_account: update,
+    list_connected_agents: read,
+    disconnect_agent: remove,
+    list_share_links: read,
+    create_share_link: write,
+    revoke_share_link: remove
+  }),
+  ...group("domains", {
+    list_domains: read,
+    add_domain: write,
+    // A failed check counts toward lapsing a verified domain: not safe to repeat.
+    verify_domain: { destructive: true },
+    // Replaces the routing; a missing catch-all refuses mail.
+    route_domain: replace,
+    remove_domain: remove
+  }),
+  ...group("sheets", {
+    list_google_connections: read,
+    connect_google: outward,
+    pick_spreadsheet: outward,
+    create_spreadsheet: outward,
+    list_sheet_tabs: { readOnly: true, openWorld: true },
+    disconnect_google: remove
+  }),
+  ...group("names", {
+    // The log of what visitors asked a running preview for.
+    list_names: read,
+    reserve_name: write,
+    release_name: remove,
+    set_name_password: update,
+    // Opens the name to anyone again.
+    clear_name_password: { destructive: true, idempotent: true }
+  })
+};
+var ENABLE_TOOLS = "enable_tools";
+function toolAnnotations(name) {
+  const entry = TOOL_CATALOG[name];
+  const readOnly = entry?.readOnly === true;
+  return {
+    title: toolTitle(name),
+    readOnlyHint: readOnly,
+    // MCP reads a missing destructiveHint as true on any tool that writes.
+    destructiveHint: !readOnly && entry?.destructive === true,
+    idempotentHint: readOnly || entry?.idempotent === true,
+    openWorldHint: entry?.openWorld === true
+  };
+}
+function toolTitle(name) {
+  const words = name.split("_").map((word) => TITLE_WORDS[word] ?? word);
+  const first = words[0] ?? "";
+  return [first.charAt(0).toUpperCase() + first.slice(1), ...words.slice(1)].join(" ");
+}
+var TITLE_WORDS = {
+  api: "API",
+  ai: "AI",
+  mcp: "MCP"
+};
+function parseToolGroups(setting) {
+  if (setting === null || setting === void 0 || setting.trim() === "") return null;
+  const groups = /* @__PURE__ */ new Set(["core"]);
+  const unknown = [];
+  for (const raw of setting.split(/[\s,+]+/)) {
+    const name = raw.trim().toLowerCase();
+    if (!name) continue;
+    if (name === "all") {
+      for (const g of TOOL_GROUP_NAMES) groups.add(g);
+    } else if (TOOL_GROUP_NAMES.includes(name)) {
+      groups.add(name);
+    } else {
+      unknown.push(raw.trim());
+    }
+  }
+  return { groups, unknown };
+}
+var LOADS_EVERYTHING = [
+  /^claude-code$/i,
+  /^claude-ai$/i,
+  /^claude$/i,
+  /codex/i,
+  /^openai-mcp$/i,
+  /chatgpt/i
+];
+function clientLoadsEverything(clientName) {
+  if (!clientName) return false;
+  const name = clientName.trim().toLowerCase().replace(/[\s_]+/g, "-");
+  return LOADS_EVERYTHING.some((pattern) => pattern.test(name));
+}
+function defaultToolGroups(clientName) {
+  return clientLoadsEverything(clientName) ? new Set(TOOL_GROUP_NAMES) : /* @__PURE__ */ new Set(["core"]);
+}
+
 // src/tools.ts
 var MAX_BODY_SIZE = MAX_OUTPUT;
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
@@ -927,11 +1130,18 @@ function durationMs(value) {
     return null;
   }
 }
-function toolTarget(target, remote, handles) {
+function toolTarget(target, options, handles) {
+  const remote = options.remote === true;
   return {
     tool(name, description, shape, handler) {
       if (remote && LOCAL_ONLY_TOOLS.has(name)) return { remove() {
       } };
+      const entry = TOOL_CATALOG[name];
+      if (!entry) throw new Error(`${name} has no entry in catalog.ts`);
+      if (options.groups && !options.groups.has(entry.group)) return { remove() {
+      } };
+      if (options.readOnly && entry.readOnly !== true) return { remove() {
+      } };
       const wrapped = remote ? async (args) => {
         const input = args;
         if (TARGET_URL_TOOLS.has(name) && input.targetUrl !== void 0) {
@@ -965,7 +1175,7 @@ function toolTarget(target, remote, handles) {
         }
         return handler(bounded);
       } : handler;
-      const handle = target.tool(name, description, shape, wrapped);
+      const handle = target.tool(name, description, shape, wrapped, toolAnnotations(name));
       handles.push(handle);
       return handle;
     }
@@ -1041,7 +1251,7 @@ function withShareHints(list, remote = false) {
 function registerTools(target, client, options = {}) {
   const handles = [];
   const remote = options.remote === true;
-  const server = toolTarget(target, remote, handles);
+  const server = toolTarget(target, options, handles);
   const shareWith = remote ? REMOTE_SHARE : "share_port";
   server.tool(
     "create_endpoint",
@@ -2743,6 +2953,15 @@ function registerTools(target, client, options = {}) {
 }
 
 export {
+  TOOL_GROUPS,
+  TOOL_GROUP_NAMES,
+  TOOL_CATALOG,
+  ENABLE_TOOLS,
+  toolAnnotations,
+  toolTitle,
+  parseToolGroups,
+  clientLoadsEverything,
+  defaultToolGroups,
   compactRequest,
   createEndpointShape,
   listEndpointsShape,

package/dist/index.d.mts

@@ -1,9 +1,72 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export { REMOTE_MAX_WAIT_MS, RegisterToolsOptions, RegisteredToolHandle, ToolServer, registerTools } from './tools.mjs';
+import { McpServer } from '@modelcontextprotocol/server';
 import { WebhooksCC } from '@webhooks-cc/sdk';
+import { T as ToolGroup, a as ToolServer, R as RegisteredToolHandle } from './tools-Bg9zP80n.mjs';
+export { E as ENABLE_TOOLS, b as REMOTE_MAX_WAIT_MS, c as RegisterToolsOptions, d as TOOL_CATALOG, e as TOOL_GROUPS, f as TOOL_GROUP_NAMES, g as ToolAnnotationsHint, h as clientLoadsEverything, i as defaultToolGroups, p as parseToolGroups, r as registerTools, t as toolAnnotations } from './tools-Bg9zP80n.mjs';
 import 'zod';
 
-interface SandboxToolOptions {
+/**
+ * The local (stdio) server's view of its tools: which groups it loads, and
+ * the enable_tools tool that loads more. The hosted server chooses its own
+ * groups per request and has no enable_tools.
+ */
+/** registerTools' view of a v2 McpServer: each tool with its title and annotations. */
+declare function asToolServer(server: McpServer): ToolServer;
+/** Which tools a local server lists. */
+interface ToolSelection {
+    /** The groups named by WHK_MCP_TOOLS (or the tools option); null to choose by client. */
+    groups: ReadonlySet<ToolGroup> | null;
+    /** Only the tools that change nothing (WHK_MCP_READ_ONLY). */
+    readOnly: boolean;
+}
+interface ToolSelectionOptions {
+    /** Tool groups, such as "all" or "core,teams" (default: WHK_MCP_TOOLS, else by client). */
+    tools?: string;
+    /** Only the tools that change nothing (default: WHK_MCP_READ_ONLY). */
+    readOnly?: boolean;
+}
+/** The selection from the options, else the environment. Unknown group names go to stderr. */
+declare function toolSelection(options?: ToolSelectionOptions): ToolSelection;
+/**
+ * An account's tools on a local server, by group. show() registers the
+ * groups the server starts with (and enable_tools while any group is left),
+ * load() adds groups, and the client's name (clientIdentified) loads every
+ * group for clients that take long tool lists, unless WHK_MCP_TOOLS chose.
+ * Everything registered in one tick reaches the client as one list_changed,
+ * since the server debounces it.
+ */
+declare class LocalToolGroups {
+    private readonly server;
+    readonly selection: ToolSelection;
+    private client;
+    private loaded;
+    private handles;
+    private enableTools;
+    private clientKnown;
+    private clientName;
+    constructor(server: ToolServer, selection: ToolSelection);
+    /** The groups an account's tools start with. */
+    private startingGroups;
+    /** Registers the tools for an account; the handle removes them all again. */
+    show(client: WebhooksCC): RegisteredToolHandle;
+    /** Removes every account tool, enable_tools included. */
+    hide(): void;
+    /** The groups loaded now. */
+    loadedGroups(): ToolGroup[];
+    /**
+     * 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: string | undefined): void;
+    /** Registers the groups not loaded yet; returns the tools each one added. */
+    load(groups: readonly ToolGroup[]): Partial<Record<ToolGroup, string[]>>;
+    /** (Re)registers enable_tools with the current groups, or drops it once all are loaded. */
+    private showEnableTools;
+}
+/** Groups for a server, watching for the client that connects. */
+declare function localToolGroups(server: McpServer, selection: ToolSelection): LocalToolGroups;
+
+interface SandboxToolOptions extends ToolSelectionOptions {
     /** API base URL (default: WHK_BASE_URL or https://webhooks.cc). */
     baseUrl?: string;
     /** Webhook receiver URL (default: WHK_WEBHOOK_URL or https://go.webhooks.cc). */
@@ -18,6 +81,11 @@ interface SandboxToolOptions {
     credentialsFile?: string | false;
     /** Called whenever the tools switch to a human's account, with a client for it. */
     onConnected?: (client: WebhooksCC) => void;
+    /**
+     * The account tools' groups, when the caller already made them for this
+     * server (createServer does); otherwise made from tools and readOnly.
+     */
+    toolGroups?: LocalToolGroups;
 }
 /**
  * Registers the agent tools: the full tools when the credential file holds a
@@ -37,7 +105,7 @@ declare function registerPrompts(server: McpServer): void;
 
 declare function registerResources(server: McpServer, client: WebhooksCC): void;
 
-interface CreateServerOptions {
+interface CreateServerOptions extends ToolSelectionOptions {
     /** 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) */
@@ -52,18 +120,24 @@ interface CreateServerOptions {
     credentialsFile?: string | false;
 }
 /**
- * Create an MCP server with all webhooks.cc tools, prompts, and resources registered.
+ * Create an MCP server with the webhooks.cc tools, prompts, and resources registered.
+ *
+ * Which tools it lists: the groups in `tools` (default WHK_MCP_TOOLS, such
+ * as "all" or "core,teams"); without a setting, the core tools, and every
+ * group for clients that take long tool lists (Claude Code, Codex, ChatGPT)
+ * once they connect. enable_tools loads more groups during a session.
+ * `readOnly` (default WHK_MCP_READ_ONLY) lists only the tools that change
+ * nothing.
  *
  * @example
  * ```ts
  * import { createServer } from "@webhooks-cc/mcp";
- * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ * import { serveStdio } from "@modelcontextprotocol/server/stdio";
  *
- * const server = createServer({ apiKey: "whcc_..." });
- * await server.connect(new StdioServerTransport());
+ * serveStdio(() => createServer({ apiKey: "whcc_..." }));
  * ```
  */
 declare function createServer(options?: CreateServerOptions): McpServer;
 
-export { createServer, registerAgentRegistrationTools, registerPrompts, registerResources, registerSandboxTools };
-export type { CreateServerOptions, SandboxToolOptions };
+export { LocalToolGroups, RegisteredToolHandle, ToolGroup, ToolServer, asToolServer, createServer, localToolGroups, registerAgentRegistrationTools, registerPrompts, registerResources, registerSandboxTools, toolSelection };
+export type { CreateServerOptions, SandboxToolOptions, ToolSelection, ToolSelectionOptions };

package/dist/index.d.ts

@@ -1,9 +1,72 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export { REMOTE_MAX_WAIT_MS, RegisterToolsOptions, RegisteredToolHandle, ToolServer, registerTools } from './tools.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { WebhooksCC } from '@webhooks-cc/sdk';
+import { T as ToolGroup, a as ToolServer, R as RegisteredToolHandle } from './tools-Bg9zP80n.js';
+export { E as ENABLE_TOOLS, b as REMOTE_MAX_WAIT_MS, c as RegisterToolsOptions, d as TOOL_CATALOG, e as TOOL_GROUPS, f as TOOL_GROUP_NAMES, g as ToolAnnotationsHint, h as clientLoadsEverything, i as defaultToolGroups, p as parseToolGroups, r as registerTools, t as toolAnnotations } from './tools-Bg9zP80n.js';
 import 'zod';
 
-interface SandboxToolOptions {
+/**
+ * The local (stdio) server's view of its tools: which groups it loads, and
+ * the enable_tools tool that loads more. The hosted server chooses its own
+ * groups per request and has no enable_tools.
+ */
+/** registerTools' view of a v2 McpServer: each tool with its title and annotations. */
+declare function asToolServer(server: McpServer): ToolServer;
+/** Which tools a local server lists. */
+interface ToolSelection {
+    /** The groups named by WHK_MCP_TOOLS (or the tools option); null to choose by client. */
+    groups: ReadonlySet<ToolGroup> | null;
+    /** Only the tools that change nothing (WHK_MCP_READ_ONLY). */
+    readOnly: boolean;
+}
+interface ToolSelectionOptions {
+    /** Tool groups, such as "all" or "core,teams" (default: WHK_MCP_TOOLS, else by client). */
+    tools?: string;
+    /** Only the tools that change nothing (default: WHK_MCP_READ_ONLY). */
+    readOnly?: boolean;
+}
+/** The selection from the options, else the environment. Unknown group names go to stderr. */
+declare function toolSelection(options?: ToolSelectionOptions): ToolSelection;
+/**
+ * An account's tools on a local server, by group. show() registers the
+ * groups the server starts with (and enable_tools while any group is left),
+ * load() adds groups, and the client's name (clientIdentified) loads every
+ * group for clients that take long tool lists, unless WHK_MCP_TOOLS chose.
+ * Everything registered in one tick reaches the client as one list_changed,
+ * since the server debounces it.
+ */
+declare class LocalToolGroups {
+    private readonly server;
+    readonly selection: ToolSelection;
+    private client;
+    private loaded;
+    private handles;
+    private enableTools;
+    private clientKnown;
+    private clientName;
+    constructor(server: ToolServer, selection: ToolSelection);
+    /** The groups an account's tools start with. */
+    private startingGroups;
+    /** Registers the tools for an account; the handle removes them all again. */
+    show(client: WebhooksCC): RegisteredToolHandle;
+    /** Removes every account tool, enable_tools included. */
+    hide(): void;
+    /** The groups loaded now. */
+    loadedGroups(): ToolGroup[];
+    /**
+     * 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: string | undefined): void;
+    /** Registers the groups not loaded yet; returns the tools each one added. */
+    load(groups: readonly ToolGroup[]): Partial<Record<ToolGroup, string[]>>;
+    /** (Re)registers enable_tools with the current groups, or drops it once all are loaded. */
+    private showEnableTools;
+}
+/** Groups for a server, watching for the client that connects. */
+declare function localToolGroups(server: McpServer, selection: ToolSelection): LocalToolGroups;
+
+interface SandboxToolOptions extends ToolSelectionOptions {
     /** API base URL (default: WHK_BASE_URL or https://webhooks.cc). */
     baseUrl?: string;
     /** Webhook receiver URL (default: WHK_WEBHOOK_URL or https://go.webhooks.cc). */
@@ -18,6 +81,11 @@ interface SandboxToolOptions {
     credentialsFile?: string | false;
     /** Called whenever the tools switch to a human's account, with a client for it. */
     onConnected?: (client: WebhooksCC) => void;
+    /**
+     * The account tools' groups, when the caller already made them for this
+     * server (createServer does); otherwise made from tools and readOnly.
+     */
+    toolGroups?: LocalToolGroups;
 }
 /**
  * Registers the agent tools: the full tools when the credential file holds a
@@ -37,7 +105,7 @@ declare function registerPrompts(server: McpServer): void;
 
 declare function registerResources(server: McpServer, client: WebhooksCC): void;
 
-interface CreateServerOptions {
+interface CreateServerOptions extends ToolSelectionOptions {
     /** 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) */
@@ -52,18 +120,24 @@ interface CreateServerOptions {
     credentialsFile?: string | false;
 }
 /**
- * Create an MCP server with all webhooks.cc tools, prompts, and resources registered.
+ * Create an MCP server with the webhooks.cc tools, prompts, and resources registered.
+ *
+ * Which tools it lists: the groups in `tools` (default WHK_MCP_TOOLS, such
+ * as "all" or "core,teams"); without a setting, the core tools, and every
+ * group for clients that take long tool lists (Claude Code, Codex, ChatGPT)
+ * once they connect. enable_tools loads more groups during a session.
+ * `readOnly` (default WHK_MCP_READ_ONLY) lists only the tools that change
+ * nothing.
  *
  * @example
  * ```ts
  * import { createServer } from "@webhooks-cc/mcp";
- * import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ * import { serveStdio } from "@modelcontextprotocol/server/stdio";
  *
- * const server = createServer({ apiKey: "whcc_..." });
- * await server.connect(new StdioServerTransport());
+ * serveStdio(() => createServer({ apiKey: "whcc_..." }));
  * ```
  */
 declare function createServer(options?: CreateServerOptions): McpServer;
 
-export { createServer, registerAgentRegistrationTools, registerPrompts, registerResources, registerSandboxTools };
-export type { CreateServerOptions, SandboxToolOptions };
+export { LocalToolGroups, RegisteredToolHandle, ToolGroup, ToolServer, asToolServer, createServer, localToolGroups, registerAgentRegistrationTools, registerPrompts, registerResources, registerSandboxTools, toolSelection };
+export type { CreateServerOptions, SandboxToolOptions, ToolSelection, ToolSelectionOptions };