@mcp-b/webmcp-local-relay 1.6.0 → 1.7.0

package/README.md

@@ -5,15 +5,22 @@
 Use WebMCP tools from any website, right inside your AI client.
 
 ```text
- Browser                        Your machine
-┌─────────────────┐            ┌─────────────────┐
-│  Website with    │            │  webmcp-local-  │
-│  WebMCP tools    │───────────│  relay           │
-│                  │  localhost │                  │
-└─────────────────┘            └────────┬────────┘
-                                        │ stdio
-                                        ▼
-                               Claude / Cursor / etc.
+ Browser Tab                          Local Machine
+┌──────────────────────┐             ┌──────────────────────┐
+│                      │  WebSocket  │                      │
+│   Website with       ├────────────▶  webmcp-local-relay   │
+│   WebMCP tools       │  localhost  │   (MCP server)       │
+│                      │             │                      │
+└──────────────────────┘             └──────────┬───────────┘
+                                                │
+                                          stdio │ JSON-RPC
+                                                │
+                                     ┌──────────▼───────────┐
+                                     │                      │
+                                     │   Claude / Cursor /  │
+                                     │   any MCP client     │
+                                     │                      │
+                                     └──────────────────────┘
 ```
 
 Open a website that has WebMCP tools. Run the relay. The tools show up in your MCP client.
@@ -100,13 +107,14 @@ npx @mcp-b/webmcp-local-relay
 
 ### Exposed Tools
 
-The relay exposes three static management tools that are always available:
+The relay exposes four static management tools that are always available:
 
 | Tool | Description |
 |------|-------------|
 | `webmcp_list_sources` | Lists connected browser tabs with metadata (tab ID, origin, URL, title, icon, tool count) |
 | `webmcp_list_tools` | Lists all relayed tools with source info |
 | `webmcp_call_tool` | Invokes a relayed tool by name with JSON arguments — useful for clients that don't support dynamic tool registration |
+| `webmcp_open_page` | Opens a URL in the user's default browser, or refreshes a connected source page by matching origin |
 
 **Dynamic tools** are registered directly on the MCP server using the original tool name, sanitized to `[a-zA-Z0-9_]`. When tools from different tabs share a name, a short tab-ID suffix is appended for disambiguation:
 
@@ -120,8 +128,9 @@ webmcp-local-relay [options]
 
   --host, -H               Bind host (default: 127.0.0.1)
   --port, -p               WebSocket port (default: 9333)
-  --widget-origin          Allowed browser origins, comma-separated (default: *)
+  --widget-origin          Allowed host page origin(s), comma-separated (default: *)
   --allowed-origin         Alias for --widget-origin
+  --ws-origin              Alias for --widget-origin
   --help, -h               Show help
 ```
 
@@ -134,39 +143,61 @@ npx @mcp-b/webmcp-local-relay
 # Custom port
 npx @mcp-b/webmcp-local-relay --port 9444
 
-# Restrict to trusted origins only
-npx @mcp-b/webmcp-local-relay --widget-origin https://your-app.example.com,https://another-app.example.com
+# Restrict to tools from trusted host pages
+npx @mcp-b/webmcp-local-relay --widget-origin https://myapp.com
 ```
 
 ### Security
 
 - Binds to `127.0.0.1` by default (loopback only, not accessible from your network).
 - The default `allowedOrigins` is `*`, which permits any browser page to connect and register tools. This is convenient for development but means any website open in your browser can expose tools to the relay.
-- **Recommended:** Use `--widget-origin` to restrict connections to only the origins you trust:
+- `--widget-origin` validates the **host page origin** reported in the browser `hello` message. This is the origin of the page that loaded `embed.js` (e.g., `https://myapp.com`), regardless of whether the widget iframe is served from CDN or self-hosted.
+- **Recommended:** Use `--widget-origin` to restrict which websites can register tools:
   ```bash
-  webmcp-local-relay --widget-origin https://your-app.example.com,https://another-app.example.com
+  # Only allow tools from myapp.com
+  webmcp-local-relay --widget-origin https://myapp.com
+
+  # Allow multiple origins
+  webmcp-local-relay --widget-origin https://app1.com,https://app2.com
   ```
