@webmcp-auto-ui/core 0.2.0 → 0.5.0

package/README.md

@@ -8,6 +8,10 @@ W3C WebMCP Draft 2026-03-27 polyfill and MCP Streamable HTTP client. Pure TypeSc
 
 **McpClient** — connects to MCP servers over Streamable HTTP (SSE). Handles `initialize`, `tools/list`, and `tools/call`.
 
+**McpMultiClient** — manages simultaneous connections to multiple MCP servers. Aggregates tool lists and routes `callTool` to the correct server. Useful for apps that connect to several data sources at once (e.g. flex with multi-MCP).
+
+**Prompt caching** — the `cache_control` property is applied on the tools array (not individual tools) to work correctly with Anthropic's prompt caching. This fix ensures cache hits when the tool set is stable across requests.
+
 **createToolGroup** — registers a named group of tools on `navigator.modelContext`. Aborting the group unregisters all tools at once — useful for component lifecycle cleanup.
 
 **sanitizeSchema** — strips JSON Schema keywords that Anthropic's API rejects (`oneOf`, `anyOf`, `allOf`, `$ref`, `if/then/else`). Applied automatically before any LLM call.
@@ -30,6 +34,7 @@ npm install @webmcp-auto-ui/core
 import {
   initializeWebMCPPolyfill,
   McpClient,
+  McpMultiClient,
   createToolGroup,
   textResult, jsonResult,
   listenForAgentCalls,
@@ -52,9 +57,17 @@ const init = await client.connect();
 const tools = await client.listTools();
 const result = await client.callTool('my_tool', { arg: 'value' });
 
+// Multi-server connections
+const multi = new McpMultiClient();
+await multi.addServer('https://mcp1.example.com/mcp');
+await multi.addServer('https://mcp2.example.com/mcp');
+const allTools = multi.listAllTools();      // aggregated from all servers
+const result = await multi.callTool('query_sql', { sql: 'SELECT 1' }); // routes to correct server
+
 // Cleanup
 stop();
 group.abort();
+await multi.disconnectAll();
 ```
 
 ## Types

package/dist/index.d.ts

@@ -7,4 +7,6 @@ export { listenForAgentCalls, stopListening, callToolViaPostMessage, isWebMCPEve
 export { dispatchAndWait, signalCompletion, sanitizeSchema, createToolGroup, } from './utils.js';
 export { textResult, jsonResult, registerSkill, unregisterSkill, getSkill, listSkills, clearSkills, } from './webmcp-helpers.js';
 export type { SkillDef } from './webmcp-helpers.js';
+export { McpMultiClient } from './multi-client.js';
+export type { ConnectedServer } from './multi-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,2BAA2B,EAC3B,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGvE,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,2BAA2B,EAC3B,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGvE,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -12,4 +12,6 @@ export { listenForAgentCalls, stopListening, callToolViaPostMessage, isWebMCPEve
 export { dispatchAndWait, signalCompletion, sanitizeSchema, createToolGroup, } from './utils.js';
 // WebMCP helpers (skill registry + result builders)
 export { textResult, jsonResult, registerSkill, unregisterSkill, getSkill, listSkills, clearSkills, } from './webmcp-helpers.js';
+// Multi-MCP client
+export { McpMultiClient } from './multi-client.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+DAA+D;AAiD/D,aAAa;AACb,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD,WAAW;AACX,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,qBAAqB;AACrB,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,oDAAoD;AACpD,OAAO,EACL,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,+DAA+D;AAiD/D,aAAa;AACb,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD,WAAW;AACX,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,qBAAqB;AACrB,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,sBAAsB,EACtB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,YAAY;AACZ,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,oDAAoD;AACpD,OAAO,EACL,UAAU,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAG7B,mBAAmB;AACnB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/multi-client.d.ts

@@ -0,0 +1,52 @@
+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.
+     * Tools with the same name from different servers are all included.
+     */
+    listAllTools(): AggregatedTool[];
+    /**
+     * Call a tool by name. Automatically routes to the first server (insertion
+     * order) that exposes a tool with the given name.
+     */
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult>;
+    /**
+     * Disconnect from all servers.
+     */
+    disconnectAll(): Promise<void>;
+    /** Number of connected servers. */
+    get serverCount(): number;
+    /** True if at least one server is connected. */
+    get hasConnections(): boolean;
+}
+//# sourceMappingURL=multi-client.d.ts.map

package/dist/multi-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-client.d.ts","sourceRoot":"","sources":["../src/multi-client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EAEd,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAMjF,qBAAa,cAAc;IACzB,oEAAoE;IACpE,OAAO,CAAC,OAAO,CAA4E;IAM3F;;;OAGG;IACG,SAAS,CACb,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAC7C,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAoB9C;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9C;;OAEG;IACH,WAAW,IAAI,eAAe,EAAE;IAQhC;;;;OAIG;IACH,YAAY,IAAI,cAAc,EAAE;IAUhC;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAUpF;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAapC,mCAAmC;IACnC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,gDAAgD;IAChD,IAAI,cAAc,IAAI,OAAO,CAE5B;CACF"}

package/dist/multi-client.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// @webmcp-auto-ui/core — McpMultiClient
+// Manages multiple simultaneous MCP server connections via McpClient instances.
+// Zero dependencies, SSR-safe.
+// ---------------------------------------------------------------------------
+import { McpClient } from './client.js';
+// ---------------------------------------------------------------------------
+// McpMultiClient
+// ---------------------------------------------------------------------------
+export class McpMultiClient {
+    /** Ordered map — insertion order determines first-match priority */
+    servers = new Map();
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Add (or reconnect) an MCP server and return its name + tools.
+     * If the URL is already registered, the old connection is removed first.
+     */
+    async addServer(url, options) {
+        // Reconnect semantics: remove existing connection for this URL
+        if (this.servers.has(url)) {
+            await this.removeServer(url);
+        }
+        const clientOptions = options?.headers
+            ? { headers: options.headers }
+            : undefined;
+        const client = new McpClient(url, clientOptions);
+        const initResult = await client.connect();
+        const tools = await client.listTools();
+        const name = initResult.serverInfo.name;
+        this.servers.set(url, { client, name, tools });
+        return { name, tools };
+    }
+    /**
+     * Remove a server and disconnect its client.
+     */
+    async removeServer(url) {
+        const entry = this.servers.get(url);
+        if (!entry)
+            return;
+        await entry.client.disconnect();
+        this.servers.delete(url);
+    }
+    /**
+     * List all connected servers with their metadata.
+     */
+    listServers() {
+        const result = [];
+        for (const [url, entry] of this.servers) {
+            result.push({ url, name: entry.name, tools: entry.tools });
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    listAllTools() {
+        const result = [];
+        for (const [url, entry] of this.servers) {
+            for (const tool of entry.tools) {
+                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.
+     */
+    async callTool(name, args) {
+        for (const [, entry] of this.servers) {
+            const match = entry.tools.find((t) => t.name === name);
+            if (match) {
+                return entry.client.callTool(name, args);
+            }
+        }
+        throw new Error(`McpMultiClient: no server exposes tool "${name}"`);
+    }
+    /**
+     * Disconnect from all servers.
+     */
+    async disconnectAll() {
+        const promises = [];
+        for (const [, entry] of this.servers) {
+            promises.push(entry.client.disconnect());
+        }
+        await Promise.all(promises);
+        this.servers.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Getters
+    // -------------------------------------------------------------------------
+    /** Number of connected servers. */
+    get serverCount() {
+        return this.servers.size;
+    }
+    /** True if at least one server is connected. */
+    get hasConnections() {
+        return this.servers.size > 0;
+    }
+}
+//# sourceMappingURL=multi-client.js.map

package/dist/multi-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-client.js","sourceRoot":"","sources":["../src/multi-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmcp-auto-ui/core",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "W3C WebMCP polyfill + MCP Streamable HTTP client — zero dependencies, framework-agnostic",
   "license": "AGPL-3.0-or-later",
   "author": "jb@media.mit.edu",

package/src/index.ts

@@ -90,3 +90,7 @@ export {
   clearSkills,
 } from './webmcp-helpers.js';
 export type { SkillDef } from './webmcp-helpers.js';
+
+// Multi-MCP client
+export { McpMultiClient } from './multi-client.js';
+export type { ConnectedServer } from './multi-client.js';

package/src/multi-client.ts

@@ -0,0 +1,140 @@
+// ---------------------------------------------------------------------------
+// @webmcp-auto-ui/core — McpMultiClient
+// Manages multiple simultaneous MCP server connections via McpClient instances.
+// Zero dependencies, SSR-safe.
+// ---------------------------------------------------------------------------
+
+import { McpClient } from './client.js';
+import type {
+  McpTool,
+  McpToolResult,
+  McpClientOptions,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ConnectedServer {
+  url: string;
+  name: string;
+  tools: McpTool[];
+}
+
+export type AggregatedTool = McpTool & { serverUrl: string; serverName: string };
+
+// ---------------------------------------------------------------------------
+// McpMultiClient
+// ---------------------------------------------------------------------------
+
+export class McpMultiClient {
+  /** Ordered map — insertion order determines first-match priority */
+  private servers = new Map<string, { client: McpClient; name: string; tools: McpTool[] }>();
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Add (or reconnect) an MCP server and return its name + tools.
+   * If the URL is already registered, the old connection is removed first.
+   */
+  async addServer(
+    url: string,
+    options?: { headers?: Record<string, string> },
+  ): Promise<{ name: string; tools: McpTool[] }> {
+    // Reconnect semantics: remove existing connection for this URL
+    if (this.servers.has(url)) {
+      await this.removeServer(url);
+    }
+
+    const clientOptions: McpClientOptions | undefined = options?.headers
+      ? { headers: options.headers }
+      : undefined;
+
+    const client = new McpClient(url, clientOptions);
+    const initResult = await client.connect();
+    const tools = await client.listTools();
+
+    const name = initResult.serverInfo.name;
+    this.servers.set(url, { client, name, tools });
+
+    return { name, tools };
+  }
+
+  /**
+   * Remove a server and disconnect its client.
+   */
+  async removeServer(url: string): Promise<void> {
+    const entry = this.servers.get(url);
+    if (!entry) return;
+    await entry.client.disconnect();
+    this.servers.delete(url);
+  }
+
+  /**
+   * List all connected servers with their metadata.
+   */
+  listServers(): ConnectedServer[] {
+    const result: ConnectedServer[] = [];
+    for (const [url, entry] of this.servers) {
+      result.push({ url, name: entry.name, tools: entry.tools });
+    }
+    return result;
+  }
+
+  /**
+   * 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.
+   */
+  listAllTools(): AggregatedTool[] {
+    const result: AggregatedTool[] = [];
+    for (const [url, entry] of this.servers) {
+      for (const tool of entry.tools) {
+        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.
+   */
+  async callTool(name: string, args?: Record<string, unknown>): Promise<McpToolResult> {
+    for (const [, entry] of this.servers) {
+      const match = entry.tools.find((t) => t.name === name);
+      if (match) {
+        return entry.client.callTool(name, args);
+      }
+    }
+    throw new Error(`McpMultiClient: no server exposes tool "${name}"`);
+  }
+
+  /**
+   * Disconnect from all servers.
+   */
+  async disconnectAll(): Promise<void> {
+    const promises: Promise<void>[] = [];
+    for (const [, entry] of this.servers) {
+      promises.push(entry.client.disconnect());
+    }
+    await Promise.all(promises);
+    this.servers.clear();
+  }
+
+  // -------------------------------------------------------------------------
+  // Getters
+  // -------------------------------------------------------------------------
+
+  /** Number of connected servers. */
+  get serverCount(): number {
+    return this.servers.size;
+  }
+
+  /** True if at least one server is connected. */
+  get hasConnections(): boolean {
+    return this.servers.size > 0;
+  }
+}