@mcp-b/chrome-devtools-mcp 2.0.13 → 2.2.0

package/build/src/transports/WebMCPClientTransport.js

@@ -1,449 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { WEB_MCP_BRIDGE_SCRIPT, CHECK_WEBMCP_AVAILABLE_SCRIPT } from './WebMCPBridgeScript.js';
-import { CDP_BRIDGE_WINDOW_PROPERTY, CDP_BRIDGE_BINDING } from './bridgeConstants.js';
-/**
- * MCP Client Transport that connects to a WebMCP server running in a browser tab.
- *
- * This transport uses Chrome DevTools Protocol (CDP) to inject a bridge script
- * into the page, which then ferries MCP messages between this transport and
- * the page's TabServerTransport via window.postMessage.
- *
- * Architecture:
- * ```
- * WebMCPClientTransport (Node.js)
- *     │
- *     │ CDP (Runtime.evaluate / Runtime.bindingCalled)
- *     ▼
- * Bridge Script (injected into page)
- *     │
- *     │ window.postMessage
- *     ▼
- * TabServerTransport (@mcp-b/global)
- *     │
- *     ▼
- * MCP Server (tools, resources, prompts)
- * ```
- *
- * @example
- * ```typescript
- * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
- * import { WebMCPClientTransport } from './transports/WebMCPClientTransport.js';
- *
- * const transport = new WebMCPClientTransport({ page });
- * const client = new Client({ name: 'my-client', version: '1.0.0' });
- *
- * await client.connect(transport);
- * const { tools } = await client.listTools();
- * ```
- */
-export class WebMCPClientTransport {
-    _page;
-    _cdpSession = null;
-    _started = false;
-    /** Guards against concurrent start() calls. */
-    _starting = false;
-    _closed = false;
-    _readyTimeout;
-    _requireWebMCP;
-    _serverReady = false;
-    _serverReadyPromise;
-    _serverReadyResolve;
-    _serverReadyReject;
-    /** Tracks if promise was rejected to prevent double rejection. */
-    _serverReadyRejected = false;
-    /** Bound handler for frame navigation events (stored for cleanup). */
-    _frameNavigatedHandler = null;
-    /** Bound handler for CDP binding calls (stored for cleanup). */
-    _bindingCalledHandler = null;
-    /** Guards against concurrent navigation handling. */
-    _navigationInProgress = false;
-    /** Callback invoked when transport is closed. */
-    onclose;
-    /** Callback invoked when an error occurs. */
-    onerror;
-    /** Callback invoked when a JSON-RPC message is received. */
-    onmessage;
-    /**
-     * Check if the transport has been closed.
-     * This is useful for clients to check if they need to reconnect
-     * after a page navigation or reload.
-     */
-    isClosed() {
-        return this._closed;
-    }
-    /**
-     * Get the page this transport is connected to.
-     * This allows callers to verify the transport is connected to the expected page,
-     * which is important when browsers are closed and reopened.
-     */
-    getPage() {
-        return this._page;
-    }
-    constructor(options) {
-        this._page = options.page;
-        this._readyTimeout = options.readyTimeout ?? 10000;
-        this._requireWebMCP = options.requireWebMCP ?? true;
-        // Set up server ready promise with attached rejection handler
-        // to prevent unhandled rejection if close() is called before start()
-        this._serverReadyPromise = new Promise((resolve, reject) => {
-            this._serverReadyResolve = resolve;
-            this._serverReadyReject = (err) => {
-                this._serverReadyRejected = true;
-                reject(err);
-            };
-        });
-        // Attach a no-op catch to prevent unhandled rejection warnings
-        // The actual error will be propagated when the promise is awaited
-        this._serverReadyPromise.catch(() => {
-            // Intentionally empty - errors are handled where the promise is awaited
-        });
-    }
-    /**
-     * Check if WebMCP is available on the page.
-     *
-     * Returns `available: false` with an `error` field if the check failed due to
-     * page-level issues (closed, navigating, etc.) vs WebMCP simply not being present.
-     */
-    async checkWebMCPAvailable() {
-        try {
-            const result = await this._page.evaluate(CHECK_WEBMCP_AVAILABLE_SCRIPT);
-            return result;
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            // Distinguish between "page is broken" vs "WebMCP not present"
-            const isPageError = message.includes('Execution context was destroyed') ||
-                message.includes('Target closed') ||
-                message.includes('Session closed') ||
-                message.includes('Protocol error');
-            if (isPageError) {
-                return { available: false, error: `Page error: ${message}` };
-            }
-            // Other errors (e.g., script threw) mean WebMCP is not available
-            return { available: false };
-        }
-    }
-    /**
-     * Start the transport and establish connection to the WebMCP server.
-     *
-     * This method:
-     * 1. Creates a CDP session
-     * 2. Sets up the binding for receiving messages from the page
-     * 3. Injects the bridge script
-     * 4. Initiates the server-ready handshake
-     * 5. Waits for the server to be ready (with timeout)
-     */
-    async start() {
-        if (this._started) {
-            throw new Error('WebMCPClientTransport already started');
-        }
-        if (this._starting) {
-            throw new Error('WebMCPClientTransport start already in progress');
-        }
-        if (this._closed) {
-            throw new Error('WebMCPClientTransport has been closed');
-        }
-        this._starting = true;
-        try {
-            // Check if WebMCP is available
-            if (this._requireWebMCP) {
-                const check = await this.checkWebMCPAvailable();
-                if (!check.available) {
-                    const errorDetail = check.error ? ` (${check.error})` : '';
-                    throw new Error(`WebMCP not detected on this page${errorDetail}. ` +
-                        'Ensure @mcp-b/global is loaded and initialized.');
-                }
-            }
-            // Create CDP session for this page
-            this._cdpSession = await this._page.createCDPSession();
-            // Enable Runtime domain for bindings and evaluation
-            await this._cdpSession.send('Runtime.enable');
-            // Set up binding for receiving messages from the bridge
-            // When the bridge calls window.__mcpBridgeToClient(msg), we receive it here
-            await this._cdpSession.send('Runtime.addBinding', {
-                name: CDP_BRIDGE_BINDING,
-            });
-            // Create bound handlers so we can remove them later
-            this._bindingCalledHandler = (event) => {
-                if (event.name !== CDP_BRIDGE_BINDING)
-                    return;
-                // Guard against processing messages after close
-                if (this._closed)
-                    return;
-                let payload;
-                try {
-                    payload = JSON.parse(event.payload);
-                }
-                catch (err) {
-                    this.onerror?.(new Error(`Failed to parse JSON message from bridge: ${err instanceof Error ? err.message : String(err)}. ` +
-                        `Raw payload: ${event.payload.substring(0, 200)}`));
-                    return;
-                }
-                try {
-                    this._handlePayload(payload);
-                }
-                catch (err) {
-                    this.onerror?.(new Error(`Failed to handle message from bridge: ${err instanceof Error ? err.message : String(err)}`));
-                }
-            };
-            this._frameNavigatedHandler = (frame) => {
-                if (frame === this._page.mainFrame()) {
-                    // Main frame navigated - check if bridge survived (SPA navigation)
-                    this._handleNavigation().catch((err) => {
-                        // Log navigation handling errors for debugging
-                        const message = err instanceof Error ? err.message : String(err);
-                        const logFn = console.debug || console.log;
-                        logFn('[WebMCPClientTransport] Navigation handling error:', message);
-                    });
-                }
-            };
-            // Listen for binding calls (messages from bridge → this transport)
-            this._cdpSession.on('Runtime.bindingCalled', this._bindingCalledHandler);
-            // Listen for page navigation to detect when bridge is lost
-            this._page.on('framenavigated', this._frameNavigatedHandler);
-            // Inject the bridge script
-            const result = await this._page.evaluate(WEB_MCP_BRIDGE_SCRIPT);
-            if (!result.success && !result.alreadyInjected) {
-                throw new Error('Failed to inject WebMCP bridge script');
-            }
-            this._started = true;
-            // Initiate server-ready handshake
-            await this._page.evaluate((bridgeProp) => {
-                window[bridgeProp]?.checkReady();
-            }, CDP_BRIDGE_WINDOW_PROPERTY);
-            // Wait for server ready with timeout
-            const timeoutPromise = new Promise((_, reject) => {
-                const timer = setTimeout(() => {
-                    reject(new Error(`WebMCP server did not respond within ${this._readyTimeout}ms. ` +
-                        'Ensure TabServerTransport is running on the page.'));
-                }, this._readyTimeout);
-                // Clear timeout if promise resolves
-                this._serverReadyPromise.then(() => clearTimeout(timer)).catch(() => clearTimeout(timer));
-            });
-            try {
-                await Promise.race([this._serverReadyPromise, timeoutPromise]);
-            }
-            catch (err) {
-                await this.close();
-                throw err;
-            }
-        }
-        catch (err) {
-            // Clean up on any error during start
-            this._starting = false;
-            if (!this._closed) {
-                await this._cleanup();
-            }
-            throw err;
-        }
-        finally {
-            this._starting = false;
-        }
-    }
-    /**
-     * Handle a payload received from the bridge
-     */
-    _handlePayload(payload) {
-        // Guard against processing messages after close
-        if (this._closed)
-            return;
-        // Handle special string payloads (handshake signals)
-        if (typeof payload === 'string') {
-            if (payload === 'mcp-server-ready') {
-                if (!this._serverReady) {
-                    this._serverReady = true;
-                    this._serverReadyResolve();
-                }
-                return;
-            }
-            if (payload === 'mcp-server-stopped') {
-                this._handleServerStopped();
-                return;
-            }
-            // Unknown string payload - might be an error
-            this.onerror?.(new Error(`Unexpected string payload: ${payload}`));
-            return;
-        }
-        // Handle JSON-RPC messages
-        if (typeof payload === 'object' && payload !== null) {
-            // Resolve server ready on first real message too
-            if (!this._serverReady) {
-                this._serverReady = true;
-                this._serverReadyResolve();
-            }
-            this.onmessage?.(payload);
-        }
-    }
-    /**
-     * Handle page navigation - check if OUR BRIDGE survived (SPA navigation)
-     *
-     * The `framenavigated` event fires for BOTH:
-     * 1. Full page navigations (where the bridge IS destroyed)
-     * 2. Client-side SPA navigations via History API (where the bridge survives)
-     *
-     * For SPA navigations (React Router, TanStack Router, Next.js, etc.),
-     * the page doesn't actually reload - only the URL changes.
-     * The injected bridge script remains intact and functional.
-     *
-     * IMPORTANT: We check for OUR bridge (window.__mcpCdpBridge), not just the
-     * page's WebMCP availability. A full navigation to another WebMCP page would
-     * have a new TabServerTransport but our bridge would be destroyed.
-     */
-    async _handleNavigation() {
-        // Guard against concurrent navigation handling
-        if (this._closed || this._navigationInProgress)
-            return;
-        this._navigationInProgress = true;
-        try {
-            // Give the page a moment to settle after navigation
-            // This helps with rapid SPA navigations
-            await new Promise(resolve => setTimeout(resolve, 50));
-            // Re-check closed state after the wait (could have been closed during delay)
-            if (this._closed)
-                return;
-            // Check if OUR BRIDGE survived the navigation (not just the page's WebMCP)
-            // This distinguishes SPA navigation from full navigation to another WebMCP page
-            try {
-                const bridgeAlive = await this._page.evaluate((bridgeProp) => {
-                    return !!window[bridgeProp];
-                }, CDP_BRIDGE_WINDOW_PROPERTY);
-                if (bridgeAlive) {
-                    // Our bridge survived - this was an SPA navigation, don't close
-                    const logFn = console.debug || console.log;
-                    logFn('[WebMCPClientTransport] Bridge survived navigation (SPA), keeping connection open');
-                    return;
-                }
-            }
-            catch {
-                // Evaluation failed - page context is gone, proceed with close
-            }
-            // Re-check closed state (could have been closed during bridge check)
-            if (this._closed)
-                return;
-            // Bridge is lost - full navigation occurred
-            this._serverReady = false;
-            this._closed = true;
-            this._started = false;
-            // Reject any pending server ready promise (safe - has attached catch handler)
-            if (!this._serverReadyRejected) {
-                this._serverReadyReject(new Error('Page navigated, connection lost'));
-            }
-            // Full teardown - detach CDP session and remove listeners
-            this._cleanup().catch((err) => {
-                // Cleanup errors during navigation are expected and non-critical
-                const message = err instanceof Error ? err.message : String(err);
-                const logFn = console.debug || console.log;
-                logFn('[WebMCPClientTransport] Cleanup error during navigation (non-critical):', message);
-            });
-            // Signal clean disconnection (not an error)
-            this.onclose?.();
-        }
-        finally {
-            this._navigationInProgress = false;
-        }
-    }
-    /**
-     * Handle server stopped signal
-     */
-    _handleServerStopped() {
-        if (this._closed)
-            return;
-        this._serverReady = false;
-        this.onerror?.(new Error('WebMCP server stopped'));
-    }
-    /**
-     * Send a JSON-RPC message to the WebMCP server
-     */
-    async send(message) {
-        if (!this._started) {
-            throw new Error('WebMCPClientTransport not started');
-        }
-        if (this._closed) {
-            throw new Error('WebMCPClientTransport has been closed');
-        }
-        // Wait for server to be ready before sending
-        await this._serverReadyPromise;
-        // Send via CDP → bridge → postMessage → TabServer
-        try {
-            // JSON.stringify inside try block to catch non-serializable messages
-            const messageJson = JSON.stringify(message);
-            await this._page.evaluate((msg, bridgeProp) => {
-                const bridge = window[bridgeProp];
-                if (!bridge) {
-                    throw new Error('WebMCP bridge not found');
-                }
-                const sent = bridge.toServer(msg);
-                if (!sent) {
-                    throw new Error('Bridge failed to send message');
-                }
-            }, messageJson, CDP_BRIDGE_WINDOW_PROPERTY);
-        }
-        catch (err) {
-            const error = new Error(`Failed to send message: ${err}`);
-            this.onerror?.(error);
-            throw error;
-        }
-    }
-    /**
-     * Internal cleanup method - removes listeners and detaches CDP session.
-     * Does not set _closed flag or call onclose (caller handles those).
-     */
-    async _cleanup() {
-        // Remove page event listener
-        if (this._frameNavigatedHandler) {
-            this._page.off('framenavigated', this._frameNavigatedHandler);
-            this._frameNavigatedHandler = null;
-        }
-        // Remove CDP event listener
-        if (this._cdpSession && this._bindingCalledHandler) {
-            this._cdpSession.off('Runtime.bindingCalled', this._bindingCalledHandler);
-            this._bindingCalledHandler = null;
-        }
-        // Dispose the bridge script if possible
-        try {
-            await this._page.evaluate((bridgeProp) => {
-                window[bridgeProp]?.dispose();
-            }, CDP_BRIDGE_WINDOW_PROPERTY);
-        }
-        catch (err) {
-            // Cleanup errors during navigation are expected and non-critical
-            const message = err instanceof Error ? err.message : String(err);
-            const logFn = console.debug || console.log;
-            logFn('[WebMCPClientTransport] Bridge dispose skipped:', message);
-        }
-        // Detach CDP session
-        if (this._cdpSession) {
-            try {
-                await this._cdpSession.detach();
-            }
-            catch (err) {
-                // Expected when session already detached - log for debugging only
-                const message = err instanceof Error ? err.message : String(err);
-                const logFn = console.debug || console.log;
-                logFn('[WebMCPClientTransport] CDP detach skipped:', message);
-            }
-            this._cdpSession = null;
-        }
-    }
-    /**
-     * Close the transport and clean up resources
-     */
-    async close() {
-        if (this._closed)
-            return;
-        this._closed = true;
-        this._started = false;
-        this._serverReady = false;
-        // Full cleanup
-        await this._cleanup();
-        // Reject any pending server ready promise (safe - has attached catch handler)
-        if (!this._serverReadyRejected) {
-            this._serverReadyReject(new Error('Transport closed'));
-        }
-        this.onclose?.();
-    }
-}