-- Only the WebSocket `Origin` header is checked — any local process can connect regardless of origin restrictions.
+- Only the host page origin is checked — any local process can connect regardless of origin restrictions.
 
 ### Architecture
 
 ```text
-MCP Client (Claude, Cursor, etc.)
-    | stdio (JSON-RPC)
-    v
-LocalRelayMcpServer
-    | static + dynamic MCP tools
-    v
-RelayBridgeServer (ws://127.0.0.1:9333)
-    | ws messages
-    v
-Widget iframe (embed.js -> widget.html)
-    | postMessage bridge
-    v
-Host page WebMCP runtime (navigator.modelContext)
+┌──────────────────────────────────────┐
+│        MCP Client                    │
+│   (Claude, Cursor, Windsurf, etc.)   │
+└──────────────────┬───────────────────┘
+                   │ stdio / JSON-RPC
+┌──────────────────▼───────────────────┐
+│        LocalRelayMcpServer           │
+│   webmcp_list_sources                │
+│   webmcp_list_tools                  │
+│   webmcp_call_tool                   │
+│   + dynamic tools from browser       │
+└──────────────────┬───────────────────┘
+                   │ WebSocket (ws://127.0.0.1:9333)
+┌──────────────────▼───────────────────┐
+│        RelayBridgeServer             │
+│   Manages connections, routes calls  │
+└──────────────────┬───────────────────┘
+                   │ postMessage
+┌──────────────────▼───────────────────┐
+│        Widget iframe                 │
+│   embed.js injects widget.html       │
+└──────────────────┬───────────────────┘
+                   │ navigator.modelContext
+┌──────────────────▼───────────────────┐
+│        Host page                     │
+│   WebMCP runtime + registered tools  │
+└──────────────────────────────────────┘
 ```
 
 **How it connects:** The embed script injects a hidden iframe into the host page. The iframe opens a WebSocket to the relay on `localhost`. Tools are discovered via `navigator.modelContext` (or `navigator.modelContextTesting` as fallback) and forwarded to the relay, which registers them as standard MCP tools over stdio.
+If the relay is temporarily unavailable, the widget reconnects automatically using exponential backoff (1.5x multiplier) from `500ms` up to `3000ms`, stopping after 100 attempts.
+
+**Client mode:** When a second relay instance starts and the port is already in use (`EADDRINUSE`), it automatically falls back to **client mode**. In client mode the relay connects as a WebSocket client to the existing server relay and proxies tool operations through it. If the server relay later stops, the client attempts to promote itself back to server mode. This enables multiple MCP clients to share the same browser connections without manual configuration.
 
 ### Runtime Compatibility
 
@@ -199,9 +230,9 @@ For Chromium/Chrome Canary native preview testing:
 | Problem | Fix |
 |---------|-----|
 | `No sources connected` | Ensure the page loaded `embed.js` and the relay process is running |
-| `No tools listed` | Ensure page tools are registered on the WebMCP runtime before `embed.js` loads |
+| `No tools listed` | Ensure tools are registered on the page's WebMCP runtime. If tools register after load, confirm your runtime emits tool-change notifications (`toolschanged` or `registerToolsChangedCallback`) |
 | `Tool not found` | Tab reloaded or disconnected — call `webmcp_list_tools` again to refresh |
-| Connection blocked | Verify `--widget-origin` matches your page's origin, and relay port matches `data-relay-port` |
+| Connection blocked | Verify `--widget-origin` matches your host page's origin (e.g., `https://myapp.com`), and relay port matches `data-relay-port` |
 
 ---
 

package/dist/browser/embed.js

@@ -11,18 +11,16 @@
  * @typedef {{ requestId: string; type: string; toolName?: unknown; args?: unknown }} WidgetRequestMessage
  * @typedef {{ relayHost: string; relayPort: string; tabId: string; widgetUrl: string; widgetOrigin: string }} RelayConfig
  */
