@mcp-b/chrome-devtools-mcp 0.12.0-beta.0

package/build/src/transports/WebMCPClientTransport.js

@@ -0,0 +1,276 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { WEB_MCP_BRIDGE_SCRIPT, CHECK_WEBMCP_AVAILABLE_SCRIPT } from './WebMCPBridgeScript.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;
+    _closed = false;
+    _readyTimeout;
+    _requireWebMCP;
+    _serverReady = false;
+    _serverReadyPromise;
+    _serverReadyResolve;
+    _serverReadyReject;
+    // Transport callbacks
+    onclose;
+    onerror;
+    onmessage;
+    constructor(options) {
+        this._page = options.page;
+        this._readyTimeout = options.readyTimeout ?? 10000;
+        this._requireWebMCP = options.requireWebMCP ?? true;
+        // Set up server ready promise
+        this._serverReadyPromise = new Promise((resolve, reject) => {
+            this._serverReadyResolve = resolve;
+            this._serverReadyReject = reject;
+        });
+    }
+    /**
+     * Check if WebMCP is available on the page
+     */
+    async checkWebMCPAvailable() {
+        try {
+            const result = await this._page.evaluate(CHECK_WEBMCP_AVAILABLE_SCRIPT);
+            return result;
+        }
+        catch {
+            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._closed) {
+            throw new Error('WebMCPClientTransport has been closed');
+        }
+        // Check if WebMCP is available
+        if (this._requireWebMCP) {
+            const check = await this.checkWebMCPAvailable();
+            if (!check.available) {
+                throw new Error('WebMCP not detected on this page. ' +
+                    '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: '__mcpBridgeToClient',
+        });
+        // Listen for binding calls (messages from bridge → this transport)
+        this._cdpSession.on('Runtime.bindingCalled', event => {
+            if (event.name !== '__mcpBridgeToClient')
+                return;
+            try {
+                const payload = JSON.parse(event.payload);
+                this._handlePayload(payload);
+            }
+            catch (err) {
+                this.onerror?.(new Error(`Failed to parse message from bridge: ${err}`));
+            }
+        });
+        // Listen for page navigation to detect when bridge is lost
+        this._page.on('framenavigated', frame => {
+            if (frame === this._page.mainFrame()) {
+                // Main frame navigated, bridge is gone
+                this._handleNavigation();
+            }
+        });
+        // 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(() => {
+            window.__mcpBridge?.checkReady();
+        });
+        // 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;
+        }
+    }
+    /**
+     * Handle a payload received from the bridge
+     */
+    _handlePayload(payload) {
+        // 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 - bridge is lost
+     */
+    _handleNavigation() {
+        if (this._closed)
+            return;
+        this._serverReady = false;
+        this._serverReadyReject(new Error('Page navigated, connection lost'));
+        // Reset the promise for potential reconnection
+        this._serverReadyPromise = new Promise((resolve, reject) => {
+            this._serverReadyResolve = resolve;
+            this._serverReadyReject = reject;
+        });
+        this.onerror?.(new Error('Page navigated, WebMCP connection lost'));
+    }
+    /**
+     * Handle server stopped signal
+     */
+    _handleServerStopped() {
+        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
+        const messageJson = JSON.stringify(message);
+        try {
+            await this._page.evaluate((msg) => {
+                const bridge = window.__mcpBridge;
+                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);
+        }
+        catch (err) {
+            const error = new Error(`Failed to send message: ${err}`);
+            this.onerror?.(error);
+            throw error;
+        }
+    }
+    /**
+     * Close the transport and clean up resources
+     */
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this._started = false;
+        this._serverReady = false;
+        // Dispose the bridge script if possible
+        try {
+            await this._page.evaluate(() => {
+                window.__mcpBridge?.dispose();
+            });
+        }
+        catch {
+            // Ignore errors during cleanup
+        }
+        // Detach CDP session
+        if (this._cdpSession) {
+            try {
+                await this._cdpSession.detach();
+            }
+            catch {
+                // Ignore detach errors
+            }
+            this._cdpSession = null;
+        }
+        // Reject any pending server ready promise
+        this._serverReadyReject(new Error('Transport closed'));
+        this.onclose?.();
+    }
+}

