@frontmcp/plugin-webmcp 1.9.3 → 1.9.5

package/README.md

@@ -38,13 +38,14 @@ An agent's call runs the server's `tools:call-tool` flow, so hooks, authorities,
 
 ## Options
 
-| Option         | Type                                           | Default                   | Description                                                        |
-| -------------- | ---------------------------------------------- | ------------------------- | ------------------------------------------------------------------ |
-| `prefix`       | `string`                                       | `''`                      | Prepended to every exposed tool name, e.g. `'shop.'`.              |
-| `include`      | `(tool) => boolean`                            | all                       | Decides which listed tools are exposed.                            |
-| `exposedTo`    | `string[]`                                     | —                         | Other origins (e.g. an iframe's parent) the tools are offered to.  |
-| `authContext`  | `DirectAuthContext \| () => DirectAuthContext` | anonymous `webmcp` caller | Who the server sees calling. A function is resolved on every call. |
-| `modelContext` | `ModelContext`                                 | `document.modelContext`   | The context to register with: a polyfill, or a test double.        |
+| Option         | Type                                           | Default                   | Description                                                         |
+| -------------- | ---------------------------------------------- | ------------------------- | ------------------------------------------------------------------- |
+| `prefix`       | `string`                                       | `''`                      | Prepended to every exposed tool name, e.g. `'shop.'`.               |
+| `include`      | `(tool) => boolean`                            | all                       | Decides which listed tools are exposed.                             |
+| `exposedTo`    | `string[]`                                     | —                         | Other origins (e.g. an iframe's parent) the tools are offered to.   |
+| `authContext`  | `DirectAuthContext \| () => DirectAuthContext` | anonymous `webmcp` caller | Who the server sees calling. A function is resolved on every call.  |
+| `modelContext` | `ModelContext`                                 | `document.modelContext`   | The context to register with: a polyfill, or a test double.         |
+| `result`       | `'structured' \| 'content' \| 'both'`          | `'structured'`            | What a call resolves to (see [Results](#how-tools-are-translated)). |
 
 ## Choosing which tools agents see
 
@@ -61,9 +62,63 @@ Tools are listed through the `'webmcp'` call surface, so `availableWhen` decides
   `app:tool` becomes `app_tool`), names are cut to 128 characters, and collisions get `_2`, `_3`, …
 - **Annotations.** MCP's `readOnlyHint` maps to `readOnlyHint`. An explicit `destructiveHint: true`
   maps to `consequentialHint`, and an explicit `openWorldHint: true` to `untrustedContentHint`.
-- **Results.** A call resolves to `{ content, structuredContent? }`, without `_meta`.
+- **Results.** An agent reads the whole result as text, so by default it gets each result once. With
+  `result: 'structured'` (the default) a call resolves to the tool's `structuredContent` alone when its content only
+  repeats it: one text block with the same JSON, or the primitive a `{ content }` wrapper holds, as the server writes
+  it for clients that don't read structured output. Otherwise it resolves to `{ content }`, plus `structuredContent`
+  when there is one, so text that says more and images are kept. `'content'` always resolves to `{ content }`, and
+  `'both'` to `{ content, structuredContent }` as an MCP client gets them (the shape up to 1.9.4). `_meta` is never
+  included.
 - **Errors.** An error result (`isError`), or an error from the server, rejects with its message.
 
+## Registering tools before the server loads
+
+A server in the page is a large bundle, and starting it is one long task. To keep it off page load, compute the
+tool list at build time and register it in the page; the server loads on an agent's first call:
+
+`server.ts`, one factory for the build script and the page:
+
+```typescript
+export function createShopServer({ modelContext }: { modelContext?: ModelContext } = {}) {
+  return create({
+    info: { name: 'shop', version: '1.0.0' },
+    tools: [SearchProducts, AddToCart],
+    plugins: [WebMcpPlugin.init({ prefix: 'shop.', modelContext })],
+  });
+}
+```
+
+The build script (Node):
+
+```typescript
+import { listWebMcpTools } from '@frontmcp/plugin-webmcp';
+
+const tools = await listWebMcpTools((modelContext) => createShopServer({ modelContext }));
+await writeFile('src/webmcp-tools.json', JSON.stringify(tools));
+```
+
+The page entry, a chunk without the SDK:
+
+```typescript
+import { registerWebMcpTools, resolveDocumentModelContext } from '@frontmcp/plugin-webmcp/register';
+
+import tools from './webmcp-tools.json';
+
+void registerWebMcpTools(resolveDocumentModelContext(), tools, (modelContext) =>
+  import('./server').then(({ createShopServer }) => createShopServer({ modelContext })),
+);
+```
+
+- `listWebMcpTools(factory)` builds the server with a `modelContext` that records what the plugin registers,
+  returns those descriptors (name, title, description, input schema, hints) and disposes the server. The factory
+  must pass the `modelContext` it is given to `WebMcpPlugin.init()`.
+- `registerWebMcpTools(modelContext, tools, loadServer, { exposedTo? })` registers the list at once. The first call
+  loads the server with `loadServer` (once, however many calls arrive together) and runs through the plugin; a failed
+  load rejects that call (a server it built is disposed, and the listed tools stay), and the next call tries again. From then on the plugin registers and unregisters tools as
+  the server's tools change, and `server.dispose()` unregisters them. A listed tool the loaded server lacks is
+  unregistered. Without a `modelContext` (no WebMCP) it does nothing.
+- `@frontmcp/plugin-webmcp/register` does not import `@frontmcp/sdk`; it is a few kilobytes.
+
 ## Browser support
 
 WebMCP is in origin trial in Chrome and Edge (Chrome 149+). For local development, enable

package/esm/index.mjs

@@ -18,9 +18,17 @@ import {
   InternalMcpError
 } from "@frontmcp/sdk";
 import { randomUUID, runRequestExclusive } from "@frontmcp/utils";
-var MAX_WEBMCP_NAME_LENGTH = 128;
-var INVALID_NAME_CHARACTERS = /[^A-Za-z0-9_.-]/g;
-var ANONYMOUS_SUBJECT = "anon:webmcp";
+
+// plugins/plugin-webmcp/src/webmcp.handoff.ts
+var SYNC_LISTENER = /* @__PURE__ */ Symbol.for("@frontmcp/plugin-webmcp/sync-listener");
+function withSyncListener(modelContext, listener) {
+  return Object.assign(modelContext, { [SYNC_LISTENER]: listener });
+}
+function syncListenerOf(modelContext) {
+  return modelContext?.[SYNC_LISTENER];
+}
+
+// plugins/plugin-webmcp/src/webmcp.model-context.ts
 function resolveDocumentModelContext() {
   const modelContext = globalThis.document?.modelContext;
   return typeof modelContext === "object" && modelContext !== null && typeof modelContext.registerTool === "function" ? modelContext : void 0;
@@ -28,6 +36,11 @@ function resolveDocumentModelContext() {
 function isWebMcpSupported() {
   return resolveDocumentModelContext() !== void 0;
 }
+
+// plugins/plugin-webmcp/src/webmcp.bridge.ts
+var MAX_WEBMCP_NAME_LENGTH = 128;
+var INVALID_NAME_CHARACTERS = /[^A-Za-z0-9_.-]/g;
+var ANONYMOUS_SUBJECT = "anon:webmcp";
 function toWebMcpToolName(name) {
   const cleaned = name.replace(INVALID_NAME_CHARACTERS, "_").slice(0, MAX_WEBMCP_NAME_LENGTH);
   return cleaned.length > 0 ? cleaned : "_";
@@ -47,6 +60,27 @@ function toWebMcpAnnotations(annotations) {
   if (annotations?.openWorldHint === true) hints.untrustedContentHint = true;
   return Object.keys(hints).length > 0 ? hints : void 0;
 }
+function isSameJson(text, value) {
+  try {
+    return JSON.stringify(JSON.parse(text)) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+function isTextCopyOf(content, structuredContent) {
+  const [block, ...others] = content;
+  if (block?.type !== "text" || others.length > 0) return false;
+  if (isSameJson(block.text, structuredContent)) return true;
+  const keys = Object.keys(structuredContent);
+  return keys.length === 1 && keys[0] === "content" && block.text === String(structuredContent["content"] ?? "");
+}
+function toAgentResult(result, mode) {
+  const content = result.content ?? [];
+  const structuredContent = result.structuredContent;
+  if (mode === "content" || structuredContent === void 0) return { content };
+  if (mode === "structured" && isTextCopyOf(content, structuredContent)) return structuredContent;
+  return { content, structuredContent };
+}
 function textOf(content) {
   return (content ?? []).map((block) => block.type === "text" ? block.text : "").filter((text) => text.length > 0).join("\n");
 }
@@ -103,6 +137,7 @@ var WebMcpBridge = class {
       return;
     }
     this.modelContext = modelContext;
+    syncListenerOf(modelContext)?.started();
     this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, () => this.refresh());
   }
   /**
@@ -131,15 +166,19 @@ var WebMcpBridge = class {
   /** Sync until no change is pending. Starts a microtask later, so a burst of changes syncs once. */
   async drain() {
     await Promise.resolve();
+    let failure;
     try {
       while (this.pending && !this.stopped) {
         this.pending = false;
         try {
           await this.sync();
+          failure = void 0;
         } catch (error) {
+          failure = error;
           this.logger.warn(`WebMCP sync failed: ${toAgentError(error).message}`);
         }
       }
+      if (!this.stopped) syncListenerOf(this.modelContext)?.synced(failure);
     } finally {
       this.run = void 0;
     }
@@ -230,10 +269,7 @@ var WebMcpBridge = class {
       throw toAgentError(error);
     }
     if (result.isError) throw new Error(textOf(result.content) || `Tool "${mcpName}" failed`);
-    return {
-      content: result.content ?? [],
-      ...result.structuredContent !== void 0 && { structuredContent: result.structuredContent }
-    };
+    return toAgentResult(result, this.options.result);
   }
   /**
    * Run a flow as its own request. A browser build without AsyncContext runs requests one at a
@@ -284,7 +320,15 @@ var webMcpPluginOptionsSchema = z.object({
   /** Auth context the tools are listed and called with. Defaults to an anonymous `webmcp` caller. */
   authContext: z.custom((value) => typeof value === "function" || typeof value === "object" && value !== null).optional(),
   /** The `ModelContext` to register with. Defaults to `document.modelContext`; pass a polyfill or test double. */
-  modelContext: z.custom(isModelContext, { message: "modelContext must have a registerTool function" }).optional()
+  modelContext: z.custom(isModelContext, { message: "modelContext must have a registerTool function" }).optional(),
+  /**
+   * What a call resolves to. The agent reads the whole value as text, so by default it gets each result once:
+   * - `'structured'`: the tool's `structuredContent` alone when its content only repeats it (one text block with
+   *   the same JSON, as the server writes it); otherwise `{ content }`, plus `structuredContent` when there is one.
+   * - `'content'`: `{ content }`.
+   * - `'both'`: `{ content, structuredContent }`, as an MCP client gets them.
+   */
+  result: z.enum(["structured", "content", "both"]).default("structured")
 });
 
 // plugins/plugin-webmcp/src/webmcp.plugin.ts
@@ -321,11 +365,168 @@ WebMcpPlugin = __decorateClass([
     description: "Exposes the server's tools to in-browser agents through WebMCP (document.modelContext)"
   })
 ], WebMcpPlugin);
+
+// plugins/plugin-webmcp/src/webmcp.lazy.ts
+var NO_PLUGIN_MESSAGE = "The server has no WebMcpPlugin on the modelContext it was given: pass it to WebMcpPlugin.init({ modelContext })";
+function createPluginSync() {
+  let started = false;
+  let resolveSynced;
+  let rejectSynced;
+  const synced = new Promise((resolve, reject) => {
+    resolveSynced = resolve;
+    rejectSynced = reject;
+  });
+  synced.catch(() => void 0);
+  return {
+    listener: {
+      started: () => {
+        started = true;
+      },
+      synced: (error) => error === void 0 ? resolveSynced?.() : rejectSynced?.(error)
+    },
+    async whenSynced() {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (!started) throw new Error(NO_PLUGIN_MESSAGE);
+      await synced;
+    }
+  };
+}
+function fingerprintOf(descriptor, exposedTo) {
+  return JSON.stringify([descriptor, exposedTo ?? []]);
+}
+async function listWebMcpTools(createServer) {
+  const descriptors = /* @__PURE__ */ new Map();
+  const pluginSync = createPluginSync();
+  const modelContext = withSyncListener(
+    {
+      async registerTool({ execute: _execute, ...descriptor }, options) {
+        descriptors.set(descriptor.name, descriptor);
+        options?.signal?.addEventListener("abort", () => descriptors.delete(descriptor.name), { once: true });
+      }
+    },
+    pluginSync.listener
+  );
+  const server = await createServer(modelContext);
+  try {
+    await pluginSync.whenSynced();
+    return [...descriptors.values()];
+  } finally {
+    await server.dispose();
+  }
+}
+var LazyWebMcpTools = class {
+  constructor(modelContext, loadServer) {
+    this.modelContext = modelContext;
+    this.loadServer = loadServer;
+  }
+  modelContext;
+  loadServer;
+  placeholders = /* @__PURE__ */ new Map();
+  /** The plugin's `execute` of every tool it registered, by name. */
+  executors = /* @__PURE__ */ new Map();
+  loading;
+  async register(tools, exposedTo) {
+    await Promise.all(tools.map((tool) => this.registerPlaceholder(tool, exposedTo)));
+  }
+  async registerPlaceholder(tool, exposedTo) {
+    const placeholder = {
+      fingerprint: fingerprintOf(tool, exposedTo),
+      controller: new AbortController(),
+      adopted: false
+    };
+    this.placeholders.set(tool.name, placeholder);
+    try {
+      await this.modelContext.registerTool(
+        { ...tool, execute: (input, options) => this.call(tool.name, input, options) },
+        { signal: placeholder.controller.signal, ...exposedTo && { exposedTo } }
+      );
+    } catch {
+      this.release(tool.name, placeholder);
+    }
+  }
+  async call(name, input, options) {
+    await this.load();
+    const execute = this.executors.get(name);
+    if (!execute) throw new Error(`Tool "${name}" not found`);
+    return execute(input, options);
+  }
+  /** Load the server once; a failed load is tried again on the next call. */
+  load() {
+    this.loading ??= this.loadThroughPlugin().catch((error) => {
+      this.loading = void 0;
+      throw error;
+    });
+    return this.loading;
+  }
+  async loadThroughPlugin() {
+    const pluginSync = createPluginSync();
+    const attempt = { failed: false };
+    const handoff = withSyncListener(
+      { registerTool: (tool, options) => this.adopt(tool, options, attempt) },
+      pluginSync.listener
+    );
+    const server = await this.loadServer(handoff);
+    try {
+      await pluginSync.whenSynced();
+    } catch (error) {
+      await this.abandon(attempt, server);
+      throw error;
+    }
+    for (const [name, placeholder] of this.placeholders) {
+      if (!placeholder.adopted) this.release(name, placeholder);
+    }
+  }
+  /** Forget what a failed load's plugin registered, keep the listed tools for the next try, and dispose its server. */
+  async abandon(attempt, server) {
+    attempt.failed = true;
+    this.executors.clear();
+    for (const placeholder of this.placeholders.values()) placeholder.adopted = false;
+    const disposable = server;
+    if (typeof disposable?.dispose === "function") await Promise.resolve(disposable.dispose()).catch(() => void 0);
+  }
+  /**
+   * A registration from the plugin: an unchanged listed tool keeps its registration and runs the plugin's
+   * `execute`; anything else replaces the listed tool of that name, or is new, and goes to the page's context.
+   */
+  async adopt(tool, options, attempt) {
+    if (attempt.failed || options?.signal?.aborted) return;
+    const { execute, ...descriptor } = tool;
+    const placeholder = this.placeholders.get(tool.name);
+    const kept = placeholder && !placeholder.adopted && placeholder.fingerprint === fingerprintOf(descriptor, options?.exposedTo) ? placeholder : void 0;
+    this.executors.set(tool.name, execute);
+    options?.signal?.addEventListener(
+      "abort",
+      () => {
+        if (attempt.failed) return;
+        if (this.executors.get(tool.name) === execute) this.executors.delete(tool.name);
+        if (kept) this.release(tool.name, kept);
+      },
+      { once: true }
+    );
+    if (kept) {
+      kept.adopted = true;
+      return;
+    }
+    if (placeholder) this.release(tool.name, placeholder);
+    await this.modelContext.registerTool(tool, options);
+  }
+  release(name, placeholder) {
+    placeholder.controller.abort();
+    if (this.placeholders.get(name) === placeholder) this.placeholders.delete(name);
+  }
+};
+async function registerWebMcpTools(modelContext, tools, loadServer, options = {}) {
+  if (!modelContext) return;
+  await new LazyWebMcpTools(modelContext, loadServer).register(tools, options.exposedTo);
+}
 export {
   WebMcpBridge,
   WebMcpPlugin,
   WebMcpPlugin as default,
   isWebMcpSupported,
+  listWebMcpTools,
+  registerWebMcpTools,
+  resolveDocumentModelContext,
   toWebMcpToolName,
   webMcpPluginOptionsSchema
 };

package/esm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/plugin-webmcp",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "WebMCP plugin for FrontMCP - expose an in-browser FrontMCP server's tools to browser agents through document.modelContext",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
   "bugs": {
     "url": "https://github.com/agentfront/frontmcp/issues"
   },
-  "homepage": "https://github.com/agentfront/frontmcp/blob/main/plugins/plugin-webmcp/README.md",
+  "homepage": "https://frontmcp.dev/reference/plugins/webmcp",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -46,14 +46,24 @@
         "types": "../index.d.ts",
         "default": "./index.mjs"
       }
+    },
+    "./register": {
+      "require": {
+        "types": "../register.d.ts",
+        "default": "../register.js"
+      },
+      "import": {
+        "types": "../register.d.ts",
+        "default": "./register.mjs"
+      }
     }
   },
   "dependencies": {
-    "@frontmcp/sdk": "1.9.3",
-    "@frontmcp/utils": "1.9.3"
+    "@frontmcp/sdk": "1.9.5",
+    "@frontmcp/utils": "1.9.5"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.9.3"
+    "@frontmcp/lazy-zod": "1.9.5"
   },
   "devDependencies": {
     "reflect-metadata": "^0.2.2"

package/esm/register.mjs

@@ -0,0 +1,153 @@
+// plugins/plugin-webmcp/src/webmcp.model-context.ts
+function resolveDocumentModelContext() {
+  const modelContext = globalThis.document?.modelContext;
+  return typeof modelContext === "object" && modelContext !== null && typeof modelContext.registerTool === "function" ? modelContext : void 0;
+}
+function isWebMcpSupported() {
+  return resolveDocumentModelContext() !== void 0;
+}
+
+// plugins/plugin-webmcp/src/webmcp.handoff.ts
+var SYNC_LISTENER = /* @__PURE__ */ Symbol.for("@frontmcp/plugin-webmcp/sync-listener");
+function withSyncListener(modelContext, listener) {
+  return Object.assign(modelContext, { [SYNC_LISTENER]: listener });
+}
+
+// plugins/plugin-webmcp/src/webmcp.lazy.ts
+var NO_PLUGIN_MESSAGE = "The server has no WebMcpPlugin on the modelContext it was given: pass it to WebMcpPlugin.init({ modelContext })";
+function createPluginSync() {
+  let started = false;
+  let resolveSynced;
+  let rejectSynced;
+  const synced = new Promise((resolve, reject) => {
+    resolveSynced = resolve;
+    rejectSynced = reject;
+  });
+  synced.catch(() => void 0);
+  return {
+    listener: {
+      started: () => {
+        started = true;
+      },
+      synced: (error) => error === void 0 ? resolveSynced?.() : rejectSynced?.(error)
+    },
+    async whenSynced() {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (!started) throw new Error(NO_PLUGIN_MESSAGE);
+      await synced;
+    }
+  };
+}
+function fingerprintOf(descriptor, exposedTo) {
+  return JSON.stringify([descriptor, exposedTo ?? []]);
+}
+var LazyWebMcpTools = class {
+  constructor(modelContext, loadServer) {
+    this.modelContext = modelContext;
+    this.loadServer = loadServer;
+  }
+  modelContext;
+  loadServer;
+  placeholders = /* @__PURE__ */ new Map();
+  /** The plugin's `execute` of every tool it registered, by name. */
+  executors = /* @__PURE__ */ new Map();
+  loading;
+  async register(tools, exposedTo) {
+    await Promise.all(tools.map((tool) => this.registerPlaceholder(tool, exposedTo)));
+  }
+  async registerPlaceholder(tool, exposedTo) {
+    const placeholder = {
+      fingerprint: fingerprintOf(tool, exposedTo),
+      controller: new AbortController(),
+      adopted: false
+    };
+    this.placeholders.set(tool.name, placeholder);
+    try {
+      await this.modelContext.registerTool(
+        { ...tool, execute: (input, options) => this.call(tool.name, input, options) },
+        { signal: placeholder.controller.signal, ...exposedTo && { exposedTo } }
+      );
+    } catch {
+      this.release(tool.name, placeholder);
+    }
+  }
+  async call(name, input, options) {
+    await this.load();
+    const execute = this.executors.get(name);
+    if (!execute) throw new Error(`Tool "${name}" not found`);
+    return execute(input, options);
+  }
+  /** Load the server once; a failed load is tried again on the next call. */
+  load() {
+    this.loading ??= this.loadThroughPlugin().catch((error) => {
+      this.loading = void 0;
+      throw error;
+    });
+    return this.loading;
+  }
+  async loadThroughPlugin() {
+    const pluginSync = createPluginSync();
+    const attempt = { failed: false };
+    const handoff = withSyncListener(
+      { registerTool: (tool, options) => this.adopt(tool, options, attempt) },
+      pluginSync.listener
+    );
+    const server = await this.loadServer(handoff);
+    try {
+      await pluginSync.whenSynced();
+    } catch (error) {
+      await this.abandon(attempt, server);
+      throw error;
+    }
+    for (const [name, placeholder] of this.placeholders) {
+      if (!placeholder.adopted) this.release(name, placeholder);
+    }
+  }
+  /** Forget what a failed load's plugin registered, keep the listed tools for the next try, and dispose its server. */
+  async abandon(attempt, server) {
+    attempt.failed = true;
+    this.executors.clear();
+    for (const placeholder of this.placeholders.values()) placeholder.adopted = false;
+    const disposable = server;
+    if (typeof disposable?.dispose === "function") await Promise.resolve(disposable.dispose()).catch(() => void 0);
+  }
+  /**
+   * A registration from the plugin: an unchanged listed tool keeps its registration and runs the plugin's
+   * `execute`; anything else replaces the listed tool of that name, or is new, and goes to the page's context.
+   */
+  async adopt(tool, options, attempt) {
+    if (attempt.failed || options?.signal?.aborted) return;
+    const { execute, ...descriptor } = tool;
+    const placeholder = this.placeholders.get(tool.name);
+    const kept = placeholder && !placeholder.adopted && placeholder.fingerprint === fingerprintOf(descriptor, options?.exposedTo) ? placeholder : void 0;
+    this.executors.set(tool.name, execute);
+    options?.signal?.addEventListener(
+      "abort",
+      () => {
+        if (attempt.failed) return;
+        if (this.executors.get(tool.name) === execute) this.executors.delete(tool.name);
+        if (kept) this.release(tool.name, kept);
+      },
+      { once: true }
+    );
+    if (kept) {
+      kept.adopted = true;
+      return;
+    }
+    if (placeholder) this.release(tool.name, placeholder);
+    await this.modelContext.registerTool(tool, options);
+  }
+  release(name, placeholder) {
+    placeholder.controller.abort();
+    if (this.placeholders.get(name) === placeholder) this.placeholders.delete(name);
+  }
+};
+async function registerWebMcpTools(modelContext, tools, loadServer, options = {}) {
+  if (!modelContext) return;
+  await new LazyWebMcpTools(modelContext, loadServer).register(tools, options.exposedTo);
+}
+export {
+  isWebMcpSupported,
+  registerWebMcpTools,
+  resolveDocumentModelContext
+};

package/index.d.ts

@@ -1,5 +1,7 @@
 export { default, default as WebMcpPlugin } from './webmcp.plugin';
-export { WebMcpBridge, isWebMcpSupported, toWebMcpToolName, type WebMcpToolResult } from './webmcp.bridge';
-export { webMcpPluginOptionsSchema, type WebMcpAuthContext, type WebMcpListedTool, type WebMcpPluginOptions, type WebMcpPluginOptionsInput, } from './webmcp.options';
+export { WebMcpBridge, toWebMcpToolName, type WebMcpContentResult, type WebMcpToolResult } from './webmcp.bridge';
+export { isWebMcpSupported, resolveDocumentModelContext } from './webmcp.model-context';
+export { listWebMcpTools, registerWebMcpTools, type RegisterWebMcpToolsOptions, type WebMcpServerFactory, type WebMcpToolDescriptor, } from './webmcp.lazy';
+export { webMcpPluginOptionsSchema, type WebMcpAuthContext, type WebMcpListedTool, type WebMcpPluginOptions, type WebMcpPluginOptionsInput, type WebMcpResultMode, } from './webmcp.options';
 export type { ModelContext, ModelContextRegisterToolOptions, ModelContextRegisteredTool, ModelContextTool, ModelContextToolAnnotations, ModelContextToolExecuteOptions, } from './webmcp.types';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC3G,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,GAC9B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,YAAY,EACZ,+BAA+B,EAC/B,0BAA0B,EAC1B,gBAAgB,EAChB,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClH,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,YAAY,EACZ,+BAA+B,EAC/B,0BAA0B,EAC1B,gBAAgB,EAChB,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC"}

package/index.js

@@ -32,6 +32,9 @@ __export(index_exports, {
   WebMcpPlugin: () => WebMcpPlugin,
   default: () => WebMcpPlugin,
   isWebMcpSupported: () => isWebMcpSupported,
+  listWebMcpTools: () => listWebMcpTools,
+  registerWebMcpTools: () => registerWebMcpTools,
+  resolveDocumentModelContext: () => resolveDocumentModelContext,
   toWebMcpToolName: () => toWebMcpToolName,
   webMcpPluginOptionsSchema: () => webMcpPluginOptionsSchema
 });
@@ -43,9 +46,17 @@ var import_sdk2 = require("@frontmcp/sdk");
 // plugins/plugin-webmcp/src/webmcp.bridge.ts
 var import_sdk = require("@frontmcp/sdk");
 var import_utils = require("@frontmcp/utils");
-var MAX_WEBMCP_NAME_LENGTH = 128;
-var INVALID_NAME_CHARACTERS = /[^A-Za-z0-9_.-]/g;
-var ANONYMOUS_SUBJECT = "anon:webmcp";
+
+// plugins/plugin-webmcp/src/webmcp.handoff.ts
+var SYNC_LISTENER = /* @__PURE__ */ Symbol.for("@frontmcp/plugin-webmcp/sync-listener");
+function withSyncListener(modelContext, listener) {
+  return Object.assign(modelContext, { [SYNC_LISTENER]: listener });
+}
+function syncListenerOf(modelContext) {
+  return modelContext?.[SYNC_LISTENER];
+}
+
+// plugins/plugin-webmcp/src/webmcp.model-context.ts
 function resolveDocumentModelContext() {
   const modelContext = globalThis.document?.modelContext;
   return typeof modelContext === "object" && modelContext !== null && typeof modelContext.registerTool === "function" ? modelContext : void 0;
@@ -53,6 +64,11 @@ function resolveDocumentModelContext() {
 function isWebMcpSupported() {
   return resolveDocumentModelContext() !== void 0;
 }
+
+// plugins/plugin-webmcp/src/webmcp.bridge.ts
+var MAX_WEBMCP_NAME_LENGTH = 128;
+var INVALID_NAME_CHARACTERS = /[^A-Za-z0-9_.-]/g;
+var ANONYMOUS_SUBJECT = "anon:webmcp";
 function toWebMcpToolName(name) {
   const cleaned = name.replace(INVALID_NAME_CHARACTERS, "_").slice(0, MAX_WEBMCP_NAME_LENGTH);
   return cleaned.length > 0 ? cleaned : "_";
@@ -72,6 +88,27 @@ function toWebMcpAnnotations(annotations) {
   if (annotations?.openWorldHint === true) hints.untrustedContentHint = true;
   return Object.keys(hints).length > 0 ? hints : void 0;
 }
+function isSameJson(text, value) {
+  try {
+    return JSON.stringify(JSON.parse(text)) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+function isTextCopyOf(content, structuredContent) {
+  const [block, ...others] = content;
+  if (block?.type !== "text" || others.length > 0) return false;
+  if (isSameJson(block.text, structuredContent)) return true;
+  const keys = Object.keys(structuredContent);
+  return keys.length === 1 && keys[0] === "content" && block.text === String(structuredContent["content"] ?? "");
+}
+function toAgentResult(result, mode) {
+  const content = result.content ?? [];
+  const structuredContent = result.structuredContent;
+  if (mode === "content" || structuredContent === void 0) return { content };
+  if (mode === "structured" && isTextCopyOf(content, structuredContent)) return structuredContent;
+  return { content, structuredContent };
+}
 function textOf(content) {
   return (content ?? []).map((block) => block.type === "text" ? block.text : "").filter((text) => text.length > 0).join("\n");
 }
@@ -128,6 +165,7 @@ var WebMcpBridge = class {
       return;
     }
     this.modelContext = modelContext;
+    syncListenerOf(modelContext)?.started();
     this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, () => this.refresh());
   }
   /**
@@ -156,15 +194,19 @@ var WebMcpBridge = class {
   /** Sync until no change is pending. Starts a microtask later, so a burst of changes syncs once. */
   async drain() {
     await Promise.resolve();
+    let failure;
     try {
       while (this.pending && !this.stopped) {
         this.pending = false;
         try {
           await this.sync();
+          failure = void 0;
         } catch (error) {
+          failure = error;
           this.logger.warn(`WebMCP sync failed: ${toAgentError(error).message}`);
         }
       }
+      if (!this.stopped) syncListenerOf(this.modelContext)?.synced(failure);
     } finally {
       this.run = void 0;
     }
@@ -255,10 +297,7 @@ var WebMcpBridge = class {
       throw toAgentError(error);
     }
     if (result.isError) throw new Error(textOf(result.content) || `Tool "${mcpName}" failed`);
-    return {
-      content: result.content ?? [],
-      ...result.structuredContent !== void 0 && { structuredContent: result.structuredContent }
-    };
+    return toAgentResult(result, this.options.result);
   }
   /**
    * Run a flow as its own request. A browser build without AsyncContext runs requests one at a
@@ -309,7 +348,15 @@ var webMcpPluginOptionsSchema = import_lazy_zod.z.object({
   /** Auth context the tools are listed and called with. Defaults to an anonymous `webmcp` caller. */
   authContext: import_lazy_zod.z.custom((value) => typeof value === "function" || typeof value === "object" && value !== null).optional(),
   /** The `ModelContext` to register with. Defaults to `document.modelContext`; pass a polyfill or test double. */
-  modelContext: import_lazy_zod.z.custom(isModelContext, { message: "modelContext must have a registerTool function" }).optional()
+  modelContext: import_lazy_zod.z.custom(isModelContext, { message: "modelContext must have a registerTool function" }).optional(),
+  /**
+   * What a call resolves to. The agent reads the whole value as text, so by default it gets each result once:
+   * - `'structured'`: the tool's `structuredContent` alone when its content only repeats it (one text block with
+   *   the same JSON, as the server writes it); otherwise `{ content }`, plus `structuredContent` when there is one.
+   * - `'content'`: `{ content }`.
+   * - `'both'`: `{ content, structuredContent }`, as an MCP client gets them.
+   */
+  result: import_lazy_zod.z.enum(["structured", "content", "both"]).default("structured")
 });
 
 // plugins/plugin-webmcp/src/webmcp.plugin.ts
@@ -346,3 +393,157 @@ WebMcpPlugin = __decorateClass([
     description: "Exposes the server's tools to in-browser agents through WebMCP (document.modelContext)"
   })
 ], WebMcpPlugin);
