@webmcp-auto-ui/core 0.5.0 → 2.5.4

package/src/multi-client.d.ts

@@ -0,0 +1,55 @@
+import type { McpTool, McpToolResult } from './types.js';
+export interface ConnectedServer {
+    url: string;
+    name: string;
+    tools: McpTool[];
+}
+export type AggregatedTool = McpTool & {
+    serverUrl: string;
+    serverName: string;
+};
+export declare class McpMultiClient {
+    /** Ordered map — insertion order determines first-match priority */
+    private servers;
+    /**
+     * Add (or reconnect) an MCP server and return its name + tools.
+     * If the URL is already registered, the old connection is removed first.
+     */
+    addServer(url: string, options?: {
+        headers?: Record<string, string>;
+    }): Promise<{
+        name: string;
+        tools: McpTool[];
+    }>;
+    /**
+     * Remove a server and disconnect its client.
+     */
+    removeServer(url: string): Promise<void>;
+    /**
+     * List all connected servers with their metadata.
+     */
+    listServers(): ConnectedServer[];
+    /**
+     * List ALL tools from ALL connected servers.
+     * Each tool is augmented with its origin server URL and name.
+     * Duplicate tool names across servers are prefixed with the server name
+     * (e.g. "wikipedia__search") to satisfy the Claude API uniqueness constraint.
+     */
+    listAllTools(): AggregatedTool[];
+    /**
+     * Call a tool by name. Automatically routes to the correct server.
+     * Supports both plain names ("search") and prefixed names ("wikipedia__search")
+     * for disambiguated duplicates.
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    /**
+     * Disconnect from all servers.
+     */
+    disconnectAll(): Promise<void>;
+    /** Convert a server name to a snake_case prefix for tool name disambiguation. */
+    private normalizeServerName;
+    /** Number of connected servers. */
+    get serverCount(): number;
+    /** True if at least one server is connected. */
+    get hasConnections(): boolean;
+}

package/src/multi-client.ts