-(function initializeWebMcpRelayEmbed() {
+(() => {
   const RELAY_IFRAME_SELECTOR = '[data-webmcp-relay]';
   const TAB_ID_STORAGE_KEY = '__webmcp_relay_tab_id';
   const FALLBACK_WIDGET_URL =
     'https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay/dist/browser/widget.html';
 
   /** @type {Window | null} */
-  var widgetWindow = null;
+  let widgetWindow = null;
 
-  /**
-   * @returns {HTMLScriptElement | null}
-   */
+  /** @returns {HTMLScriptElement | null} */
   function getCurrentScriptElement() {
     return document.currentScript instanceof HTMLScriptElement ? document.currentScript : null;
   }
@@ -35,9 +33,7 @@
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
   }
 
-  /**
-   * @returns {string}
-   */
+  /** @returns {string} */
   function createTabId() {
     if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
       return crypto.randomUUID();
@@ -45,9 +41,7 @@
     return `${String(Date.now())}_${String(Math.random()).slice(2, 10)}`;
   }
 
-  /**
-   * @returns {string}
-   */
+  /** @returns {string} */
   function readOrCreateTabId() {
     try {
       const storedTabId = sessionStorage.getItem(TAB_ID_STORAGE_KEY);
@@ -81,10 +75,16 @@
         return new URL('widget.html', script.src).href;
       } catch (err) {
         console.warn(
-          '[webmcp-relay-embed] Failed to resolve widget URL from script src, falling back to CDN:',
+          '[webmcp-relay-embed] Failed to resolve widget URL from script src, falling back to CDN.',
+          'This may cause version mismatches with your local relay server.',
           err
         );
       }
+    } else {
+      console.warn(
+        '[webmcp-relay-embed] Script element has no src attribute, falling back to CDN widget URL.',
+        'This may cause version mismatches with your local relay server.'
+      );
     }
     return FALLBACK_WIDGET_URL;
   }
@@ -117,7 +117,10 @@
       return isJsonObject(parsed) ? parsed : { type: 'object', properties: {} };
     } catch (err) {
       console.warn(
-        '[webmcp-relay-embed] Failed to parse tool inputSchema, using permissive default:',
+        '[webmcp-relay-embed] Tool inputSchema is not valid JSON.',
+        'The tool will accept any arguments, which may cause invocation errors.',
+        'Raw schema:',
+        typeof rawSchema === 'string' ? rawSchema.slice(0, 200) : rawSchema,
         err
       );
       return { type: 'object', properties: {} };
@@ -129,12 +132,18 @@
    * @returns {JsonObject}
    */
   function toInvokeArgs(value) {
-    return isJsonObject(value) ? value : {};
+    if (isJsonObject(value)) return value;
+    if (value !== undefined && value !== null) {
+      console.warn(
+        '[webmcp-relay-embed] Tool invocation args must be an object, got',
+        typeof value,
+        '-- invocation will proceed with empty arguments'
+      );
+    }
+    return {};
   }
 
-  /**
-   * @returns {ToolBridge | null}
-   */
+  /** @returns {ToolBridge | null} */
   function getToolBridge() {
     const modelContext = navigator.modelContext;
     if (
@@ -180,7 +189,14 @@
               content: [{ type: 'text', text: 'Tool execution interrupted by navigation' }],
             };
           }
-          const parsed = JSON.parse(serialized);
+          let parsed;
+          try {
+            parsed = JSON.parse(serialized);
+          } catch {
+            throw new Error(
+              `Testing tool returned invalid JSON: ${String(serialized).slice(0, 200)}`
+            );
+          }
           if (!isJsonObject(parsed)) {
             throw new Error('Testing tool response was not an object');
           }
@@ -189,10 +205,14 @@
       };
     }
 
+    console.warn(
+      '[webmcp-relay-embed] No WebMCP runtime found (navigator.modelContext or',
+      'navigator.modelContextTesting). Tools will not be relayed.'
+    );
     return null;
   }
 
