portage-ucp-webmcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b780435e8c5d1af1fe7c6943d789685242346aba2182ed99a1b53f42fce98d7
+  data.tar.gz: 90bc20baab307b0659242608563ff785db1e311413beb04d65600bd0d78e0d9b
+SHA512:
+  metadata.gz: 254d23426d3384ad535c75f618c2d53174742337e2d9d4989905a861b241e3233636ea700067033177a423eedd3cc1e75b655099126315aa02b72e47f53d7e36
+  data.tar.gz: 17b34c2da562e7394402ada1bf6f9989600c5cc4a55ef803bc35a42cfbf260cd2e6537973e4e1d07c7698c57727477d0ecb22202c36bbcce7fc0e3aebeb7d75f

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
+pre-1.0, so APIs may still shift between minor versions.
+
+## [0.1.0] - Unreleased
+
+- Initial release. WebMCP as a transport to the existing `Adapter` contract.
+- The registrar reports a non-JSON reply from its endpoint (a proxy's HTML
+  error page) as `tools/call to <endpoint> returned a non-JSON response
+  (<status>)`, rather than a bare `Unexpected token '<'`.
+- Inbound (merchant side): `ToolCatalog` derives the tools a page registers
+  from `Portage::Ucp::Mcp::Server`'s own tools/list. It adds readable
+  descriptions, typed parameter schemas and WebMCP annotations.
+  `Rack::App` serves the page registrar (`GET /webmcp.js`) and its call
+  endpoint (`POST /webmcp`). The endpoint accepts JSON only, requires a
+  matching `Origin`, and allows only `tools/call`/`tools/list` for exposed
+  actions. It hands the Rack request to the Authenticator. OAuth-token and
+  stored-credential tools are left out by default. `complete_checkout` is
+  also left out by default, because the Dispatcher's default Terminal
+  Confirmer would block the web request.
+- Outbound (agent side): `Transport` is a `portage-ucp-client` transport over
+  any page's WebMCP tools. It supports the spec surface, the
+  `modelContextTesting` surface and the userland-polyfill surface. It
+  resolves tool names with `tool_names:`/`prefix:`, and it picks flat or
+  real-UCP argument shapes from each tool's schema.
+  `Bridges::ScriptEvaluator` works with Ferrum, Playwright, Selenium or any
+  JavaScript-evaluating callable. `WebMcp.connect` returns a
+  `Client::Session`.
+- `WebMcp.polyfill_js`: a minimal, spec-shaped `document.modelContext` for
+  browsers without native WebMCP.
+- `Transport` waits out a page that drops and re-registers its tools
+  mid-call (`reregister_wait:`, default 2s) instead of raising
+  `ToolNotFoundError` for a tool it had just found. Confirmed live on
+  Shopify storefronts, whose own `add_to_cart` tool leaves the page with no
+  tools for about 500ms.
+  - The wait is a blocking `sleep`, now documented under the README's
+    "Timeouts". Its one deadline covers the whole call, and the last poll
+    no longer sleeps past it: a 0.25s poll started 0.1s before the deadline
+    now sleeps 0.1s.
+- `ScriptEvaluator`'s `BridgeError` quotes at most 300 characters of the
+  driver's own error (and of an unreadable reply), the same cap
+  `portage-ucp-decision` uses for Jev. A Selenium failure can carry a DOM
+  dump or a stack trace, which used to land whole in an agent's context.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,275 @@
+# portage-ucp-webmcp
+
+[WebMCP](https://webmachinelearning.github.io/webmcp/) for
+[`portage-ucp`](https://github.com/tomtom87/Portage/tree/main/portage-ucp), as a
+**transport**, not a commerce backend. WebMCP lets a web page register tools on
+`document.modelContext` for an agent running in the browser to call. This gem
+makes that page one more way to reach the existing `Adapter` contract, next to
+classic MCP (stdio, Streamable HTTP) and native UCP.
+
+```
+                         ┌── stdio / Streamable HTTP ──┐
+Agent ── Session ────────┤── native UCP (HTTP) ────────┤── Mcp::Server ── Dispatcher ── Adapter
+                         └── WebMCP (a browser page) ──┘
+```
+
+Two halves, usable separately:
+
+| Half | Side | What it does |
+|---|---|---|
+| Inbound | Merchant | Registers a Portage-powered store's catalog/cart/checkout tools on its pages via `document.modelContext`. Each tool call POSTs back to the store, into the same `Portage::Ucp::Mcp::Server` every other transport uses. |
+| Outbound | Agent | A `portage-ucp-client` transport that finds and calls the WebMCP tools **any** page registers, Portage-powered or not, through the browser driver you already run. |
+
+The `Adapter` stays the single source of truth. The tool list comes from the
+`CapabilityRegistry`, as it does for MCP. Nothing commerce-related runs in the
+browser.
+
+## Inbound: expose your store to browser agents
+
+```ruby
+require "portage/ucp/webmcp"
+
+catalog = Portage::Ucp::WebMcp::ToolCatalog.new(
+  adapter: adapter,
+  authenticator: MyCookieAuthenticator.new # same Authenticator contract as MCP
+)
+
+# config.ru
+map("/ucp") { run Portage::Ucp::WebMcp::Rack::App.new(catalog: catalog) }
+
+# Rails
+mount Portage::Ucp::WebMcp::Rack::App.new(catalog: catalog), at: "/ucp"
+```
+
+```html
+<script src="/ucp/webmcp.js" defer></script>
+```
+
+`Rack::App` serves two routes under its mount point:
+
+| Route | Serves |
+|---|---|
+| `GET /webmcp.js` | The page script (`Registrar`). It registers each tool on `document.modelContext`, or on `navigator.modelContext` in earlier-draft browsers. |
+| `POST /webmcp` | Its tool calls (`Rack::CallEndpoint`). One stateless JSON-RPC `tools/call` in, one result out, answered by the catalog's `Mcp::Server`. |
+
+### What the page registers
+
+`ToolCatalog` decorates the MCP server's generated tools for browser agents:
+
+- Readable descriptions and typed JSON Schemas. `Mcp::Server` can only name
+  parameters, so every property there is `{}`.
+- WebMCP annotations: `readOnlyHint` for reads, and `consequentialHint` for
+  `cancel_order`, `refund_order`, `request_return` and `complete_checkout`.
+- `idempotency_key` is optional. The page generates one per mutating call when
+  the agent leaves it out.
+
+What the catalog exposes:
+
+- **Capabilities:** standard `dev.ucp.shopping.*` capabilities only, without
+  identity linking. Tools that take an OAuth token or manage stored credentials
+  (saved payment methods, saved addresses, shopper-data deletion, payment
+  enrollment) are left out. Widen with `capabilities: ->(name) { ... }`.
+- **`complete_checkout`:** left out (`DEFAULT_EXCEPT`). Over any server
+  transport it runs the Dispatcher's payment `Confirmer`. That defaults to
+  `Confirmer::Terminal`, which prompts on the server's stdin, and
+  `Mcp::Server.build` has no seam to replace it. On a web request that prompt
+  holds the request until it times out and denies. In the browser the shopper
+  is present anyway: the agent builds the checkout, and the shopper pays in the
+  store's own checkout (the checkout's `links` or `continue_url`). Opt in with
+  `except: []` only after you have solved confirmation.
+- **Filters:** `only:`, `except:` and `prefix:` (for example `prefix: "acme."`
+  when the page registers WebMCP tools of its own).
+
+`Rack::CallEndpoint` enforces the same filter on the server side. An action the
+page doesn't register can't be reached by POSTing its name.
+
+### Security
+
+The endpoint is browser-facing and the page's cookies go with every call. For
+that reason it is stricter than a plain MCP endpoint:
+
+- **JSON bodies only.** A cross-site `<form>` can't reach the endpoint without a
+  CORS preflight.
+- **`Origin` required.** The header must match `allowed_origins`. The default is
+  the endpoint's own origin. A request with no `Origin` is refused unless you
+  pass `require_origin: false`.
+- **Two methods only.** `tools/call` and `tools/list`, and only for exposed
+  actions.
+- **Same guards as MCP.** Mutating calls go through your `Authenticator` and
+  `RateLimiter`, exactly as over MCP. The `server_context` they receive carries
+  `transport: "webmcp"`, `request:` (the `Rack::Request`, for your session
+  cookie or a CSRF header) and `origin:`.
+
+Put a CSRF token on the page's requests with
+`registrar_options: { headers: { "x-csrf-token" => token } }` and check it in
+your `Authenticator`.
+
+For a storefront on another origin than the endpoint, use this pattern:
+
+```ruby
+Portage::Ucp::WebMcp::Rack::App.new(
+  catalog: catalog,
+  call_options: { allowed_origins: ["https://shop.example"] },
+  registrar_options: { endpoint: "https://api.shop.example/ucp/webmcp", credentials: "include" }
+)
+```
+
+The endpoint then answers the CORS preflight and sends credentialed CORS
+headers for that origin only.
+
+### Browsers without WebMCP
+
+When the page has no `modelContext`, the registrar does nothing. It records
+`window.portageWebMcp.reason = "no_model_context"`. Pass
+`registrar_options: { include_polyfill: true }` to install a minimal,
+spec-shaped `document.modelContext` first. That helps agents that drive a
+browser build without native WebMCP. A browser that has a native
+implementation keeps it.
+
+## Outbound: call any page's WebMCP tools from an agent
+
+```ruby
+require "portage/ucp/webmcp"
+
+page = Ferrum::Browser.new.create_page
+page.command("Page.addScriptToEvaluateOnNewDocument", source: Portage::Ucp::WebMcp.polyfill_js) # optional
+page.go_to("https://shop.example/products/mug")
+
+session = Portage::Ucp::WebMcp.connect(
+  bridge: Portage::Ucp::WebMcp::Bridges::ScriptEvaluator.ferrum(page)
+)
+session.search_catalog(query: "mug")
+session.create_checkout(line_items: [{ product_id: "mug", quantity: 1 }])
+```
+
+`session` is the same `Portage::Ucp::Client::Session` that
+`Client.for_adapter`, `.connect` and `.discover` return. It has the same
+methods, the same client-side `PaymentTokenGuard` and the same `ServerError`
+on a tool error. The caller doesn't need to know which transport it got.
+
+### Browser drivers
+
+No driver gem is a dependency. `ScriptEvaluator` takes any callable that
+evaluates a JavaScript expression in the page and returns what its promise
+resolves to. Helpers exist for three drivers:
+
+| Driver | Bridge |
+|---|---|
+| Ferrum | `ScriptEvaluator.ferrum(page)` |
+| Playwright (`playwright-ruby-client`) | `ScriptEvaluator.playwright(page)` |
+| Selenium WebDriver | `ScriptEvaluator.selenium(driver)` |
+| Anything else | `ScriptEvaluator.new(evaluate: ->(js) { ... })`, or `WebMcp.connect(evaluate: ...)` |
+
+A browser extension, a raw CDP session or a remote grid can write its own
+bridge instead. Any object with `#list_tools` and `#execute_tool(name, input)`
+works.
+
+### WebMCP surfaces
+
+The consumer script tries these in order:
+
+1. `document.modelContext`, or `navigator.modelContext`, with `getTools()` and
+   `executeTool()`. This is the current spec.
+2. `navigator.modelContextTesting`, with `listTools()` and
+   `executeTool(name, json)`. This is the testing API from early browser builds.
+3. `listTools()` and `callTool({ name, arguments })`, the shape that some
+   userland polyfills use.
+
+A page that registers tools but offers none of these to a consumer can still be
+read. Inject `WebMcp.polyfill_js` before navigation so the page registers into
+something the consumer can list.
+
+### Stores that don't run Portage
+
+`Transport` does not assume that the page was built with this gem:
+
+- **Tool names.** An action resolves to `tool_names[action]` first, then to
+  `"#{prefix}#{action}"`, then to the action itself. Map a store's own names:
+  `WebMcp.connect(bridge:, tool_names: { search_catalog: "findProducts" })`. A
+  miss reads the page again once (for tools registered late), then raises
+  `ToolNotFoundError`, which lists what the page does register.
+- **Argument shape.** The shape comes from each tool's own `inputSchema`. If
+  its properties nest under `catalog`, `cart` or `checkout`, or it takes `id`
+  and `meta`, it is a real-UCP-shaped tool. It gets the same body that
+  `Transports::Http` builds for native UCP (the code is shared through
+  `Transports::UcpWireShape`). Other tools get Session's flat arguments, as
+  over stdio. Force one shape with `wire: :ucp` or `wire: :flat`.
+- **Results.** An MCP-style `CallToolResult` is unwrapped the same way as over
+  stdio or HTTP, and `isError` raises `ServerError`. A JSON string (the spec's
+  `executeTool` resolves to one) is parsed. Anything else is returned as it is.
+- **Re-registration.** Some pages drop all their tools and register them again
+  while they re-render. A call to a tool that vanished that way waits up to
+  `reregister_wait:` (default 2 seconds) for it to come back, then retries.
+  The call never ran the first time, so the retry is safe. The wait blocks
+  the calling thread; see "Timeouts" below.
+
+### Timeouts
+
+Two limits bound an outbound call, and both block the thread that made it:
+
+- **The browser driver's own timeout** bounds each round trip to the page.
+  `ScriptEvaluator.ferrum(page, timeout: 30)` passes its `timeout:` (default
+  30 seconds) to `evaluate_async`. Playwright and Selenium use the page's or
+  driver's own script timeout, so set it there. A driver that times out
+  raises, and the error surfaces as `BridgeError`.
+- **`reregister_wait:`** (default 2 seconds, `WebMcp.connect(...,
+  reregister_wait:)`) bounds the wait for a tool the page dropped mid-call.
+  It's a plain `sleep`, polling every 0.25 seconds. One monotonic deadline
+  covers the whole call: it's set before the first attempt, a retry never
+  resets it, the retried calls count against it, and no sleep runs past it.
+  A miss costs at most `reregister_wait:` plus the one driver round trip in
+  flight when it expires. Pass `reregister_wait: 0` to fail on the first
+  miss, or make the call off a thread that can't afford to block.
+
+### Shopify storefronts
+
+Checked live on 2026-09-23: 6 of 8 Shopify storefronts tried (ColourPop,
+tentree, Kylie Cosmetics, Brooklinen, Allbirds, Billabong) register the same 11
+WebMCP tools of their own. Gymshark and Fashion Nova registered none. The
+tools take UCP-shaped arguments, so `wire: :auto` picks the UCP shape. Two
+names differ from Session's:
+
+```ruby
+session = Portage::Ucp::WebMcp.connect(bridge: bridge, tool_names: { create_cart: "add_to_cart" })
+session.search_catalog(query: "hoodie")          # page tool: search_catalog
+session.get_product(product_id: product["id"])   # page tool: get_product, variants included
+session.create_cart(line_items: [{ product_id: variant["id"], quantity: 1 }]) # adds to the browser's cart
+session.get_cart(cart_id: "current")             # the browser's cart; cart_id is ignored
+```
+
+Things to know about these tools:
+
+- The cart is the browser session's own cart, so `add_to_cart` returns no cart
+  id and adds to what is already there.
+- Search results carry no variants. Call `get_product` for variant ids.
+- Right after `add_to_cart`, the page's cart tools can fail for a second or two
+  with `Standard Actions are not available ... Try again`. Wait and call again.
+- `update_cart_lines` addresses existing cart lines by line id, not by variant.
+  `proceed_to_checkout` navigates the browser to Shopify checkout, where the
+  shopper pays. Neither maps onto a Session method.
+
+### Errors
+
+All errors are under `Portage::Ucp::Client::Error`, so existing `rescue` blocks
+still catch them.
+
+| Error | When |
+|---|---|
+| `WebMcp::BridgeError` | The page has no WebMCP surface, the driver failed, or the result couldn't be read. It quotes at most 300 characters of the driver's own error. |
+| `WebMcp::ToolNotFoundError` | No page tool answers the action. `#available` lists what the page registers. |
+| `Client::ServerError` | The tool ran and failed: `isError`, or the page's tool threw. |
+
+## Development
+
+```bash
+bundle exec rspec && bundle exec rubocop
+```
+
+The browser-side scripts are plain `.js` files under
+`lib/portage/ucp/webmcp/assets/`. Specs tagged `:node` run them unmodified in
+a node process that stands in for a browser tab
+(`spec/support/node_browser.{js,rb}`). The fetches of that tab are answered by
+the real `Rack::App`. This makes the round-trip specs go page, then endpoint,
+then `Mcp::Server`, then `ReferenceAdapter`, with nothing mocked. They also
+check that WebMCP returns the same documents as the in-process Loopback
+transport. These specs are skipped when `node` isn't installed.

data/lib/portage/ucp/webmcp/assets/consumer.js

@@ -0,0 +1,104 @@
+/*
+ * portage-ucp-webmcp consumer (outbound).
+ *
+ * A single function expression Bridges::ScriptEvaluator evaluates in the
+ * page (via whatever driver the caller has) as `(<this>)(op, name, input)`.
+ * Always resolves — never rejects — to a JSON string envelope
+ * `{ ok: true, value }` or `{ ok: false, code, error }`, so every driver sees
+ * one shape regardless of how it surfaces a rejected promise. `code` is
+ * "no_surface" (no WebMCP on the page), "not_registered" (no such tool) or
+ * "execute_failed" (the tool itself threw or rejected).
+ *
+ * Surfaces probed, in order:
+ *   1. `document.modelContext` / `navigator.modelContext` with `getTools()` +
+ *      `executeTool(tool, input)` — the current spec.
+ *   2. `navigator.modelContextTesting` with `listTools()` +
+ *      `executeTool(name, jsonString)` — the testing API early browser builds
+ *      shipped behind a flag.
+ *   3. A `modelContext` with `listTools()` + `callTool({ name, arguments })`
+ *      — the shape some userland polyfills expose.
+ */
+(function (op, name, input) {
+  "use strict";
+
+  var root = typeof window !== "undefined" ? window : globalThis;
+  var doc = root.document;
+  var nav = root.navigator || {};
+  var context = (doc && doc.modelContext) || nav.modelContext;
+  var testing = nav.modelContextTesting;
+
+  function failure(code, message) {
+    var error = new Error(message);
+    error.code = code;
+    return error;
+  }
+
+  function surface() {
+    if (context && typeof context.getTools === "function" && typeof context.executeTool === "function") {
+      return Promise.resolve(context.getTools()).then(function (tools) {
+        return { kind: "spec", tools: tools || [] };
+      });
+    }
+    if (testing && typeof testing.listTools === "function") {
+      return Promise.resolve(testing.listTools()).then(function (tools) {
+        return { kind: "testing", tools: tools || [] };
+      });
+    }
+    if (context && typeof context.listTools === "function" && typeof context.callTool === "function") {
+      return Promise.resolve(context.listTools()).then(function (listed) {
+        return { kind: "polyfill", tools: (listed && listed.tools) || listed || [] };
+      });
+    }
+    return Promise.reject(failure("no_surface",
+      "no WebMCP tool surface on this page (document.modelContext, navigator.modelContext, " +
+      "navigator.modelContextTesting)"));
+  }
+
+  function schema(value) {
+    if (typeof value !== "string") return value || {};
+    try { return JSON.parse(value); } catch (_e) { return {}; }
+  }
+
+  function plain(tool) {
+    return {
+      name: tool.name,
+      title: tool.title || null,
+      description: tool.description || "",
+      inputSchema: schema(tool.inputSchema),
+      annotations: tool.annotations || {},
+      origin: tool.origin || null
+    };
+  }
+
+  function execute(found) {
+    var tool = found.tools.filter(function (t) { return t.name === name; })[0];
+    if (!tool) throw failure("not_registered", "WebMCP tool not registered on this page: " + name);
+
+    var run;
+    try {
+      if (found.kind === "spec") run = context.executeTool(tool, input || {});
+      else if (found.kind === "testing") run = testing.executeTool(name, JSON.stringify(input || {}));
+      else run = context.callTool({ name: name, arguments: input || {} });
+    } catch (error) {
+      run = Promise.reject(error);
+    }
+    return Promise.resolve(run).then(null, function (error) {
+      throw failure("execute_failed", String((error && error.message) || error));
+    });
+  }
+
+  var work = surface().then(function (found) {
+    return op === "list" ? found.tools.map(plain) : execute(found);
+  });
+
+  return work.then(
+    function (value) { return JSON.stringify({ ok: true, value: value === undefined ? null : value }); },
+    function (error) {
+      return JSON.stringify({
+        ok: false,
+        code: (error && error.code) || "execute_failed",
+        error: String((error && error.message) || error)
+      });
+    }
+  );
+})

data/lib/portage/ucp/webmcp/assets/polyfill.js

@@ -0,0 +1,109 @@
+/*
+ * portage-ucp-webmcp polyfill.
+ *
+ * Installs a minimal, spec-shaped ModelContext (`registerTool` with an
+ * AbortSignal, `getTools`, `executeTool`, plus the older `unregisterTool`)
+ * on `document.modelContext` and `navigator.modelContext` — only when the
+ * browser has neither. Two uses:
+ *
+ *   - Agent side: inject it as an init script (Playwright `add_init_script`,
+ *     Ferrum `evaluate_on_new_document`, CDP
+ *     `Page.addScriptToEvaluateOnNewDocument`) so a page that registers
+ *     WebMCP tools still has them discoverable in a browser build without
+ *     native WebMCP.
+ *   - Merchant side: prepend it to the registrar (`include_polyfill: true`)
+ *     for agents that drive such a browser.
+ *
+ * It is not a security boundary and does nothing a page's own script
+ * couldn't; when a native implementation exists it is left untouched.
+ */
+(function () {
+  "use strict";
+
+  var root = typeof window !== "undefined" ? window : globalThis;
+  var doc = root.document;
+  var nav = root.navigator;
+  if ((doc && doc.modelContext) || (nav && nav.modelContext)) return;
+
+  var NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+  var tools = new Map();
+  var listeners = {};
+
+  function emit(type, detail) {
+    (listeners[type] || []).slice().forEach(function (listener) {
+      try { listener({ type: type, toolName: detail }); } catch (_e) { /* listener's own problem */ }
+    });
+  }
+
+  function origin() {
+    return (root.location && root.location.origin) || null;
+  }
+
+  function remove(name) {
+    if (tools.delete(name)) emit("toolchange", name);
+  }
+
+  var modelContext = {
+    registerTool: function (tool, options) {
+      if (!tool || !NAME.test(String(tool.name))) return Promise.reject(new TypeError("invalid tool name"));
+      if (!tool.description) return Promise.reject(new TypeError("tool description is required"));
+      if (typeof tool.execute !== "function") return Promise.reject(new TypeError("tool execute must be a function"));
+      if (tools.has(tool.name)) return Promise.reject(new Error("tool already registered: " + tool.name));
+
+      var signal = options && options.signal;
+      if (signal && signal.aborted) return Promise.resolve();
+      tools.set(tool.name, tool);
+      if (signal) signal.addEventListener("abort", function () { remove(tool.name); });
+      emit("toolchange", tool.name);
+      return Promise.resolve();
+    },
+
+    unregisterTool: function (name) { remove(name); },
+
+    getTools: function () {
+      return Promise.resolve(Array.from(tools.values()).map(function (tool) {
+        return {
+          name: tool.name,
+          title: tool.title,
+          description: tool.description,
+          inputSchema: tool.inputSchema || {},
+          annotations: tool.annotations || {},
+          origin: origin()
+        };
+      }));
+    },
+
+    // Resolves to a string, like the spec's `Promise<DOMString>`.
+    executeTool: function (registered, input, options) {
+      var name = typeof registered === "string" ? registered : registered && registered.name;
+      var tool = tools.get(name);
+      if (!tool) return Promise.reject(new Error("tool not registered: " + name));
+
+      var signal = (options && options.signal) ||
+        (typeof AbortController === "function" ? new AbortController().signal : undefined);
+      emit("toolactivated", name);
+      return Promise.resolve(tool.execute(input || {}, { signal: signal })).then(function (value) {
+        return typeof value === "string" ? value : JSON.stringify(value === undefined ? null : value);
+      });
+    },
+
+    addEventListener: function (type, listener) {
+      (listeners[type] = listeners[type] || []).push(listener);
+    },
+
+    removeEventListener: function (type, listener) {
+      listeners[type] = (listeners[type] || []).filter(function (l) { return l !== listener; });
+    }
+  };
+
+  function install(target) {
+    if (!target) return;
+    try {
+      Object.defineProperty(target, "modelContext", { value: modelContext, configurable: true });
+    } catch (_e) { /* frozen host object; the other target still gets it */ }
+  }
+
+  install(doc);
+  install(nav);
+  root.__portageWebMcpPolyfill = true;
+})();