package/build/src/transports/bridgeConstants.js

@@ -1,22 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * Constants for WebMCP CDP bridge communication.
- * These names are used to coordinate between the bridge script injected into the page
- * and the WebMCPClientTransport running in Node.js via CDP.
- */
-/**
- * Window property name for the CDP bridge object.
- * Renamed from `__mcpBridge` to `__mcpCdpBridge` to avoid collision with
- * the polyfill's internal `__mcpBridge` property.
- */
-export const CDP_BRIDGE_WINDOW_PROPERTY = '__mcpCdpBridge';
-/**
- * CDP binding name for receiving messages from the bridge.
- * This is the function name registered via Runtime.addBinding that the
- * bridge calls to send messages back to the CDP transport.
- */
-export const CDP_BRIDGE_BINDING = '__mcpBridgeToClient';

package/build/src/transports/index.js

@@ -1,7 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-export { WebMCPClientTransport, } from './WebMCPClientTransport.js';
-export { WEB_MCP_BRIDGE_SCRIPT, CHECK_WEBMCP_AVAILABLE_SCRIPT, } from './WebMCPBridgeScript.js';

package/build/vendor/chrome-devtools-frontend/LICENSE

@@ -1,27 +0,0 @@
-// Copyright 2014 The Chromium Authors
-//
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions are
-// met:
-//
-//    * Redistributions of source code must retain the above copyright
-// notice, this list of conditions and the following disclaimer.
-//    * Redistributions in binary form must reproduce the above
-// copyright notice, this list of conditions and the following disclaimer
-// in the documentation and/or other materials provided with the
-// distribution.
-//    * Neither the name of Google Inc. nor the names of its
-// contributors may be used to endorse or promote products derived from
-// this software without specific prior written permission.
-//
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/build/vendor/chrome-devtools-frontend/front_end/core/common/App.js