+
+// plugins/plugin-webmcp/src/webmcp.lazy.ts
+var NO_PLUGIN_MESSAGE = "The server has no WebMcpPlugin on the modelContext it was given: pass it to WebMcpPlugin.init({ modelContext })";
+function createPluginSync() {
+  let started = false;
+  let resolveSynced;
+  let rejectSynced;
+  const synced = new Promise((resolve, reject) => {
+    resolveSynced = resolve;
+    rejectSynced = reject;
+  });
+  synced.catch(() => void 0);
+  return {
+    listener: {
+      started: () => {
+        started = true;
+      },
+      synced: (error) => error === void 0 ? resolveSynced?.() : rejectSynced?.(error)
+    },
+    async whenSynced() {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (!started) throw new Error(NO_PLUGIN_MESSAGE);
+      await synced;
+    }
+  };
+}
+function fingerprintOf(descriptor, exposedTo) {
+  return JSON.stringify([descriptor, exposedTo ?? []]);
+}
+async function listWebMcpTools(createServer) {
+  const descriptors = /* @__PURE__ */ new Map();
+  const pluginSync = createPluginSync();
+  const modelContext = withSyncListener(
+    {
+      async registerTool({ execute: _execute, ...descriptor }, options) {
+        descriptors.set(descriptor.name, descriptor);
+        options?.signal?.addEventListener("abort", () => descriptors.delete(descriptor.name), { once: true });
+      }
+    },
+    pluginSync.listener
+  );
+  const server = await createServer(modelContext);
+  try {
+    await pluginSync.whenSynced();
+    return [...descriptors.values()];
+  } finally {
+    await server.dispose();
+  }
+}
+var LazyWebMcpTools = class {
+  constructor(modelContext, loadServer) {
+    this.modelContext = modelContext;
+    this.loadServer = loadServer;
+  }
+  modelContext;
+  loadServer;
+  placeholders = /* @__PURE__ */ new Map();
+  /** The plugin's `execute` of every tool it registered, by name. */
+  executors = /* @__PURE__ */ new Map();
+  loading;
+  async register(tools, exposedTo) {
+    await Promise.all(tools.map((tool) => this.registerPlaceholder(tool, exposedTo)));
+  }
+  async registerPlaceholder(tool, exposedTo) {
+    const placeholder = {
+      fingerprint: fingerprintOf(tool, exposedTo),
+      controller: new AbortController(),
+      adopted: false
+    };
+    this.placeholders.set(tool.name, placeholder);
+    try {
+      await this.modelContext.registerTool(
+        { ...tool, execute: (input, options) => this.call(tool.name, input, options) },
+        { signal: placeholder.controller.signal, ...exposedTo && { exposedTo } }
+      );
+    } catch {
+      this.release(tool.name, placeholder);
+    }
+  }
+  async call(name, input, options) {
+    await this.load();
+    const execute = this.executors.get(name);
+    if (!execute) throw new Error(`Tool "${name}" not found`);
+    return execute(input, options);
+  }
+  /** Load the server once; a failed load is tried again on the next call. */
+  load() {
+    this.loading ??= this.loadThroughPlugin().catch((error) => {
+      this.loading = void 0;
+      throw error;
+    });
+    return this.loading;
+  }
+  async loadThroughPlugin() {
+    const pluginSync = createPluginSync();
+    const attempt = { failed: false };
+    const handoff = withSyncListener(
+      { registerTool: (tool, options) => this.adopt(tool, options, attempt) },
+      pluginSync.listener
+    );
+    const server = await this.loadServer(handoff);
+    try {
+      await pluginSync.whenSynced();
+    } catch (error) {
+      await this.abandon(attempt, server);
+      throw error;
+    }
+    for (const [name, placeholder] of this.placeholders) {
+      if (!placeholder.adopted) this.release(name, placeholder);
+    }
+  }
+  /** Forget what a failed load's plugin registered, keep the listed tools for the next try, and dispose its server. */
+  async abandon(attempt, server) {
+    attempt.failed = true;
+    this.executors.clear();
+    for (const placeholder of this.placeholders.values()) placeholder.adopted = false;
+    const disposable = server;
+    if (typeof disposable?.dispose === "function") await Promise.resolve(disposable.dispose()).catch(() => void 0);
+  }
+  /**
+   * A registration from the plugin: an unchanged listed tool keeps its registration and runs the plugin's
+   * `execute`; anything else replaces the listed tool of that name, or is new, and goes to the page's context.
+   */
+  async adopt(tool, options, attempt) {
+    if (attempt.failed || options?.signal?.aborted) return;
+    const { execute, ...descriptor } = tool;
+    const placeholder = this.placeholders.get(tool.name);
+    const kept = placeholder && !placeholder.adopted && placeholder.fingerprint === fingerprintOf(descriptor, options?.exposedTo) ? placeholder : void 0;
+    this.executors.set(tool.name, execute);
+    options?.signal?.addEventListener(
+      "abort",
+      () => {
+        if (attempt.failed) return;
+        if (this.executors.get(tool.name) === execute) this.executors.delete(tool.name);
+        if (kept) this.release(tool.name, kept);
+      },
+      { once: true }
+    );
+    if (kept) {
+      kept.adopted = true;
+      return;
+    }
+    if (placeholder) this.release(tool.name, placeholder);
+    await this.modelContext.registerTool(tool, options);
+  }
+  release(name, placeholder) {
+    placeholder.controller.abort();
+    if (this.placeholders.get(name) === placeholder) this.placeholders.delete(name);
+  }
+};
+async function registerWebMcpTools(modelContext, tools, loadServer, options = {}) {
+  if (!modelContext) return;
+  await new LazyWebMcpTools(modelContext, loadServer).register(tools, options.exposedTo);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/plugin-webmcp",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "WebMCP plugin for FrontMCP - expose an in-browser FrontMCP server's tools to browser agents through document.modelContext",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
   "bugs": {
     "url": "https://github.com/agentfront/frontmcp/issues"
   },
-  "homepage": "https://github.com/agentfront/frontmcp/blob/main/plugins/plugin-webmcp/README.md",
+  "homepage": "https://frontmcp.dev/reference/plugins/webmcp",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -46,14 +46,24 @@
         "types": "./index.d.ts",
         "default": "./esm/index.mjs"
       }