-  var pushScheduled = false;
+  let pushScheduled = false;
 
   /**
    * Coalesced handler for tool change events.
@@ -201,13 +221,13 @@
   function onToolsChanged() {
     if (pushScheduled || !widgetWindow) return;
     pushScheduled = true;
-    setTimeout(function pushToolsChangedToWidget() {
+    setTimeout(() => {
       pushScheduled = false;
       if (!widgetWindow) return;
-      var bridge = getToolBridge();
-      var toolsPromise = bridge ? Promise.resolve(bridge.listTools()) : Promise.resolve([]);
+      const bridge = getToolBridge();
+      const toolsPromise = bridge ? Promise.resolve(bridge.listTools()) : Promise.resolve([]);
       toolsPromise
-        .then(function (tools) {
+        .then((tools) => {
           if (!widgetWindow) return;
           widgetWindow.postMessage(
             {
@@ -217,7 +237,7 @@
             config.widgetOrigin
           );
         })
-        .catch(function (err) {
+        .catch((err) => {
           console.warn('[webmcp-relay-embed] Failed to push tool changes:', err);
         });
     }, 0);
@@ -229,23 +249,35 @@
    * falls back to registerToolsChangedCallback on modelContextTesting.
    */
   function subscribeToToolChanges() {
-    var mc = navigator.modelContext;
+    const mc = navigator.modelContext;
     if (mc && typeof mc.addEventListener === 'function') {
       try {
         mc.addEventListener('toolschanged', onToolsChanged);
         return;
-      } catch (_e) {
-        /* BrowserMcpServer doesn't extend EventTarget — fall through */
+      } catch (error) {
+        if (!(error instanceof TypeError)) {
+          console.warn(
+            '[webmcp-relay-embed] Unexpected error subscribing via addEventListener:',
+            error
+          );
+        }
       }
     }
-    var testing = navigator.modelContextTesting;
+    const testing = navigator.modelContextTesting;
     if (testing && typeof testing.registerToolsChangedCallback === 'function') {
       try {
         testing.registerToolsChangedCallback(onToolsChanged);
-      } catch (e) {
-        console.warn('[webmcp-relay-embed] Failed to subscribe to tool changes:', e);
+        return;
+      } catch (error) {
+        console.warn(
+          '[webmcp-relay-embed] Failed to subscribe via registerToolsChangedCallback:',
+          error
+        );
       }
     }
+    console.warn(
+      '[webmcp-relay-embed] Could not subscribe to tool changes. Dynamic tool updates will not be relayed.'
+    );
   }
 
   /**
@@ -258,7 +290,7 @@
       return;
     }
 
-    const postMessage = source.postMessage;
+    const { postMessage } = source;
     if (typeof postMessage !== 'function') {
       return;
     }
@@ -309,6 +341,7 @@
           type: 'webmcp.tools.list.response',
           requestId: request.requestId,
           tools: [],
+          error: `Failed to list tools: ${error instanceof Error ? error.message : String(error)}`,
         });
       });
   }
@@ -345,9 +378,7 @@
       });
   }
 
-  /**
-   * @param {RelayConfig} config
-   */
+  /** @param {RelayConfig} config */
   function injectRelayWidget(config) {
     if (document.querySelector(RELAY_IFRAME_SELECTOR)) {
       return;
@@ -356,7 +387,10 @@
     const searchParams = new URLSearchParams();
     searchParams.set('tabId', config.tabId);
     searchParams.set('hostOrigin', window.location.origin);
-    searchParams.set('hostUrl', window.location.href);
+    const cleanUrl = new URL(window.location.href);
+    cleanUrl.search = '';
+    cleanUrl.hash = '';
+    searchParams.set('hostUrl', cleanUrl.href);
     searchParams.set('hostTitle', document.title || '');
     searchParams.set('relayHost', config.relayHost);
     searchParams.set('relayPort', config.relayPort);
@@ -367,21 +401,44 @@
     iframe.setAttribute('aria-hidden', 'true');
     iframe.setAttribute('data-webmcp-relay', '1');
     document.body.appendChild(iframe);
+    widgetWindow = iframe.contentWindow;
     iframe.addEventListener('load', () => {
       widgetWindow = iframe.contentWindow;
     });
+    iframe.addEventListener('error', () => {
+      console.error(
+        '[webmcp-relay-embed] Failed to load relay widget iframe from:',
+        iframe.src,
+        '-- WebMCP tools will NOT be relayed. Check network connectivity and widget URL.'
+      );
+    });
   }
 
   if (document.querySelector(RELAY_IFRAME_SELECTOR)) {
     return;
   }
 
-  const config = buildRelayConfig(getCurrentScriptElement());
+  let config;
+  try {
+    config = buildRelayConfig(getCurrentScriptElement());
+  } catch (err) {
+    console.error('[webmcp-relay-embed] Failed to initialize relay configuration:', err);
+    return;
+  }
 
   window.addEventListener('message', (event) => {
     if (event.origin !== config.widgetOrigin) {
       return;
     }
+    if (!widgetWindow || event.source !== widgetWindow) {
+      return;
+    }
+
+    const data = event.data;
+    if (isJsonObject(data) && data.type === 'webmcp.reload') {
+      window.location.reload();
+      return;
+    }
 
     const request = parseWidgetRequest(event.data);
     if (!request) {