@@ -1,4 +0,0 @@
-// Copyright 2019 The Chromium Authors
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-export {};

package/build/vendor/chrome-devtools-frontend/front_end/core/common/AppProvider.js

@@ -1,17 +0,0 @@
-// Copyright 2019 The Chromium Authors
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-import * as Root from '../root/root.js';
-const registeredAppProvider = [];
-export function registerAppProvider(registration) {
-    registeredAppProvider.push(registration);
-}
-export function getRegisteredAppProviders() {
-    return registeredAppProvider
-        .filter(provider => Root.Runtime.Runtime.isDescriptorEnabled({ experiment: undefined, condition: provider.condition }))
-        .sort((firstProvider, secondProvider) => {
-        const order1 = firstProvider.order || 0;
-        const order2 = secondProvider.order || 0;
-        return order1 - order2;
-    });
-}

package/build/vendor/chrome-devtools-frontend/front_end/core/common/Base64.js

@@ -1,61 +0,0 @@
-// Copyright 2020 The Chromium Authors
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-export const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-export const BASE64_CODES = new Uint8Array(123);
-for (let index = 0; index < BASE64_CHARS.length; ++index) {
-    BASE64_CODES[BASE64_CHARS.charCodeAt(index)] = index;
-}
-/**
- * Decodes Base64-encoded data from a string without performing any kind of checking.
- */
-export function decode(input) {
-    let bytesLength = ((input.length * 3) / 4) >>> 0;
-    if (input.charCodeAt(input.length - 2) === 0x3d /* '=' */) {
-        bytesLength -= 2;
-    }
-    else if (input.charCodeAt(input.length - 1) === 0x3d /* '=' */) {
-        bytesLength -= 1;
-    }
-    const bytes = new Uint8Array(bytesLength);
-    for (let index = 0, offset = 0; index < input.length; index += 4) {
-        const a = BASE64_CODES[input.charCodeAt(index + 0)];
-        const b = BASE64_CODES[input.charCodeAt(index + 1)];
-        const c = BASE64_CODES[input.charCodeAt(index + 2)];
-        const d = BASE64_CODES[input.charCodeAt(index + 3)];
-        bytes[offset++] = (a << 2) | (b >> 4);
-        bytes[offset++] = ((b & 0x0f) << 4) | (c >> 2);
-        bytes[offset++] = ((c & 0x03) << 6) | (d & 0x3f);
-    }
-    return bytes;
-}
-/**
- * Note: if input can be very large (larger than the max string size), callers should
- * expect this to throw an error.
- */
-export function encode(input) {
-    return new Promise((resolve, reject) => {
-        const reader = new FileReader();
-        reader.onerror = () => reject(new Error('failed to convert to base64: internal error'));
-        reader.onload = () => {
-            // The input was too large to encode as a string. The caller should anticipate
-            // this and use a workaround. See TimelinePanel.ts innerSaveToFile for an example.
-            // For more information, see crbug.com/436482118.
-            if (reader.result === '') {
-                reject(new Error('failed to convert to base64: input too large to encode as base64 string'));
-                return;
-            }
-            // This string can be very large, so take care to not double memory. `split`
-            // was used here before, which always results in new strings in V8. By using
-            // slice instead, we leverage the sliced string optimization in V8 and avoid
-            // doubling the memory requirement (even if temporarily: that is a potential
-            // source of OOM crashes given large enough input, such as is common with
-            // Performance traces).
-            const blobAsUrl = reader.result;
-            const index = blobAsUrl.indexOf(',');
-            const base64 = blobAsUrl.slice(index + 1);
-            resolve(base64);
-        };
-        reader.readAsDataURL(new Blob([input]));
-    });
-}

package/build/vendor/chrome-devtools-frontend/front_end/core/common/CharacterIdMap.js

@@ -1,27 +0,0 @@
-// Copyright 2016 The Chromium Authors
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-export class CharacterIdMap {
-    #elementToCharacter = new Map();
-    #characterToElement = new Map();
-    #charCode = 33;
-    toChar(object) {
-        let character = this.#elementToCharacter.get(object);
-        if (!character) {
-            if (this.#charCode >= 0xFFFF) {
-                throw new Error('CharacterIdMap ran out of capacity!');
-            }
-            character = String.fromCharCode(this.#charCode++);
-            this.#elementToCharacter.set(object, character);
-            this.#characterToElement.set(character, object);
-        }
-        return character;
-    }
-    fromChar(character) {
-        const object = this.#characterToElement.get(character);
-        if (object === undefined) {
-            return null;
-        }
-        return object;
-    }
-}