+    },
+    "./register": {
+      "require": {
+        "types": "./register.d.ts",
+        "default": "./register.js"
+      },
+      "import": {
+        "types": "./register.d.ts",
+        "default": "./esm/register.mjs"
+      }
     }
   },
   "dependencies": {
-    "@frontmcp/sdk": "1.9.3",
-    "@frontmcp/utils": "1.9.3"
+    "@frontmcp/sdk": "1.9.5",
+    "@frontmcp/utils": "1.9.5"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.9.3"
+    "@frontmcp/lazy-zod": "1.9.5"
   },
   "devDependencies": {
     "reflect-metadata": "^0.2.2"

package/register.d.ts

@@ -0,0 +1,4 @@
+export { isWebMcpSupported, resolveDocumentModelContext } from './webmcp.model-context';
+export { registerWebMcpTools, type RegisterWebMcpToolsOptions, type WebMcpServerFactory, type WebMcpToolDescriptor, } from './webmcp.lazy';
+export type { ModelContext, ModelContextRegisterToolOptions, ModelContextTool, ModelContextToolAnnotations, ModelContextToolExecuteOptions, } from './webmcp.types';
+//# sourceMappingURL=register.d.ts.map

package/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,+BAA+B,EAC/B,gBAAgB,EAChB,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC"}

package/register.js

@@ -0,0 +1,176 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// plugins/plugin-webmcp/src/register.ts
+var register_exports = {};
+__export(register_exports, {
+  isWebMcpSupported: () => isWebMcpSupported,
+  registerWebMcpTools: () => registerWebMcpTools,
+  resolveDocumentModelContext: () => resolveDocumentModelContext
+});
+module.exports = __toCommonJS(register_exports);
+
+// plugins/plugin-webmcp/src/webmcp.model-context.ts
+function resolveDocumentModelContext() {
+  const modelContext = globalThis.document?.modelContext;
+  return typeof modelContext === "object" && modelContext !== null && typeof modelContext.registerTool === "function" ? modelContext : void 0;
+}
+function isWebMcpSupported() {
+  return resolveDocumentModelContext() !== void 0;
+}
+
+// plugins/plugin-webmcp/src/webmcp.handoff.ts
+var SYNC_LISTENER = /* @__PURE__ */ Symbol.for("@frontmcp/plugin-webmcp/sync-listener");
+function withSyncListener(modelContext, listener) {
+  return Object.assign(modelContext, { [SYNC_LISTENER]: listener });
+}
+
+// plugins/plugin-webmcp/src/webmcp.lazy.ts
+var NO_PLUGIN_MESSAGE = "The server has no WebMcpPlugin on the modelContext it was given: pass it to WebMcpPlugin.init({ modelContext })";
+function createPluginSync() {
+  let started = false;
+  let resolveSynced;
+  let rejectSynced;
+  const synced = new Promise((resolve, reject) => {
+    resolveSynced = resolve;
+    rejectSynced = reject;
+  });
+  synced.catch(() => void 0);
+  return {
+    listener: {
+      started: () => {
+        started = true;
+      },
+      synced: (error) => error === void 0 ? resolveSynced?.() : rejectSynced?.(error)
+    },
+    async whenSynced() {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (!started) throw new Error(NO_PLUGIN_MESSAGE);
+      await synced;
+    }
+  };
+}
+function fingerprintOf(descriptor, exposedTo) {
+  return JSON.stringify([descriptor, exposedTo ?? []]);
+}
+var LazyWebMcpTools = class {
+  constructor(modelContext, loadServer) {
+    this.modelContext = modelContext;
+    this.loadServer = loadServer;
+  }
+  modelContext;
+  loadServer;
+  placeholders = /* @__PURE__ */ new Map();
+  /** The plugin's `execute` of every tool it registered, by name. */
+  executors = /* @__PURE__ */ new Map();
+  loading;
+  async register(tools, exposedTo) {
+    await Promise.all(tools.map((tool) => this.registerPlaceholder(tool, exposedTo)));
+  }
+  async registerPlaceholder(tool, exposedTo) {
+    const placeholder = {
+      fingerprint: fingerprintOf(tool, exposedTo),
+      controller: new AbortController(),
+      adopted: false
+    };
+    this.placeholders.set(tool.name, placeholder);
+    try {
+      await this.modelContext.registerTool(
+        { ...tool, execute: (input, options) => this.call(tool.name, input, options) },
+        { signal: placeholder.controller.signal, ...exposedTo && { exposedTo } }
+      );
+    } catch {
+      this.release(tool.name, placeholder);
+    }
+  }
+  async call(name, input, options) {
+    await this.load();
+    const execute = this.executors.get(name);
+    if (!execute) throw new Error(`Tool "${name}" not found`);
+    return execute(input, options);
+  }
+  /** Load the server once; a failed load is tried again on the next call. */
+  load() {
+    this.loading ??= this.loadThroughPlugin().catch((error) => {
+      this.loading = void 0;
+      throw error;
+    });
+    return this.loading;
+  }
+  async loadThroughPlugin() {
+    const pluginSync = createPluginSync();
+    const attempt = { failed: false };
+    const handoff = withSyncListener(
+      { registerTool: (tool, options) => this.adopt(tool, options, attempt) },
+      pluginSync.listener
+    );
+    const server = await this.loadServer(handoff);
+    try {
+      await pluginSync.whenSynced();
+    } catch (error) {
+      await this.abandon(attempt, server);
+      throw error;
+    }
+    for (const [name, placeholder] of this.placeholders) {
+      if (!placeholder.adopted) this.release(name, placeholder);
+    }
+  }
+  /** Forget what a failed load's plugin registered, keep the listed tools for the next try, and dispose its server. */
+  async abandon(attempt, server) {
+    attempt.failed = true;
+    this.executors.clear();
+    for (const placeholder of this.placeholders.values()) placeholder.adopted = false;
+    const disposable = server;
+    if (typeof disposable?.dispose === "function") await Promise.resolve(disposable.dispose()).catch(() => void 0);
+  }
+  /**
+   * A registration from the plugin: an unchanged listed tool keeps its registration and runs the plugin's
+   * `execute`; anything else replaces the listed tool of that name, or is new, and goes to the page's context.
+   */
+  async adopt(tool, options, attempt) {
+    if (attempt.failed || options?.signal?.aborted) return;
+    const { execute, ...descriptor } = tool;
+    const placeholder = this.placeholders.get(tool.name);
+    const kept = placeholder && !placeholder.adopted && placeholder.fingerprint === fingerprintOf(descriptor, options?.exposedTo) ? placeholder : void 0;
+    this.executors.set(tool.name, execute);
+    options?.signal?.addEventListener(
+      "abort",
+      () => {
+        if (attempt.failed) return;
+        if (this.executors.get(tool.name) === execute) this.executors.delete(tool.name);
+        if (kept) this.release(tool.name, kept);
+      },
+      { once: true }
+    );
+    if (kept) {
+      kept.adopted = true;
+      return;
+    }
+    if (placeholder) this.release(tool.name, placeholder);
+    await this.modelContext.registerTool(tool, options);
+  }
+  release(name, placeholder) {
+    placeholder.controller.abort();
+    if (this.placeholders.get(name) === placeholder) this.placeholders.delete(name);
+  }
+};
+async function registerWebMcpTools(modelContext, tools, loadServer, options = {}) {
+  if (!modelContext) return;
+  await new LazyWebMcpTools(modelContext, loadServer).register(tools, options.exposedTo);
+}

package/webmcp.bridge.d.ts

@@ -7,16 +7,13 @@
  */
 import { type CallToolResult, type ScopeEntry } from '@frontmcp/sdk';
 import type { WebMcpPluginOptions } from './webmcp.options';
-import type { ModelContext } from './webmcp.types';
-/** What a WebMCP call resolves to: the MCP result without its `_meta` (and never `isError`). */
-export interface WebMcpToolResult {
+/** The MCP result without its `_meta` (and never `isError`). */
+export interface WebMcpContentResult {
     content: CallToolResult['content'];
     structuredContent?: CallToolResult['structuredContent'];
 }
-/** `document.modelContext` in a browser that implements WebMCP (or has a polyfill installed). */
-export declare function resolveDocumentModelContext(): ModelContext | undefined;
-/** Whether this page can register WebMCP tools (`document.modelContext.registerTool` exists). */
-export declare function isWebMcpSupported(): boolean;
+/** What a WebMCP call resolves to: the tool's structured content alone, or its content (see the `result` option). */
+export type WebMcpToolResult = WebMcpContentResult | NonNullable<CallToolResult['structuredContent']>;
 /** Make `name` a valid WebMCP tool name: invalid characters become `_`, cut to 128 characters. */
 export declare function toWebMcpToolName(name: string): string;
 export declare class WebMcpBridge {

package/webmcp.bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.bridge.d.ts","sourceRoot":"","sources":["../src/webmcp.bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAoB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,gBAAgB,CAAC;AAMxB,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;CACzD;AA4BD,iGAAiG;AACjG,wBAAgB,2BAA2B,IAAI,YAAY,GAAG,SAAS,CAOtE;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAsDD,qBAAa,YAAY;IAgBrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAS;IACxB,0CAA0C;IAC1C,OAAO,CAAC,GAAG,CAAC,CAAgB;gBAGT,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,mBAAmB;IAK/C,4EAA4E;IAC5E,IAAI,mBAAmB,IAAI,MAAM,EAAE,CAElC;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAab;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAMf,qDAAqD;IAC/C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,4FAA4F;IAC5F,IAAI,IAAI,IAAI;IASZ,mGAAmG;YACrF,KAAK;YAgBL,IAAI;IAgBlB,kFAAkF;YACpE,SAAS;IAevB,OAAO,CAAC,YAAY;YAmBN,QAAQ;IAwBtB,kGAAkG;YACpF,OAAO;IA2BrB;;;OAGG;YACW,SAAS;IASvB,2FAA2F;YAC7E,QAAQ;CAiBvB"}
+{"version":3,"file":"webmcp.bridge.d.ts","sourceRoot":"","sources":["../src/webmcp.bridge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAKvB,OAAO,KAAK,EAAoB,mBAAmB,EAAoB,MAAM,kBAAkB,CAAC;AAYhG,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAC;CACzD;AAED,qHAAqH;AACrH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,WAAW,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC,CAAC;AA4BtG,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD;AAmFD,qBAAa,YAAY;IAgBrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhB1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAS;IACxB,0CAA0C;IAC1C,OAAO,CAAC,GAAG,CAAC,CAAgB;gBAGT,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,mBAAmB;IAK/C,4EAA4E;IAC5E,IAAI,mBAAmB,IAAI,MAAM,EAAE,CAElC;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAcb;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAMf,qDAAqD;IAC/C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B,4FAA4F;IAC5F,IAAI,IAAI,IAAI;IASZ,mGAAmG;YACrF,KAAK;YAoBL,IAAI;IAgBlB,kFAAkF;YACpE,SAAS;IAevB,OAAO,CAAC,YAAY;YAmBN,QAAQ;IAwBtB,kGAAkG;YACpF,OAAO;IAwBrB;;;OAGG;YACW,SAAS;IASvB,2FAA2F;YAC7E,QAAQ;CAiBvB"}

package/webmcp.handoff.d.ts

@@ -0,0 +1,10 @@
+import type { ModelContext } from './webmcp.types';
+export interface WebMcpSyncListener {
+    /** The plugin found this `ModelContext` and follows the server's tools on it. */
+    started(): void;
+    /** The plugin registered the server's current tools; `error` when listing them failed. */
+    synced(error?: unknown): void;
+}
+export declare function withSyncListener(modelContext: ModelContext, listener: WebMcpSyncListener): ModelContext;
+export declare function syncListenerOf(modelContext: ModelContext | undefined): WebMcpSyncListener | undefined;
+//# sourceMappingURL=webmcp.handoff.d.ts.map

package/webmcp.handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.handoff.d.ts","sourceRoot":"","sources":["../src/webmcp.handoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAQnD,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,OAAO,IAAI,IAAI,CAAC;IAChB,0FAA0F;IAC1F,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC/B;AAID,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,GAAG,YAAY,CAEvG;AAED,wBAAgB,cAAc,CAAC,YAAY,EAAE,YAAY,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAErG"}

package/webmcp.lazy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Offering a page's tools to agents before its server is loaded: `listWebMcpTools()` computes, at build time,
+ * what WebMcpPlugin registers, and `registerWebMcpTools()` registers that list in the page and loads the server
+ * on an agent's first call. The calls then run through the plugin. Neither imports the SDK.
+ */
+import type { ModelContext, ModelContextTool } from './webmcp.types';
+/** A tool as WebMcpPlugin passes it to `registerTool()`, without its `execute`. */
+export type WebMcpToolDescriptor = Omit<ModelContextTool, 'execute'>;
+/**
+ * Builds the server, passing `modelContext` to `WebMcpPlugin.init({ modelContext })` with the plugin's other
+ * options as the page uses them.
+ */
+export type WebMcpServerFactory<Server = unknown> = (modelContext: ModelContext) => Promise<Server>;
+/** Options of `registerWebMcpTools()`. */
+export interface RegisterWebMcpToolsOptions {
+    /** Other origins the tools are offered to, as the plugin's `exposedTo` option. */
+    exposedTo?: string[];
+}
+/**
+ * What WebMcpPlugin registers for the server `createServer` builds: names, titles, descriptions, input schemas
+ * and hints, as JSON-safe values. Run it at build time and ship the result to `registerWebMcpTools()`. The
+ * server is disposed before this resolves.
+ *
+ * @example
+ * ```typescript
+ * const tools = await listWebMcpTools((modelContext) => createShopServer({ modelContext }));
+ * await writeFile('webmcp-tools.json', JSON.stringify(tools));
+ * ```
+ */
+export declare function listWebMcpTools(createServer: WebMcpServerFactory<{
+    dispose(): Promise<void>;
+}>): Promise<WebMcpToolDescriptor[]>;
+/**
+ * Register `tools` (from `listWebMcpTools()`) with `modelContext` at once, without loading the server. An
+ * agent's first call loads it with `loadServer` (once, however many calls arrive together) and runs through
+ * WebMcpPlugin from then on, which also registers and unregisters tools as the server's tools change. Does
+ * nothing when `modelContext` is undefined (no WebMCP in this browser).
+ *
+ * @example
+ * ```typescript
+ * import { registerWebMcpTools, resolveDocumentModelContext } from '@frontmcp/plugin-webmcp/register';
+ * import tools from './webmcp-tools.json';
+ *
+ * void registerWebMcpTools(resolveDocumentModelContext(), tools, (modelContext) =>
+ *   import('./server').then(({ createShopServer }) => createShopServer({ modelContext })),
+ * );
+ * ```
+ */
+export declare function registerWebMcpTools(modelContext: ModelContext | undefined, tools: readonly WebMcpToolDescriptor[], loadServer: WebMcpServerFactory, options?: RegisterWebMcpToolsOptions): Promise<void>;
+//# sourceMappingURL=webmcp.lazy.d.ts.map

package/webmcp.lazy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.lazy.d.ts","sourceRoot":"","sources":["../src/webmcp.lazy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,YAAY,EAEZ,gBAAgB,EAEjB,MAAM,gBAAgB,CAAC;AAExB,mFAAmF;AACnF,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,GAAG,OAAO,IAAI,CAAC,YAAY,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEpG,0CAA0C;AAC1C,MAAM,WAAW,0BAA0B;IACzC,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAyCD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,mBAAmB,CAAC;IAAE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,GAC9D,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAmBjC;AAmID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,KAAK,EAAE,SAAS,oBAAoB,EAAE,EACtC,UAAU,EAAE,mBAAmB,EAC/B,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/webmcp.model-context.d.ts

@@ -0,0 +1,6 @@
+import type { ModelContext } from './webmcp.types';
+/** `document.modelContext` in a browser that implements WebMCP (or has a polyfill installed). */
+export declare function resolveDocumentModelContext(): ModelContext | undefined;
+/** Whether this page can register WebMCP tools (`document.modelContext.registerTool` exists). */
+export declare function isWebMcpSupported(): boolean;
+//# sourceMappingURL=webmcp.model-context.d.ts.map

package/webmcp.model-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.model-context.d.ts","sourceRoot":"","sources":["../src/webmcp.model-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,iGAAiG;AACjG,wBAAgB,2BAA2B,IAAI,YAAY,GAAG,SAAS,CAOtE;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C"}

package/webmcp.options.d.ts

@@ -11,7 +11,14 @@ export declare const webMcpPluginOptionsSchema: import("@frontmcp/lazy-zod").Zod
     exposedTo: import("@frontmcp/lazy-zod").ZodOptional<import("@frontmcp/lazy-zod").ZodArray<import("@frontmcp/lazy-zod").ZodString>>;
     authContext: import("@frontmcp/lazy-zod").ZodOptional<import("zod").ZodCustom<WebMcpAuthContext, WebMcpAuthContext>>;
     modelContext: import("@frontmcp/lazy-zod").ZodOptional<import("zod").ZodCustom<ModelContext, ModelContext>>;
+    result: import("@frontmcp/lazy-zod").ZodDefault<import("@frontmcp/lazy-zod").ZodEnum<{
+        structured: "structured";
+        content: "content";
+        both: "both";
+    }>>;
 }, import("zod/v4/core").$strip>;
+/** What an agent's call resolves to (see the `result` option). */
+export type WebMcpResultMode = z.output<typeof webMcpPluginOptionsSchema>['result'];
 /** Options of `WebMcpPlugin.init()`, as the plugin holds them (defaults applied). */
 export type WebMcpPluginOptions = z.output<typeof webMcpPluginOptionsSchema>;
 /** Options of `WebMcpPlugin.init()`, as passed. */

package/webmcp.options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.options.d.ts","sourceRoot":"","sources":["../src/webmcp.options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,yFAAyF;AACzF,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAM3G,eAAO,MAAM,yBAAyB;;qFAOX,gBAAgB,KAAK,OAAO,SAA5B,gBAAgB,KAAK,OAAO;;;;gCAWrD,CAAC;AAEH,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE7E,mDAAmD;AACnD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"webmcp.options.d.ts","sourceRoot":"","sources":["../src/webmcp.options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,yFAAyF;AACzF,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAM3G,eAAO,MAAM,yBAAyB;;qFAOX,gBAAgB,KAAK,OAAO,SAA5B,gBAAgB,KAAK,OAAO;;;;;;;;;gCAmBrD,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEpF,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE7E,mDAAmD;AACnD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}