@@ -86,29 +86,69 @@ export class McpMultiClient {
   /**
    * List ALL tools from ALL connected servers.
    * Each tool is augmented with its origin server URL and name.
-   * Tools with the same name from different servers are all included.
+   * Duplicate tool names across servers are prefixed with the server name
+   * (e.g. "wikipedia__search") to satisfy the Claude API uniqueness constraint.
    */
   listAllTools(): AggregatedTool[] {
+    // First pass: count occurrences of each tool name across all servers
+    const nameCounts = new Map<string, number>();
+    for (const [, entry] of this.servers) {
+      for (const tool of entry.tools) {
+        nameCounts.set(tool.name, (nameCounts.get(tool.name) ?? 0) + 1);
+      }
+    }
+
+    // Second pass: build result, prefixing duplicates with serverName
     const result: AggregatedTool[] = [];
     for (const [url, entry] of this.servers) {
       for (const tool of entry.tools) {
-        result.push({ ...tool, serverUrl: url, serverName: entry.name });
+        const isDuplicate = (nameCounts.get(tool.name) ?? 0) > 1;
+        if (isDuplicate) {
+          const prefix = this.normalizeServerName(entry.name);
+          result.push({
+            ...tool,
+            name: `${prefix}__${tool.name}`,
+            description: `[${entry.name}] ${tool.description ?? ''}`,
+            serverUrl: url,
+            serverName: entry.name,
+          });
+        } else {
+          result.push({ ...tool, serverUrl: url, serverName: entry.name });
+        }
       }
     }
     return result;
   }
 
   /**
-   * Call a tool by name. Automatically routes to the first server (insertion
-   * order) that exposes a tool with the given name.
+   * Call a tool by name. Automatically routes to the correct server.
+   * Supports both plain names ("search") and prefixed names ("wikipedia__search")
+   * for disambiguated duplicates.
    */
   async callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult> {
+    // 1. Exact match on original tool name (unprefixed)
     for (const [, entry] of this.servers) {
       const match = entry.tools.find((t) => t.name === name);
       if (match) {
         return entry.client.callTool(name, args);
       }
     }
+
+    // 2. Prefixed name: "serverprefix__realToolName"
+    const separatorIdx = name.indexOf('__');
+    if (separatorIdx !== -1) {
+      const prefix = name.slice(0, separatorIdx);
+      const realName = name.slice(separatorIdx + 2);
+      for (const [, entry] of this.servers) {
+        if (this.normalizeServerName(entry.name) === prefix) {
+          const match = entry.tools.find((t) => t.name === realName);
+          if (match) {
+            return entry.client.callTool(realName, args);
+          }
+        }
+      }
+    }
+
     throw new Error(`McpMultiClient: no server exposes tool "${name}"`);
   }
 
@@ -124,6 +164,15 @@ export class McpMultiClient {
     this.servers.clear();
   }
 
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /** Convert a server name to a snake_case prefix for tool name disambiguation. */
+  private normalizeServerName(name: string): string {
+    return name.toLowerCase().replace(/[^a-z0-9_-]+/g, '_').replace(/_{2,}/g, '_').replace(/^_|_$/g, '');
+  }
+
   // -------------------------------------------------------------------------
   // Getters
   // -------------------------------------------------------------------------

package/src/polyfill.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @webmcp-auto-ui/core — WebMCP Polyfill
+ *
+ * Implements the 17 MUST HAVE features of the W3C WebMCP Draft CG Report
+ * (2026-03-27) plus ecosystem extras.
+ *
+ * Architecture: module-level state (no class) for tree-shakability.
+ * Zero external dependencies.
+ *
+ * @license AGPL-3.0-or-later
+ */
+import type { ToolExecuteResult, WebMCPPolyfillOptions } from './types.js';
+/**
+ * Execute a registered tool by name.
+ * Steps:
+ *   1. Look up tool in map
+ *   2. Validate input against inputSchema (Feature 8)
+ *   3. Inject authContext if configured (Extra)
+ *   4. Apply confirmation policy if applicable (Extra)
+ *   5. Create a ModelContextClient (Feature 6)
+ *   6. Call execute(input, client)
+ *   7. Normalize and return the result (Fix 8)
+ */
+export declare function executeToolInternal(name: string, input: Record<string, unknown>): Promise<ToolExecuteResult>;
+/**
+ * Returns true when the browser exposes a native WebMCP implementation
+ * (Chrome 146+ or a compatible browser) — no polyfill needed in that case.
+ */
+export declare function hasNativeWebMCP(): boolean;
+/**
+ * Install the WebMCP polyfill on `navigator.modelContext`.
+ *
+ * Behavior:
+ *  - If native WebMCP is present and `forcePolyfill` is not set, skip install
+ *  - If already installed by us, call cleanupWebMCPPolyfill first then re-install
+ *  - Saves previous property descriptors for restore on cleanup (Fix 7)
+ *  - Installs testing shim per installTestingShim option (Fix 14)
+ *
+ * Throws a SecurityError if called from a non-secure context (HTTP)
+ * unless `options.allowInsecureContext` is true.
+ */
+export declare function initializeWebMCPPolyfill(options?: WebMCPPolyfillOptions): void;
+/**
+ * Remove the WebMCP polyfill from navigator and reset all module state.
+ *
+ * Restores previous property descriptors if they existed (Fix 7).
+ * Call this in your framework's cleanup / onDestroy hook to support
+ * Vite/Svelte HMR without tool duplication on reload.
+ */
+export declare function cleanupWebMCPPolyfill(): void;
+export { initializeWebMCPPolyfill as default };

package/src/types.d.ts

@@ -0,0 +1,331 @@
+export type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+export interface JsonSchemaObject {
+    type?: JsonSchemaType | JsonSchemaType[];
+    title?: string;
+    description?: string;
+    default?: unknown;
+    examples?: unknown[];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    enum?: unknown[];
+    const?: unknown;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number | boolean;
+    exclusiveMaximum?: number | boolean;
+    multipleOf?: number;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    patternProperties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    allOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    not?: JsonSchema;
+    $ref?: string;
+    $schema?: string;
+    $id?: string;
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
+    if?: JsonSchema;
+    then?: JsonSchema;
+    else?: JsonSchema;
+    nullable?: boolean;
+}
+export type JsonSchema = boolean | JsonSchemaObject;
+export interface ToolAnnotations {
+    /** Hint: tool does not modify any state */
+    readOnlyHint?: boolean;
+    /** Hint: tool may modify state in a destructive/irreversible way */
+    destructiveHint?: boolean;
+    /** Hint: calling the tool multiple times with the same args has same effect */
+    idempotentHint?: boolean;
+    /** Hint: tool may interact with external systems (network, disk, etc.) */
+    openWorldHint?: boolean;
+    /** Hint: tool should be used with caution */
+    cautionHint?: boolean;
+    /** Human-readable title (MCP SDK) */
+    title?: string;
+}
+export interface ModelContextTool {
+    /** Unique name, must not be empty */
+    name: string;
+    /** Human-readable description, must not be empty */
+    description: string;
+    /** JSON Schema describing the tool's input parameters */
+    inputSchema?: JsonSchema;
+    /** JSON Schema describing the tool's structured output */
+    outputSchema?: JsonSchema;
+    /** Annotations about tool behavior */
+    annotations?: ToolAnnotations;
+}
+/** Content types returned by a tool */
+export type ToolContentType = 'text' | 'image' | 'resource' | 'error';
+export interface ToolContentText {
+    type: 'text';
+    text: string;
+}
+export interface ToolContentImage {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+export interface ToolContentResource {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export interface ToolContentError {
+    type: 'error';
+    error: string;
+}
+export type ToolContent = ToolContentText | ToolContentImage | ToolContentResource | ToolContentError;
+/** Extensible metadata for tool results */
+export interface ToolResultMetadata {
+    willNavigate?: boolean;
+    [key: string]: unknown;
+}
+export interface ToolExecuteResult {
+    content: ToolContent[];
+    isError?: boolean;
+    /** JSON-serializable structured data (MCP structured output) */
+    structuredContent?: Record<string, unknown>;
+    /** Extensible metadata */
+    _meta?: ToolResultMetadata;
+}
+export interface UserInteractionOptions {
+    /** Human-readable prompt to show the user */
+    prompt?: string;
+    /** Interaction type hint */
+    kind?: 'confirmation' | 'input' | 'choice';
+    /** For 'choice' kind */
+    choices?: string[];
+}
+export interface UserInteractionResult {
+    accepted: boolean;
+    value?: string;
+}
+export interface ModelContextClient {
+    /**
+     * Request user interaction before the tool proceeds.
+     * W3C spec marks this as TODO — placeholder implementation.
+     */
+    requestUserInteraction(options?: UserInteractionOptions): Promise<UserInteractionResult>;
+}
+export type ToolExecuteCallback = (input: Record<string, unknown>, client: ModelContextClient) => Promise<ToolExecuteResult> | ToolExecuteResult;
+export interface ToolRegistrationOptions {
+    /** AbortSignal to auto-unregister the tool when aborted */
+    signal?: AbortSignal;
+}
+export interface RegisteredTool {
+    tool: ModelContextTool;
+    execute: ToolExecuteCallback;
+    /** JSON.stringify'd input schema for fast serialization */
+    serializedInputSchema?: string;
+    registeredAt: number;
+}
+export interface ContextRegistration {
+    tool: ModelContextTool & {
+        execute: ToolExecuteCallback;
+    };
+    options?: ToolRegistrationOptions;
+}
+/** Called with no arguments when the tool set changes (MCP-B spec). */
+export type ToolsChangedCallback = () => void;
+export interface ModelContext {
+    registerTool(tool: ModelContextTool & {
+        execute: ToolExecuteCallback;
+    }, options?: ToolRegistrationOptions): void;
+    unregisterTool(nameOrTool: string | {
+        name: string;
+    }): void;
+    provideContext(registrations: ContextRegistration[]): void;
+    clearContext(): void;
+    registerToolsChangedCallback(callback: ToolsChangedCallback): void;
+}
+/** Info shape returned by modelContextTesting.listTools() */
+export interface ModelContextTestingToolInfo {
+    name: string;
+    description: string;
+    /** Serialized JSON Schema string */
+    inputSchema?: string;
+}
+export interface ModelContextTesting {
+    listTools(): ModelContextTestingToolInfo[];
+    executeTool(toolName: string, inputArgsJson: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    getCrossDocumentScriptToolResult(): Promise<string>;
+}
+export interface AuthContext {
+    userId?: string;
+    tenantId?: string;
+    workspaceId?: string;
+    roles?: string[];
+    [key: string]: unknown;
+}
+export type ConfirmationTier = 'none' | 'warn' | 'block';
+export interface ConfirmationPolicy {
+    /** Require confirmation for destructive tools */
+    destructive?: ConfirmationTier;
+    /** Require confirmation for tools without readOnlyHint */
+    mutating?: ConfirmationTier;
+    /** Require confirmation for all tools */
+    all?: ConfirmationTier;
+}
+export interface WebMCPPolyfillOptions {
+    /**
+     * Force installing the polyfill even when native WebMCP is detected.
+     * Useful for testing.
+     */
+    forcePolyfill?: boolean;
+    /**
+     * Allow running in non-secure contexts (HTTP).
+     * Should only be set to true during development.
+     */
+    allowInsecureContext?: boolean;
+    /**
+     * If true and the environment has no window (SSR/Node),
+     * all polyfill functions become silent no-ops.
+     */
+    degradeGracefully?: boolean;
+    /**
+     * Auth context injected into every tool's input as `_authContext`.
+     */
+    authContext?: AuthContext;
+    /**
+     * Confirmation policy applied before executing tools.
+     */
+    confirmationPolicy?: ConfirmationPolicy;
+    /**
+     * Controls when the testing shim (navigator.modelContextTesting) is installed.
+     * - 'if-missing' (default): install only if navigator.modelContextTesting is not already set
+     * - 'always': always install (overwrite native)
+     * - false: never install
+     */
+    installTestingShim?: 'if-missing' | 'always' | false;
+    /**
+     * If false, skip IIFE auto-initialization even when window.__webMCPPolyfillOptions is set.
+     * Default: true
+     */
+    autoInitialize?: boolean;
+}
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse<T = unknown> {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: T;
+    error?: JsonRpcError;
+}
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+export interface McpCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        listChanged?: boolean;
+        subscribe?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface McpInitializeResult {
+    protocolVersion: string;
+    capabilities: McpCapabilities;
+    serverInfo: McpServerInfo;
+}
+export interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    annotations?: ToolAnnotations;
+}
+export interface McpToolResultContent {
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+    resource?: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+}
+export interface McpToolResult {
+    content: McpToolResultContent[];
+    isError?: boolean;
+}
+export interface McpListToolsResult {
+    tools: McpTool[];
+    nextCursor?: string;
+}
+export interface McpClientOptions {
+    /** Client name sent during initialize */
+    clientName?: string;
+    /** Client version sent during initialize */
+    clientVersion?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Extra headers attached to every request */
+    headers?: Record<string, string>;
+    /** Auto-reconnect on 404 session-expired */
+    autoReconnect?: boolean;
+    /** Max reconnect attempts (default: 3) */
+    maxReconnectAttempts?: number;
+}
+export interface PostMessageBridgeOptions {
+    /** Target origin for postMessage calls (default: '*') */
+    targetOrigin?: string;
+    /** Origins to accept messages from; empty array = accept all */
+    allowedOrigins?: string[];
+}
+export interface WebMCPCallToolEvent {
+    type: 'webmcp:call-tool';
+    callId: string;
+    name: string;
+    args?: Record<string, unknown>;
+}
+export interface WebMCPToolResultEvent {
+    type: 'webmcp:tool-result';
+    callId: string;
+    result: ToolExecuteResult;
+}
+export interface WebMCPToolErrorEvent {
+    type: 'webmcp:tool-error';
+    callId: string;
+    error: string;
+}
+declare global {
+    interface Navigator {
+        modelContext?: ModelContext;
+        modelContextTesting?: ModelContextTesting;
+    }
+}

package/src/utils.d.ts

@@ -0,0 +1,81 @@
+import type { JsonSchema } from './types.js';
+/**
+ * Dispatch a CustomEvent and wait for a completion event.
+ * Solves the "execute must return after UI updates" requirement.
+ *
+ * Pattern: dispatch "tool-action" → UI handles it → UI dispatches "tool-completion-{requestId}"
+ *
+ * @param eventName - Name of the event to dispatch
+ * @param detail - Event detail payload
+ * @param options - Timeout and target
+ * @returns Promise that resolves when the completion event fires
+ */
+export declare function dispatchAndWait<T = unknown>(eventName: string, detail?: Record<string, unknown>, options?: {
+    timeout?: number;
+    successValue?: T;
+    target?: EventTarget;
+}): Promise<T>;
+/**
+ * Helper to signal completion of a dispatchAndWait request.
+ * Call this from your UI handler after the update is done.
+ */
+export declare function signalCompletion(completionEventName: string, detail?: unknown): void;
+export interface SchemaPatch {
+    path: string;
+    type: 'additionalProperties';
+    value: false;
+}
+/**
+ * Sanitize schema AND report patches applied for strict tool use.
+ * Use this when you need visibility into what was changed.
+ */
+export declare function sanitizeSchemaWithReport(schema: JsonSchema): {
+    schema: JsonSchema;
+    patches: SchemaPatch[];
+};
+/**
+ * Strip JSON Schema keywords that cause errors in AI SDKs
+ * (e.g., Vercel AI SDK rejects oneOf/anyOf on non-STRING types).
+ *
+ * Use this before passing tool schemas to LLM providers.
+ */
+export declare function sanitizeSchema(schema: JsonSchema): JsonSchema;
+/**
+ * Flatten nested object schemas into flat key__subkey properties.
+ * Returns { schema, pathMap } where pathMap maps flat keys to nested paths.
+ * Only flattens properties of type "object" with their own properties.
+ */
+export declare function flattenSchema(schema: JsonSchema): {
+    schema: JsonSchema;
+    pathMap: Record<string, string[]>;
+};
+/**
+ * Unflatten params using a pathMap from flattenSchema.
+ * Converts { a__b: 1, a__c: 2, d: 3 } back to { a: { b: 1, c: 2 }, d: 3 }
+ */
+export declare function unflattenParams(params: Record<string, unknown>, pathMap: Record<string, string[]>): Record<string, unknown>;
+/**
+ * Create a named tool group backed by a shared AbortController.
+ * Ergonomic helper for SPA route-based tool registration.
+ *
+ * Usage:
+ *   const group = createToolGroup('search-page');
+ *   group.register(tool1, registerFn);
+ *   group.register(tool2, registerFn);
+ *   // On route change:
+ *   group.abort(); // unregisters all tools in the group
+ */
+export declare function createToolGroup(name: string): {
+    name: string;
+    register: (tool: {
+        name: string;
+        description: string;
+        inputSchema?: JsonSchema;
+        execute: (...args: any[]) => any;
+        annotations?: Record<string, unknown>;
+    }, registerFn: (tool: any, options: {
+        signal: AbortSignal;
+    }) => void) => void;
+    abort: () => void;
+    isAborted: () => boolean;
+};