package/build/src/transports/index.js

@@ -0,0 +1,7 @@
+/**
+ * @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/src/utils/keyboard.js

@@ -0,0 +1,296 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// See the KeyInput type for the list of supported keys.
+const validKeys = new Set([
+    '0',
+    '1',
+    '2',
+    '3',
+    '4',
+    '5',
+    '6',
+    '7',
+    '8',
+    '9',
+    'Power',
+    'Eject',
+    'Abort',
+    'Help',
+    'Backspace',
+    'Tab',
+    'Numpad5',
+    'NumpadEnter',
+    'Enter',
+    '\r',
+    '\n',
+    'ShiftLeft',
+    'ShiftRight',
+    'ControlLeft',
+    'ControlRight',
+    'AltLeft',
+    'AltRight',
+    'Pause',
+    'CapsLock',
+    'Escape',
+    'Convert',
+    'NonConvert',
+    'Space',
+    'Numpad9',
+    'PageUp',
+    'Numpad3',
+    'PageDown',
+    'End',
+    'Numpad1',
+    'Home',
+    'Numpad7',
+    'ArrowLeft',
+    'Numpad4',
+    'Numpad8',
+    'ArrowUp',
+    'ArrowRight',
+    'Numpad6',
+    'Numpad2',
+    'ArrowDown',
+    'Select',
+    'Open',
+    'PrintScreen',
+    'Insert',
+    'Numpad0',
+    'Delete',
+    'NumpadDecimal',
+    'Digit0',
+    'Digit1',
+    'Digit2',
+    'Digit3',
+    'Digit4',
+    'Digit5',
+    'Digit6',
+    'Digit7',
+    'Digit8',
+    'Digit9',
+    'KeyA',
+    'KeyB',
+    'KeyC',
+    'KeyD',
+    'KeyE',
+    'KeyF',
+    'KeyG',
+    'KeyH',
+    'KeyI',
+    'KeyJ',
+    'KeyK',
+    'KeyL',
+    'KeyM',
+    'KeyN',
+    'KeyO',
+    'KeyP',
+    'KeyQ',
+    'KeyR',
+    'KeyS',
+    'KeyT',
+    'KeyU',
+    'KeyV',
+    'KeyW',
+    'KeyX',
+    'KeyY',
+    'KeyZ',
+    'MetaLeft',
+    'MetaRight',
+    'ContextMenu',
+    'NumpadMultiply',
+    'NumpadAdd',
+    'NumpadSubtract',
+    'NumpadDivide',
+    'F1',
+    'F2',
+    'F3',
+    'F4',
+    'F5',
+    'F6',
+    'F7',
+    'F8',
+    'F9',
+    'F10',
+    'F11',
+    'F12',
+    'F13',
+    'F14',
+    'F15',
+    'F16',
+    'F17',
+    'F18',
+    'F19',
+    'F20',
+    'F21',
+    'F22',
+    'F23',
+    'F24',
+    'NumLock',
+    'ScrollLock',
+    'AudioVolumeMute',
+    'AudioVolumeDown',
+    'AudioVolumeUp',
+    'MediaTrackNext',
+    'MediaTrackPrevious',
+    'MediaStop',
+    'MediaPlayPause',
+    'Semicolon',
+    'Equal',
+    'NumpadEqual',
+    'Comma',
+    'Minus',
+    'Period',
+    'Slash',
+    'Backquote',
+    'BracketLeft',
+    'Backslash',
+    'BracketRight',
+    'Quote',
+    'AltGraph',
+    'Props',
+    'Cancel',
+    'Clear',
+    'Shift',
+    'Control',
+    'Alt',
+    'Accept',
+    'ModeChange',
+    ' ',
+    'Print',
+    'Execute',
+    '\u0000',
+    'a',
+    'b',
+    'c',
+    'd',
+    'e',
+    'f',
+    'g',
+    'h',
+    'i',
+    'j',
+    'k',
+    'l',
+    'm',
+    'n',
+    'o',
+    'p',
+    'q',
+    'r',
+    's',
+    't',
+    'u',
+    'v',
+    'w',
+    'x',
+    'y',
+    'z',
+    'Meta',
+    '*',
+    '+',
+    '-',
+    '/',
+    ';',
+    '=',
+    ',',
+    '.',
+    '`',
+    '[',
+    '\\',
+    ']',
+    "'",
+    'Attn',
+    'CrSel',
+    'ExSel',
+    'EraseEof',
+    'Play',
+    'ZoomOut',
+    ')',
+    '!',
+    '@',
+    '#',
+    '$',
+    '%',
+    '^',
+    '&',
+    '(',
+    'A',
+    'B',
+    'C',
+    'D',
+    'E',
+    'F',
+    'G',
+    'H',
+    'I',
+    'J',
+    'K',
+    'L',
+    'M',
+    'N',
+    'O',
+    'P',
+    'Q',
+    'R',
+    'S',
+    'T',
+    'U',
+    'V',
+    'W',
+    'X',
+    'Y',
+    'Z',
+    ':',
+    '<',
+    '_',
+    '>',
+    '?',
+    '~',
+    '{',
+    '|',
+    '}',
+    '"',
+    'SoftLeft',
+    'SoftRight',
+    'Camera',
+    'Call',
+    'EndCall',
+    'VolumeDown',
+    'VolumeUp',
+]);
+function throwIfInvalidKey(key) {
+    if (validKeys.has(key)) {
+        return key;
+    }
+    throw new Error(`${key} is invalid. Valid keys are: ${Array.from(validKeys.values()).join(',')}.`);
+}
+/**
+ * Returns the primary key, followed by modifiers in original order.
+ */
+export function parseKey(keyInput) {
+    let key = '';
+    const result = [];
+    for (const ch of keyInput) {
+        // Handle cases like Shift++.
+        if (ch === '+' && key) {
+            result.push(throwIfInvalidKey(key));
+            key = '';
+        }
+        else {
+            key += ch;
+        }
+    }
+    if (key) {
+        result.push(throwIfInvalidKey(key));
+    }
+    if (result.length === 0) {
+        throw new Error(`Key ${keyInput} could not be parsed.`);
+    }
+    if (new Set(result).size !== result.length) {
+        throw new Error(`Key ${keyInput} contains duplicate keys.`);
+    }
+    return [result.at(-1), ...result.slice(0, -1)];
+}

