@webmcp-auto-ui/core 0.5.0 → 2.5.0

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,54 @@
+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;
+/**
+ * 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;
+/**
+ * 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;
+};

package/src/validate.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchema } from './types.js';
+export interface ValidationError {
+    path: string;
+    message: string;
+    keyword: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string): ValidationResult;

package/src/webmcp-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { ToolExecuteResult } from './types.js';
+export declare function textResult(text: string): ToolExecuteResult;
+export declare function jsonResult(data: unknown): ToolExecuteResult;

package/src/webmcp-helpers.ts

@@ -1,11 +1,14 @@
 // ---------------------------------------------------------------------------
 // @webmcp-auto-ui/core — WebMCP helpers
-// Thin layer on top of polyfill.ts: skill registry + result builders.
+// Result builders for tool execute callbacks.
 // Zero additional dependencies. SSR-safe.
+//
+// NOTE: The skill registry that used to live here (SkillDef, registerSkill,
+// unregisterSkill, etc.) has been removed. The canonical skill type and
+// registry now live in @webmcp-auto-ui/sdk (packages/sdk/src/skills/registry.ts).
 // ---------------------------------------------------------------------------
 
-import { executeToolInternal } from './polyfill.js';
-import type { ModelContextTool, ToolExecuteCallback, ToolExecuteResult } from './types.js';
+import type { ToolExecuteResult } from './types.js';
 
 // ---------------------------------------------------------------------------
 // Result builders
@@ -18,63 +21,3 @@ export function textResult(text: string): ToolExecuteResult {
 export function jsonResult(data: unknown): ToolExecuteResult {
   return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
-
-// ---------------------------------------------------------------------------
-// Skill registry
-// ---------------------------------------------------------------------------
-
-export interface SkillDef {
-  id: string;
-  name: string;
-  description: string;
-  component: string;
-  presentation?: string;
-  version?: string;
-  tags?: string[];
-}
-
-const _skills = new Map<string, SkillDef>();
-
-function mcNav(): {
-  registerTool: (t: ModelContextTool & { execute: ToolExecuteCallback }) => void;
-  unregisterTool: (name: string) => void;
-} | null {
-  if (typeof navigator === 'undefined') return null;
-  return (navigator as unknown as Record<string, unknown>).modelContext as ReturnType<typeof mcNav> ?? null;
-}
-
-export function registerSkill(skill: SkillDef): void {
-  _skills.set(skill.id, skill);
-  const mc = mcNav();
-  if (!mc) return;
-  const toolName = `skill__${skill.id}`;
-  try { mc.unregisterTool(toolName); } catch { /* not yet registered */ }
-  mc.registerTool({
-    name: toolName,
-    description: `[Skill] ${skill.name} — ${skill.description}. Component: ${skill.component}.${skill.presentation ? ` Hints: ${skill.presentation}` : ''}`,
-    inputSchema: { type: 'object', properties: {} },
-    execute: () => jsonResult(skill),
-    annotations: { readOnlyHint: true },
-  });
-}
-
-export function unregisterSkill(id: string): void {
-  _skills.delete(id);
-  const mc = mcNav();
-  if (!mc) return;
-  try { mc.unregisterTool(`skill__${id}`); } catch { /* already gone */ }
-}
-
-export function getSkill(id: string): SkillDef | undefined {
-  return _skills.get(id);
-}
-
-export function listSkills(): SkillDef[] {
-  return Array.from(_skills.values());
-}
-
-export function clearSkills(): void {
-  for (const id of Array.from(_skills.keys())) unregisterSkill(id);
-}
-
-export { executeToolInternal };

package/src/webmcp-server.d.ts

@@ -0,0 +1,53 @@
+export interface WebMcpServerOptions {
+    description: string;
+}
+export interface WebMcpToolDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+/** A vanilla renderer: receives a container + data, optionally returns a cleanup function. */
+export type WidgetRenderer = ((container: HTMLElement, data: Record<string, unknown>) => void | (() => void)) | unknown;
+export interface WidgetEntry {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    recipe: string;
+    renderer: WidgetRenderer;
+    group?: string;
+    /** True when the renderer is a plain function (not a framework component). */
+    vanilla: boolean;
+}
+export interface WebMcpServer {
+    readonly name: string;
+    readonly description: string;
+    registerWidget(recipeMarkdown: string, renderer: WidgetRenderer): void;
+    addTool(tool: WebMcpToolDef): void;
+    layer(): {
+        protocol: 'webmcp';
+        serverName: string;
+        description: string;
+        tools: WebMcpToolDef[];
+    };
+    getWidget(name: string): WidgetEntry | undefined;
+    listWidgets(): WidgetEntry[];
+}
+export interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+/**
+ * Parse a markdown file with YAML frontmatter (--- delimited).
+ * Supports: scalars, nested objects (indentation), arrays (- item), inline values.
+ * No external YAML dependency.
+ */
+export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
+/**
+ * Mount a widget into a DOM container by searching registered servers.
+ * If the renderer is a function (vanilla renderer), it is called directly.
+ * Returns an optional cleanup function.
+ * Falls back to a text placeholder if no server provides the widget.
+ */
+export declare function mountWidget(container: HTMLElement, type: string, data: Record<string, unknown>, servers: WebMcpServer[]): (() => void) | void;
+export declare function createWebMcpServer(name: string, options: WebMcpServerOptions): WebMcpServer;