@frontmcp/plugin-webmcp 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @frontmcp/plugin-webmcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Expose the tools of a FrontMCP server that runs **in the page** to in-browser agents through
+[WebMCP](https://webmachinelearning.github.io/webmcp/) (`document.modelContext`). Agents such as
+Gemini in Chrome, the Model Context Tool Inspector extension, and DevTools' WebMCP panel can then
+discover and call them.
+
+## Installation
+
+```bash
+npm install @frontmcp/plugin-webmcp
+```
+
+## Usage
+
+```typescript
+import { WebMcpPlugin } from '@frontmcp/plugin-webmcp';
+import { create } from '@frontmcp/sdk';
+
+const server = await create({
+  info: { name: 'shop', version: '1.0.0' },
+  tools: [SearchProducts, AddToCart],
+  plugins: [WebMcpPlugin.init({ prefix: 'shop.' })],
+});
+```
+
+Install the plugin with `WebMcpPlugin.init()` (with or without options).
+
+Once the server is ready, every tool it lists on the `'webmcp'` surface is registered with
+`document.modelContext.registerTool()`:
+
+- **Kept in sync.** Tools added or removed later, including tools added with `server.registerTool()`
+  and React's `useDynamicTool`, are registered or unregistered as they change.
+- **Cleaned up.** Every tool is unregistered when `server.dispose()` runs.
+
+An agent's call runs the server's `tools:call-tool` flow, so hooks, authorities, quota and
+`availableWhen` apply to it as they do to any MCP client.
+
+## 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.        |
+
+## Choosing which tools agents see
+
+Tools are listed through the `'webmcp'` call surface, so `availableWhen` decides per tool:
+
+```typescript
+@Tool({ name: 'checkout', availableWhen: { surface: ['webmcp'] } }) // in-browser agents only
+@Tool({ name: 'admin_reset', availableWhen: { surface: ['mcp'] } }) // never exposed through WebMCP
+```
+
+## How tools are translated
+
+- **Names.** Names become WebMCP-valid. Characters outside `[A-Za-z0-9_.-]` become `_` (so
+  `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`.
+- **Errors.** An error result (`isError`), or an error from the server, rejects with its message.
+
+## Browser support
+
+WebMCP is in origin trial in Chrome and Edge (Chrome 149+). For local development, enable
+`chrome://flags/#enable-webmcp-testing`.
+
+Where `document.modelContext` is missing, the plugin does nothing; `isWebMcpSupported()` tells you
+up front. To support other browsers, load a polyfill that installs `document.modelContext` before
+creating the server, such as [`@mcp-b/global`](https://github.com/WebMCP-org/npm-packages) (which
+also bridges the page's tools to the MCP-B browser extension), or pass one as `modelContext`.
+
+WebMCP exposes tools only: resources and prompts stay MCP-only.

package/esm/index.mjs

@@ -0,0 +1,329 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// plugins/plugin-webmcp/src/webmcp.plugin.ts
+import { DynamicPlugin, Plugin, ScopeEntry } from "@frontmcp/sdk";
+
+// plugins/plugin-webmcp/src/webmcp.bridge.ts
+import {
+  FlowControl,
+  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;
+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;
+}
+function toWebMcpToolName(name) {
+  const cleaned = name.replace(INVALID_NAME_CHARACTERS, "_").slice(0, MAX_WEBMCP_NAME_LENGTH);
+  return cleaned.length > 0 ? cleaned : "_";
+}
+function uniqueName(base, taken) {
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const suffix = `_${n}`;
+    const candidate = base.slice(0, MAX_WEBMCP_NAME_LENGTH - suffix.length) + suffix;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+function toWebMcpAnnotations(annotations) {
+  const hints = {};
+  if (annotations?.readOnlyHint === true) hints.readOnlyHint = true;
+  if (annotations?.destructiveHint === true) hints.consequentialHint = true;
+  if (annotations?.openWorldHint === true) hints.untrustedContentHint = true;
+  return Object.keys(hints).length > 0 ? hints : void 0;
+}
+function textOf(content) {
+  return (content ?? []).map((block) => block.type === "text" ? block.text : "").filter((text) => text.length > 0).join("\n");
+}
+function errorBehindFlowControl(error) {
+  if (!(error instanceof FlowControl)) return error;
+  const original = error.originalError;
+  if (error.type === "fail" && original !== void 0) return original;
+  return new InternalMcpError(`Flow ended with: ${error.type}`);
+}
+function toAgentError(error) {
+  const failure = errorBehindFlowControl(error);
+  const publicMessage = failure?.getPublicMessage;
+  if (typeof publicMessage === "function") return new Error(publicMessage.call(failure));
+  return failure instanceof Error ? failure : new Error(String(failure));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var WebMcpBridge = class {
+  constructor(scope, options) {
+    this.scope = scope;
+    this.options = options;
+    this.logger = scope.logger.child("webmcp");
+  }
+  scope;
+  options;
+  logger;
+  sessionId = `webmcp:${randomUUID()}`;
+  registrations = /* @__PURE__ */ new Map();
+  /** Registrations the ModelContext refused, by name, so the same refusal is reported once. */
+  refused = /* @__PURE__ */ new Map();
+  modelContext;
+  unsubscribe;
+  started = false;
+  stopped = false;
+  /** A registry change arrived that no sync has picked up yet. */
+  pending = false;
+  /** The scheduled or running sync loop. */
+  run;
+  /** WebMCP names of the tools currently registered with the ModelContext. */
+  get registeredToolNames() {
+    return [...this.registrations.keys()];
+  }
+  /**
+   * Find the ModelContext and keep it in sync with the server's tools. Without one (Node, a browser
+   * without WebMCP and no polyfill) the bridge does nothing.
+   */
+  start() {
+    if (this.started || this.stopped) return;
+    this.started = true;
+    const modelContext = this.options.modelContext ?? resolveDocumentModelContext();
+    if (!modelContext) {
+      this.logger.debug("WebMCP is not available here (no document.modelContext); tools are not exposed");
+      return;
+    }
+    this.modelContext = modelContext;
+    this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, () => this.refresh());
+  }
+  /**
+   * Re-list the server's tools and update the registrations. The bridge does this on every tool
+   * registry change; call it when something else changes what the caller may see, such as the
+   * `authContext` a function option returns.
+   */
+  refresh() {
+    if (!this.modelContext || this.stopped) return;
+    this.pending = true;
+    this.run ??= this.drain();
+  }
+  /** Resolves once no sync is scheduled or running. */
+  async whenIdle() {
+    while (this.run) await this.run;
+  }
+  /** Unregister every tool and stop following the registry. Calling it again does nothing. */
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.unsubscribe?.();
+    this.unsubscribe = void 0;
+    for (const registration of this.registrations.values()) registration.controller.abort();
+    this.registrations.clear();
+  }
+  /** Sync until no change is pending. Starts a microtask later, so a burst of changes syncs once. */
+  async drain() {
+    await Promise.resolve();
+    try {
+      while (this.pending && !this.stopped) {
+        this.pending = false;
+        try {
+          await this.sync();
+        } catch (error) {
+          this.logger.warn(`WebMCP sync failed: ${toAgentError(error).message}`);
+        }
+      }
+    } finally {
+      this.run = void 0;
+    }
+  }
+  async sync() {
+    const desired = this.desiredTools(await this.listTools());
+    if (this.stopped) return;
+    for (const [name, registration] of this.registrations) {
+      if (desired.get(name)?.fingerprint === registration.fingerprint) continue;
+      registration.controller.abort();
+      this.registrations.delete(name);
+    }
+    for (const [name, tool] of desired) {
+      if (this.registrations.has(name) || this.stopped) continue;
+      await this.register(name, tool);
+    }
+  }
+  /** The server's tools as the `'webmcp'` surface sees them, every page of them. */
+  async listTools() {
+    const tools = [];
+    const authInfo = await this.authInfo();
+    let cursor;
+    do {
+      const request = { method: "tools/list", params: cursor === void 0 ? {} : { cursor } };
+      const page = await this.exclusive(
+        () => this.scope.runFlowForOutput("tools:list-tools", { request, ctx: { authInfo, surface: "webmcp" } })
+      );
+      tools.push(...page.tools);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return tools;
+  }
+  desiredTools(listed) {
+    const desired = /* @__PURE__ */ new Map();
+    for (const tool of listed) {
+      if (this.options.include && !this.options.include(tool)) continue;
+      const name = uniqueName(toWebMcpToolName(this.options.prefix + tool.name), new Set(desired.keys()));
+      const title = tool.title ?? tool.annotations?.title;
+      const annotations = toWebMcpAnnotations(tool.annotations);
+      const descriptor = {
+        name,
+        ...title && { title },
+        description: tool.description || title || tool.name,
+        inputSchema: tool.inputSchema,
+        ...annotations && { annotations }
+      };
+      desired.set(name, { mcpName: tool.name, descriptor, fingerprint: JSON.stringify([tool.name, descriptor]) });
+    }
+    return desired;
+  }
+  async register(name, tool) {
+    const modelContext = this.modelContext;
+    const controller = new AbortController();
+    this.registrations.set(name, { mcpName: tool.mcpName, fingerprint: tool.fingerprint, controller });
+    try {
+      await modelContext.registerTool(
+        { ...tool.descriptor, execute: (input, options) => this.execute(tool.mcpName, input, options) },
+        { signal: controller.signal, ...this.options.exposedTo && { exposedTo: this.options.exposedTo } }
+      );
+      this.refused.delete(name);
+    } catch (error) {
+      if (this.registrations.get(name)?.controller === controller) this.registrations.delete(name);
+      controller.abort();
+      const message = `WebMCP refused tool "${name}": ${toAgentError(error).message}`;
+      if (this.refused.get(name) === tool.fingerprint) {
+        this.logger.debug(message);
+      } else {
+        this.refused.set(name, tool.fingerprint);
+        this.logger.warn(message);
+      }
+    }
+  }
+  /** Run one agent call through the `tools:call-tool` flow, and translate its result for WebMCP. */
+  async execute(mcpName, input, options) {
+    let result;
+    try {
+      const request = {
+        method: "tools/call",
+        params: { name: mcpName, arguments: isRecord(input) ? input : {} }
+      };
+      const ctx = {
+        authInfo: await this.authInfo(),
+        surface: "webmcp",
+        ...options?.signal && { signal: options.signal }
+      };
+      result = await this.exclusive(() => this.scope.runFlowForOutput("tools:call-tool", { request, ctx }));
+    } catch (error) {
+      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 }
+    };
+  }
+  /**
+   * Run a flow as its own request. A browser build without AsyncContext runs requests one at a
+   * time; this takes the turn. A flow that answers by `respond` is output, not a failure.
+   */
+  async exclusive(runFlow) {
+    try {
+      return await runRequestExclusive(runFlow);
+    } catch (error) {
+      if (error instanceof FlowControl && error.type === "respond") return error.output;
+      throw error;
+    }
+  }
+  /** The caller the flows see: the `authContext` option, or an anonymous `webmcp` caller. */
+  async authInfo() {
+    const option = this.options.authContext;
+    const authContext = typeof option === "function" ? await option() : option;
+    const user = authContext?.user;
+    const sub = typeof user?.sub === "string" ? user.sub : "webmcp";
+    const iss = typeof user?.["iss"] === "string" ? user["iss"] : "webmcp";
+    return {
+      sessionId: authContext?.sessionId ?? this.sessionId,
+      user: { ...user, iss, sub },
+      scopes: [],
+      clientId: sub,
+      ...authContext?.token !== void 0 && { token: authContext.token },
+      ...authContext?.extra && { extra: authContext.extra }
+    };
+  }
+};
+
+// plugins/plugin-webmcp/src/webmcp.options.ts
+import { z } from "@frontmcp/lazy-zod";
+function isModelContext(value) {
+  return typeof value === "object" && value !== null && typeof value.registerTool === "function";
+}
+var webMcpPluginOptionsSchema = z.object({
+  /**
+   * Prepended to every exposed tool name, e.g. `'shop.'`, so the page's tools stay apart from
+   * other tools on it. Names are then made WebMCP-valid (see `toWebMcpToolName`).
+   */
+  prefix: z.string().default(""),
+  /** Decides which listed tools are exposed. Runs after `availableWhen` and authorities. */
+  include: z.custom((value) => typeof value === "function").optional(),
+  /** Other origins (e.g. an iframe's parent) the tools are offered to, through WebMCP's `exposedTo`. */
+  exposedTo: z.array(z.string().min(1)).optional(),
+  /** 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()
+});
+
+// plugins/plugin-webmcp/src/webmcp.plugin.ts
+var WebMcpPlugin = class extends DynamicPlugin {
+  options;
+  constructor(options = {}) {
+    super();
+    this.options = webMcpPluginOptionsSchema.parse(options);
+  }
+  static dynamicProviders(options) {
+    const parsedOptions = webMcpPluginOptionsSchema.parse(options);
+    return [
+      {
+        name: "webmcp:bridge",
+        provide: WebMcpBridge,
+        inject: () => [ScopeEntry],
+        useFactory: (scope) => {
+          const bridge = new WebMcpBridge(scope, parsedOptions);
+          void scope.ready.then(
+            () => bridge.start(),
+            () => void 0
+            // the scope failed to start, and reports that itself
+          );
+          scope.onDispose(() => bridge.stop());
+          return bridge;
+        }
+      }
+    ];
+  }
+};
+WebMcpPlugin = __decorateClass([
+  Plugin({
+    name: "webmcp",
+    description: "Exposes the server's tools to in-browser agents through WebMCP (document.modelContext)"
+  })
+], WebMcpPlugin);
+export {
+  WebMcpBridge,
+  WebMcpPlugin,
+  WebMcpPlugin as default,
+  isWebMcpSupported,
+  toWebMcpToolName,
+  webMcpPluginOptionsSchema
+};

package/esm/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@frontmcp/plugin-webmcp",
+  "version": "1.5.7",
+  "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",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "webmcp",
+    "modelcontext",
+    "browser",
+    "agents",
+    "plugin",
+    "frontmcp",
+    "agentfront"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "plugins/plugin-webmcp"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/plugins/plugin-webmcp/README.md",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "../index.js",
+  "module": "./index.mjs",
+  "types": "../index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "../package.json",
+    ".": {
+      "require": {
+        "types": "../index.d.ts",
+        "default": "../index.js"
+      },
+      "import": {
+        "types": "../index.d.ts",
+        "default": "./index.mjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "1.5.7",
+    "@frontmcp/utils": "1.5.7"
+  },
+  "peerDependencies": {
+    "@frontmcp/lazy-zod": "1.5.7"
+  },
+  "devDependencies": {
+    "reflect-metadata": "^0.2.2"
+  }
+}

package/index.d.ts

@@ -0,0 +1,5 @@
+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 type { ModelContext, ModelContextRegisterToolOptions, ModelContextRegisteredTool, ModelContextTool, ModelContextToolAnnotations, ModelContextToolExecuteOptions, } from './webmcp.types';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +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"}

package/index.js

@@ -0,0 +1,346 @@
+"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);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// plugins/plugin-webmcp/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  WebMcpBridge: () => WebMcpBridge,
+  WebMcpPlugin: () => WebMcpPlugin,
+  default: () => WebMcpPlugin,
+  isWebMcpSupported: () => isWebMcpSupported,
+  toWebMcpToolName: () => toWebMcpToolName,
+  webMcpPluginOptionsSchema: () => webMcpPluginOptionsSchema
+});
+module.exports = __toCommonJS(index_exports);
+
+// plugins/plugin-webmcp/src/webmcp.plugin.ts
+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;
+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;
+}
+function toWebMcpToolName(name) {
+  const cleaned = name.replace(INVALID_NAME_CHARACTERS, "_").slice(0, MAX_WEBMCP_NAME_LENGTH);
+  return cleaned.length > 0 ? cleaned : "_";
+}
+function uniqueName(base, taken) {
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const suffix = `_${n}`;
+    const candidate = base.slice(0, MAX_WEBMCP_NAME_LENGTH - suffix.length) + suffix;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+function toWebMcpAnnotations(annotations) {
+  const hints = {};
+  if (annotations?.readOnlyHint === true) hints.readOnlyHint = true;
+  if (annotations?.destructiveHint === true) hints.consequentialHint = true;
+  if (annotations?.openWorldHint === true) hints.untrustedContentHint = true;
+  return Object.keys(hints).length > 0 ? hints : void 0;
+}
+function textOf(content) {
+  return (content ?? []).map((block) => block.type === "text" ? block.text : "").filter((text) => text.length > 0).join("\n");
+}
+function errorBehindFlowControl(error) {
+  if (!(error instanceof import_sdk.FlowControl)) return error;
+  const original = error.originalError;
+  if (error.type === "fail" && original !== void 0) return original;
+  return new import_sdk.InternalMcpError(`Flow ended with: ${error.type}`);
+}
+function toAgentError(error) {
+  const failure = errorBehindFlowControl(error);
+  const publicMessage = failure?.getPublicMessage;
+  if (typeof publicMessage === "function") return new Error(publicMessage.call(failure));
+  return failure instanceof Error ? failure : new Error(String(failure));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var WebMcpBridge = class {
+  constructor(scope, options) {
+    this.scope = scope;
+    this.options = options;
+    this.logger = scope.logger.child("webmcp");
+  }
+  scope;
+  options;
+  logger;
+  sessionId = `webmcp:${(0, import_utils.randomUUID)()}`;
+  registrations = /* @__PURE__ */ new Map();
+  /** Registrations the ModelContext refused, by name, so the same refusal is reported once. */
+  refused = /* @__PURE__ */ new Map();
+  modelContext;
+  unsubscribe;
+  started = false;
+  stopped = false;
+  /** A registry change arrived that no sync has picked up yet. */
+  pending = false;
+  /** The scheduled or running sync loop. */
+  run;
+  /** WebMCP names of the tools currently registered with the ModelContext. */
+  get registeredToolNames() {
+    return [...this.registrations.keys()];
+  }
+  /**
+   * Find the ModelContext and keep it in sync with the server's tools. Without one (Node, a browser
+   * without WebMCP and no polyfill) the bridge does nothing.
+   */
+  start() {
+    if (this.started || this.stopped) return;
+    this.started = true;
+    const modelContext = this.options.modelContext ?? resolveDocumentModelContext();
+    if (!modelContext) {
+      this.logger.debug("WebMCP is not available here (no document.modelContext); tools are not exposed");
+      return;
+    }
+    this.modelContext = modelContext;
+    this.unsubscribe = this.scope.tools.subscribe({ immediate: true }, () => this.refresh());
+  }
+  /**
+   * Re-list the server's tools and update the registrations. The bridge does this on every tool
+   * registry change; call it when something else changes what the caller may see, such as the
+   * `authContext` a function option returns.
+   */
+  refresh() {
+    if (!this.modelContext || this.stopped) return;
+    this.pending = true;
+    this.run ??= this.drain();
+  }
+  /** Resolves once no sync is scheduled or running. */
+  async whenIdle() {
+    while (this.run) await this.run;
+  }
+  /** Unregister every tool and stop following the registry. Calling it again does nothing. */
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.unsubscribe?.();
+    this.unsubscribe = void 0;
+    for (const registration of this.registrations.values()) registration.controller.abort();
+    this.registrations.clear();
+  }
+  /** Sync until no change is pending. Starts a microtask later, so a burst of changes syncs once. */
+  async drain() {
+    await Promise.resolve();
+    try {
+      while (this.pending && !this.stopped) {
+        this.pending = false;
+        try {
+          await this.sync();
+        } catch (error) {
+          this.logger.warn(`WebMCP sync failed: ${toAgentError(error).message}`);
+        }
+      }
+    } finally {
+      this.run = void 0;
+    }
+  }
+  async sync() {
+    const desired = this.desiredTools(await this.listTools());
+    if (this.stopped) return;
+    for (const [name, registration] of this.registrations) {
+      if (desired.get(name)?.fingerprint === registration.fingerprint) continue;
+      registration.controller.abort();
+      this.registrations.delete(name);
+    }
+    for (const [name, tool] of desired) {
+      if (this.registrations.has(name) || this.stopped) continue;
+      await this.register(name, tool);
+    }
+  }
+  /** The server's tools as the `'webmcp'` surface sees them, every page of them. */
+  async listTools() {
+    const tools = [];
+    const authInfo = await this.authInfo();
+    let cursor;
+    do {
+      const request = { method: "tools/list", params: cursor === void 0 ? {} : { cursor } };
+      const page = await this.exclusive(
+        () => this.scope.runFlowForOutput("tools:list-tools", { request, ctx: { authInfo, surface: "webmcp" } })
+      );
+      tools.push(...page.tools);
+      cursor = page.nextCursor;
+    } while (cursor);
+    return tools;
+  }
+  desiredTools(listed) {
+    const desired = /* @__PURE__ */ new Map();
+    for (const tool of listed) {
+      if (this.options.include && !this.options.include(tool)) continue;
+      const name = uniqueName(toWebMcpToolName(this.options.prefix + tool.name), new Set(desired.keys()));
+      const title = tool.title ?? tool.annotations?.title;
+      const annotations = toWebMcpAnnotations(tool.annotations);
+      const descriptor = {
+        name,
+        ...title && { title },
+        description: tool.description || title || tool.name,
+        inputSchema: tool.inputSchema,
+        ...annotations && { annotations }
+      };
+      desired.set(name, { mcpName: tool.name, descriptor, fingerprint: JSON.stringify([tool.name, descriptor]) });
+    }
+    return desired;
+  }
+  async register(name, tool) {
+    const modelContext = this.modelContext;
+    const controller = new AbortController();
+    this.registrations.set(name, { mcpName: tool.mcpName, fingerprint: tool.fingerprint, controller });
+    try {
+      await modelContext.registerTool(
+        { ...tool.descriptor, execute: (input, options) => this.execute(tool.mcpName, input, options) },
+        { signal: controller.signal, ...this.options.exposedTo && { exposedTo: this.options.exposedTo } }
+      );
+      this.refused.delete(name);
+    } catch (error) {
+      if (this.registrations.get(name)?.controller === controller) this.registrations.delete(name);
+      controller.abort();
+      const message = `WebMCP refused tool "${name}": ${toAgentError(error).message}`;
+      if (this.refused.get(name) === tool.fingerprint) {
+        this.logger.debug(message);
+      } else {
+        this.refused.set(name, tool.fingerprint);
+        this.logger.warn(message);
+      }
+    }
+  }
+  /** Run one agent call through the `tools:call-tool` flow, and translate its result for WebMCP. */
+  async execute(mcpName, input, options) {
+    let result;
+    try {
+      const request = {
+        method: "tools/call",
+        params: { name: mcpName, arguments: isRecord(input) ? input : {} }
+      };
+      const ctx = {
+        authInfo: await this.authInfo(),
+        surface: "webmcp",
+        ...options?.signal && { signal: options.signal }
+      };
+      result = await this.exclusive(() => this.scope.runFlowForOutput("tools:call-tool", { request, ctx }));
+    } catch (error) {
+      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 }
+    };
+  }
+  /**
+   * Run a flow as its own request. A browser build without AsyncContext runs requests one at a
+   * time; this takes the turn. A flow that answers by `respond` is output, not a failure.
+   */
+  async exclusive(runFlow) {
+    try {
+      return await (0, import_utils.runRequestExclusive)(runFlow);
+    } catch (error) {
+      if (error instanceof import_sdk.FlowControl && error.type === "respond") return error.output;
+      throw error;
+    }
+  }
+  /** The caller the flows see: the `authContext` option, or an anonymous `webmcp` caller. */
+  async authInfo() {
+    const option = this.options.authContext;
+    const authContext = typeof option === "function" ? await option() : option;
+    const user = authContext?.user;
+    const sub = typeof user?.sub === "string" ? user.sub : "webmcp";
+    const iss = typeof user?.["iss"] === "string" ? user["iss"] : "webmcp";
+    return {
+      sessionId: authContext?.sessionId ?? this.sessionId,
+      user: { ...user, iss, sub },
+      scopes: [],
+      clientId: sub,
+      ...authContext?.token !== void 0 && { token: authContext.token },
+      ...authContext?.extra && { extra: authContext.extra }
+    };
+  }
+};
+
+// plugins/plugin-webmcp/src/webmcp.options.ts
+var import_lazy_zod = require("@frontmcp/lazy-zod");
+function isModelContext(value) {
+  return typeof value === "object" && value !== null && typeof value.registerTool === "function";
+}
+var webMcpPluginOptionsSchema = import_lazy_zod.z.object({
+  /**
+   * Prepended to every exposed tool name, e.g. `'shop.'`, so the page's tools stay apart from
+   * other tools on it. Names are then made WebMCP-valid (see `toWebMcpToolName`).
+   */
+  prefix: import_lazy_zod.z.string().default(""),
+  /** Decides which listed tools are exposed. Runs after `availableWhen` and authorities. */
+  include: import_lazy_zod.z.custom((value) => typeof value === "function").optional(),
+  /** Other origins (e.g. an iframe's parent) the tools are offered to, through WebMCP's `exposedTo`. */
+  exposedTo: import_lazy_zod.z.array(import_lazy_zod.z.string().min(1)).optional(),
+  /** 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()
+});
+
+// plugins/plugin-webmcp/src/webmcp.plugin.ts
+var WebMcpPlugin = class extends import_sdk2.DynamicPlugin {
+  options;
+  constructor(options = {}) {
+    super();
+    this.options = webMcpPluginOptionsSchema.parse(options);
+  }
+  static dynamicProviders(options) {
+    const parsedOptions = webMcpPluginOptionsSchema.parse(options);
+    return [
+      {
+        name: "webmcp:bridge",
+        provide: WebMcpBridge,
+        inject: () => [import_sdk2.ScopeEntry],
+        useFactory: (scope) => {
+          const bridge = new WebMcpBridge(scope, parsedOptions);
+          void scope.ready.then(
+            () => bridge.start(),
+            () => void 0
+            // the scope failed to start, and reports that itself
+          );
+          scope.onDispose(() => bridge.stop());
+          return bridge;
+        }
+      }
+    ];
+  }
+};
+WebMcpPlugin = __decorateClass([
+  (0, import_sdk2.Plugin)({
+    name: "webmcp",
+    description: "Exposes the server's tools to in-browser agents through WebMCP (document.modelContext)"
+  })
+], WebMcpPlugin);

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@frontmcp/plugin-webmcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "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",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "webmcp",
+    "modelcontext",
+    "browser",
+    "agents",
+    "plugin",
+    "frontmcp",
+    "agentfront"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git",
+    "directory": "plugins/plugin-webmcp"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
+  "homepage": "https://github.com/agentfront/frontmcp/blob/main/plugins/plugin-webmcp/README.md",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "commonjs",
+  "main": "./index.js",
+  "module": "./esm/index.mjs",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      },
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./esm/index.mjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "1.5.7",
+    "@frontmcp/utils": "1.5.7"
+  },
+  "peerDependencies": {
+    "@frontmcp/lazy-zod": "1.5.7"
+  },
+  "devDependencies": {
+    "reflect-metadata": "^0.2.2"
+  }
+}

package/webmcp.bridge.d.ts

@@ -0,0 +1,73 @@
+/**
+ * WebMcpBridge - exposes a FrontMCP server's tools to in-browser agents through WebMCP.
+ *
+ * It is a transport adapter: it only translates. The tool list comes from the `tools:list-tools`
+ * flow and every call runs the `tools:call-tool` flow, both on the `'webmcp'` surface, so
+ * `availableWhen`, authorities, hooks and quota apply to an agent's calls as to any other client's.
+ */
+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 {
+    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;
+/** 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 {
+    private readonly scope;
+    private readonly options;
+    private readonly logger;
+    private readonly sessionId;
+    private readonly registrations;
+    /** Registrations the ModelContext refused, by name, so the same refusal is reported once. */
+    private readonly refused;
+    private modelContext?;
+    private unsubscribe?;
+    private started;
+    private stopped;
+    /** A registry change arrived that no sync has picked up yet. */
+    private pending;
+    /** The scheduled or running sync loop. */
+    private run?;
+    constructor(scope: ScopeEntry, options: WebMcpPluginOptions);
+    /** WebMCP names of the tools currently registered with the ModelContext. */
+    get registeredToolNames(): string[];
+    /**
+     * Find the ModelContext and keep it in sync with the server's tools. Without one (Node, a browser
+     * without WebMCP and no polyfill) the bridge does nothing.
+     */
+    start(): void;
+    /**
+     * Re-list the server's tools and update the registrations. The bridge does this on every tool
+     * registry change; call it when something else changes what the caller may see, such as the
+     * `authContext` a function option returns.
+     */
+    refresh(): void;
+    /** Resolves once no sync is scheduled or running. */
+    whenIdle(): Promise<void>;
+    /** Unregister every tool and stop following the registry. Calling it again does nothing. */
+    stop(): void;
+    /** Sync until no change is pending. Starts a microtask later, so a burst of changes syncs once. */
+    private drain;
+    private sync;
+    /** The server's tools as the `'webmcp'` surface sees them, every page of them. */
+    private listTools;
+    private desiredTools;
+    private register;
+    /** Run one agent call through the `tools:call-tool` flow, and translate its result for WebMCP. */
+    private execute;
+    /**
+     * Run a flow as its own request. A browser build without AsyncContext runs requests one at a
+     * time; this takes the turn. A flow that answers by `respond` is output, not a failure.
+     */
+    private exclusive;
+    /** The caller the flows see: the `authContext` option, or an anonymous `webmcp` caller. */
+    private authInfo;
+}
+//# sourceMappingURL=webmcp.bridge.d.ts.map

package/webmcp.bridge.d.ts.map

@@ -0,0 +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;AA0BD,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;CAevB"}

package/webmcp.options.d.ts

@@ -0,0 +1,19 @@
+import { z } from '@frontmcp/lazy-zod';
+import type { DirectAuthContext, ListToolsResult } from '@frontmcp/sdk';
+import type { ModelContext } from './webmcp.types';
+/** A tool as the server lists it (`tools/list`), before it is exposed through WebMCP. */
+export type WebMcpListedTool = ListToolsResult['tools'][number];
+/** Who the server sees calling: an auth context, or a function that returns the current one. */
+export type WebMcpAuthContext = DirectAuthContext | (() => DirectAuthContext | Promise<DirectAuthContext>);
+export declare const webMcpPluginOptionsSchema: import("@frontmcp/lazy-zod").ZodObject<{
+    prefix: import("@frontmcp/lazy-zod").ZodDefault<import("@frontmcp/lazy-zod").ZodString>;
+    include: import("@frontmcp/lazy-zod").ZodOptional<import("zod").ZodCustom<(tool: WebMcpListedTool) => boolean, (tool: WebMcpListedTool) => boolean>>;
+    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>>;
+}, import("zod/v4/core").$strip>;
+/** Options of `WebMcpPlugin.init()`, as the plugin holds them (defaults applied). */
+export type WebMcpPluginOptions = z.output<typeof webMcpPluginOptionsSchema>;
+/** Options of `WebMcpPlugin.init()`, as passed. */
+export type WebMcpPluginOptionsInput = z.input<typeof webMcpPluginOptionsSchema>;
+//# sourceMappingURL=webmcp.options.d.ts.map

package/webmcp.options.d.ts.map

@@ -0,0 +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"}

package/webmcp.plugin.d.ts

@@ -0,0 +1,25 @@
+import { DynamicPlugin, type ProviderType } from '@frontmcp/sdk';
+import { type WebMcpPluginOptions, type WebMcpPluginOptionsInput } from './webmcp.options';
+/**
+ * Exposes the server's tools to in-browser agents through WebMCP (`document.modelContext`).
+ *
+ * Install it on a server that runs in the page, with `WebMcpPlugin.init()`:
+ *
+ * ```typescript
+ * const server = await create({
+ *   info: { name: 'shop', version: '1.0.0' },
+ *   tools: [SearchProducts, AddToCart],
+ *   plugins: [WebMcpPlugin.init({ prefix: 'shop.' })],
+ * });
+ * ```
+ *
+ * Every tool the `'webmcp'` surface may list is registered once the server is ready, kept in sync as
+ * tools come and go (including tools added with `server.registerTool()`), and unregistered when the
+ * server is disposed. Calls run the `tools:call-tool` flow, so hooks, authorities and quota apply.
+ */
+export default class WebMcpPlugin extends DynamicPlugin<WebMcpPluginOptions, WebMcpPluginOptionsInput> {
+    readonly options: WebMcpPluginOptions;
+    constructor(options?: WebMcpPluginOptionsInput);
+    static dynamicProviders(options: WebMcpPluginOptionsInput): ProviderType[];
+}
+//# sourceMappingURL=webmcp.plugin.d.ts.map

package/webmcp.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.plugin.d.ts","sourceRoot":"","sources":["../src/webmcp.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAsB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAGrF,OAAO,EAA6B,KAAK,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEtH;;;;;;;;;;;;;;;;GAgBG;AAKH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,aAAa,CAAC,mBAAmB,EAAE,wBAAwB,CAAC;IACpG,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;gBAE1B,OAAO,GAAE,wBAA6B;WAKlC,gBAAgB,CAAC,OAAO,EAAE,wBAAwB,GAAG,YAAY,EAAE;CAqBpF"}

package/webmcp.types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The part of the WebMCP API (`document.modelContext`) this plugin uses, per the W3C Web Machine
+ * Learning CG draft of 2026-09-30 (https://webmachinelearning.github.io/webmcp/).
+ *
+ * Declared here rather than taken from a types package: the API is still in origin trial and
+ * changes between Chrome releases, so the plugin pins the shape it was written against.
+ */
+/** Behavioral hints an agent may use to decide how carefully to call a tool. */
+export interface ModelContextToolAnnotations {
+    /** The tool only reads state. */
+    readOnlyHint?: boolean;
+    /** The tool's output may contain content the page does not vouch for. */
+    untrustedContentHint?: boolean;
+    /** The tool has consequences the user may want to confirm (purchases, deletions, messages). */
+    consequentialHint?: boolean;
+}
+/** What `execute` receives besides its input. */
+export interface ModelContextToolExecuteOptions {
+    /** Aborted when the agent cancels the call. */
+    signal: AbortSignal;
+}
+/** A tool as the page registers it. */
+export interface ModelContextTool {
+    /** 1-128 characters from `[A-Za-z0-9_.-]`, unique among the page's tools. */
+    name: string;
+    title?: string;
+    /** Required and non-empty. */
+    description: string;
+    /** JSON Schema of the input object. */
+    inputSchema?: Record<string, unknown>;
+    /** Runs the tool. Its result is JSON-serialized for the agent; a rejection is a failed call. */
+    execute(input: Record<string, unknown>, options: ModelContextToolExecuteOptions): Promise<unknown>;
+    annotations?: ModelContextToolAnnotations;
+}
+/** Options of `registerTool`. Aborting `signal` unregisters the tool. */
+export interface ModelContextRegisterToolOptions {
+    /** Other origins (e.g. the parent of an iframe) the tool is offered to. */
+    exposedTo?: string[];
+    signal?: AbortSignal;
+}
+/** A tool as `getTools()` describes it. */
+export interface ModelContextRegisteredTool {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    origin?: string;
+    annotations?: ModelContextToolAnnotations;
+}
+/** `document.modelContext`. */
+export interface ModelContext {
+    /**
+     * Register a tool. Rejects with `InvalidStateError` for a duplicate or invalid name, and with
+     * `NotAllowedError` when the `tools` permissions policy denies it.
+     */
+    registerTool(tool: ModelContextTool, options?: ModelContextRegisterToolOptions): Promise<void>;
+    /** The tools registered in this page (and, with `fromOrigins`, those other origins expose to it). */
+    getTools?(options?: {
+        fromOrigins?: string[];
+    }): Promise<ModelContextRegisteredTool[]>;
+    /** Run a registered tool, as an in-page agent would. Resolves to the JSON-serialized result. */
+    executeTool?(tool: ModelContextRegisteredTool, input?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+}
+//# sourceMappingURL=webmcp.types.d.ts.map

package/webmcp.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webmcp.types.d.ts","sourceRoot":"","sources":["../src/webmcp.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,gFAAgF;AAChF,MAAM,WAAW,2BAA2B;IAC1C,iCAAiC;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,8BAA8B;IAC7C,+CAA+C;IAC/C,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,gGAAgG;IAChG,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnG,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,+BAA+B;IAC9C,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,2BAA2B,CAAC;CAC3C;AAED,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,+BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,qGAAqG;IACrG,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACvF,gGAAgG;IAChG,WAAW,CAAC,CACV,IAAI,EAAE,0BAA0B,EAChC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B"}