package/build/src/utils/pagination.js

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DEFAULT_PAGE_SIZE = 20;
+export function paginate(items, options) {
+    const total = items.length;
+    if (!options || noPaginationOptions(options)) {
+        return {
+            items,
+            currentPage: 0,
+            totalPages: 1,
+            hasNextPage: false,
+            hasPreviousPage: false,
+            startIndex: 0,
+            endIndex: total,
+            invalidPage: false,
+        };
+    }
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const totalPages = Math.max(1, Math.ceil(total / pageSize));
+    const { currentPage, invalidPage } = resolvePageIndex(options.pageIdx, totalPages);
+    const startIndex = currentPage * pageSize;
+    const pageItems = items.slice(startIndex, startIndex + pageSize);
+    const endIndex = startIndex + pageItems.length;
+    return {
+        items: pageItems,
+        currentPage,
+        totalPages,
+        hasNextPage: currentPage < totalPages - 1,
+        hasPreviousPage: currentPage > 0,
+        startIndex,
+        endIndex,
+        invalidPage,
+    };
+}
+function noPaginationOptions(options) {
+    return options.pageSize === undefined && options.pageIdx === undefined;
+}
+function resolvePageIndex(pageIdx, totalPages) {
+    if (pageIdx === undefined) {
+        return { currentPage: 0, invalidPage: false };
+    }
+    if (pageIdx < 0 || pageIdx >= totalPages) {
+        return { currentPage: 0, invalidPage: true };
+    }
+    return { currentPage: pageIdx, invalidPage: false };
+}

package/build/src/utils/types.js

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};