@webhooks-cc/mcp 1.23.0 → 2.0.0

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 };