@mcp-b/chrome-devtools-mcp 0.0.0-beta-20260116040639

package/build/src/trace-processing/parse.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AgentFocus, TraceEngine, PerformanceTraceFormatter, PerformanceInsightFormatter, } from '../../vendor/chrome-devtools-frontend/mcp/mcp.js';
+import { logger } from '../logger.js';
+const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
+export function traceResultIsSuccess(x) {
+    return 'parsedTrace' in x;
+}
+export async function parseRawTraceBuffer(buffer) {
+    engine.resetProcessor();
+    if (!buffer) {
+        return {
+            error: 'No buffer was provided.',
+        };
+    }
+    const asString = new TextDecoder().decode(buffer);
+    if (!asString) {
+        return {
+            error: 'Decoding the trace buffer returned an empty string.',
+        };
+    }
+    try {
+        const data = JSON.parse(asString);
+        const events = Array.isArray(data) ? data : data.traceEvents;
+        await engine.parse(events);
+        const parsedTrace = engine.parsedTrace();
+        if (!parsedTrace) {
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
+        }
+        const insights = parsedTrace?.insights ?? null;
+        return {
+            parsedTrace,
+            insights,
+        };
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Unexpected error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
+    }
+}
+const extraFormatDescriptions = `Information on performance traces may contain main thread activity represented as call frames and network requests.
+
+${PerformanceTraceFormatter.callFrameDataFormatDescription}
+
+${PerformanceTraceFormatter.networkDataFormatDescription}`;
+export function getTraceSummary(result) {
+    const focus = AgentFocus.fromParsedTrace(result.parsedTrace);
+    const formatter = new PerformanceTraceFormatter(focus);
+    const summaryText = formatter.formatTraceSummary();
+    return `## Summary of Performance trace findings:
+${summaryText}
+
+## Details on call tree & network request formats:
+${extraFormatDescriptions}`;
+}
+export function getInsightOutput(result, insightSetId, insightName) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
+    const insightSet = result.insights.get(insightSetId);
+    if (!insightSet) {
+        return {
+            error: 'No Performance Insights for the given insight set id. Only use ids given in the "Available insight sets" list.',
+        };
+    }
+    const matchingInsight = insightName in insightSet.model ? insightSet.model[insightName] : null;
+    if (!matchingInsight) {
+        return {
+            error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
+        };
+    }
+    const formatter = new PerformanceInsightFormatter(AgentFocus.fromParsedTrace(result.parsedTrace), matchingInsight);
+    return { output: formatter.formatInsight() };
+}

package/build/src/transports/WebMCPBridgeScript.js

@@ -0,0 +1,220 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Bridge script that gets injected into the page via CDP.
+ *
+ * This script acts as a ferry between Chrome DevTools Protocol (CDP) and
+ * the page's TabServerTransport. It does NOT understand MCP - it simply
+ * forwards JSON-RPC messages between the two transport layers.
+ *
+ * Communication flow:
+ *
+ * CDP → Page (requests):
+ *   1. CDP calls Runtime.evaluate with __mcpCdpBridge.toServer(messageJson)
+ *   2. Bridge parses the message and posts it via window.postMessage
+ *   3. TabServerTransport receives it and processes the MCP request
+ *
+ * Page → CDP (responses/notifications):
+ *   1. TabServerTransport sends response via window.postMessage
+ *   2. Bridge's message listener catches it
+ *   3. Bridge calls window.__mcpBridgeToClient(messageJson)
+ *   4. CDP receives it via Runtime.bindingCalled event
+ *
+ * The bridge uses the same message format as TabServerTransport:
+ * {
+ *   channel: 'mcp-default',
+ *   type: 'mcp',
+ *   direction: 'client-to-server' | 'server-to-client',
+ *   payload: JSONRPCMessage | 'mcp-check-ready' | 'mcp-server-ready' | 'mcp-server-stopped'
+ * }
+ */
+export const WEB_MCP_BRIDGE_SCRIPT = `
+(function() {
+  'use strict';
+
+  var CHANNEL_ID = 'mcp-default';
+  var BRIDGE_VERSION = '1.1.0';
+
+  // Prevent double injection - use __mcpCdpBridge to avoid collision with polyfill's __mcpBridge
+  if (window.__mcpCdpBridge && window.__mcpCdpBridge.version === BRIDGE_VERSION) {
+    return { alreadyInjected: true };
+  }
+
+  // Track if we've seen the server ready signal
+  var serverReady = false;
+  var webMCPDetected = false;
+
+  // Listen for messages FROM TabServerTransport (server-to-client direction)
+  // These are responses and notifications from the MCP server
+  function handleServerMessage(event) {
+    // Only handle messages from the same window (posted by TabServerTransport)
+    if (event.source !== window) return;
+
+    var data = event.data;
+
+    // Validate message format
+    if (!data || data.channel !== CHANNEL_ID || data.type !== 'mcp') return;
+    if (data.direction !== 'server-to-client') return;
+
+    var payload = data.payload;
+
+    // Track server ready state
+    if (payload === 'mcp-server-ready') {
+      serverReady = true;
+    } else if (payload === 'mcp-server-stopped') {
+      serverReady = false;
+    }
+
+    // Forward to CDP client via the binding.
+    // NOTE: We use '__mcpBridgeToClient' (not '__mcpCdpBridgeToClient') for the CDP binding
+    // because this name is set up by WebMCPClientTransport.connect() via Runtime.addBinding,
+    // which is separate from the window property '__mcpCdpBridge'. The window property was
+    // renamed to avoid collision with the polyfill's internal '__mcpBridge', but the CDP
+    // binding name doesn't conflict with anything and changing it would require coordinated
+    // updates to both the bridge script and WebMCPClientTransport.
+    if (typeof window.__mcpBridgeToClient === 'function') {
+      try {
+        var messageJson = typeof payload === 'string' ? JSON.stringify(payload) : JSON.stringify(payload);
+        window.__mcpBridgeToClient(messageJson);
+      } catch (err) {
+        console.error('[WebMCP Bridge] Failed to forward message to CDP:', err);
+      }
+    }
+  }
+
+  window.addEventListener('message', handleServerMessage);
+
+  // Check if WebMCP (navigator.modelContext) is available
+  function checkWebMCPAvailable() {
+    if (typeof navigator !== 'undefined' && navigator.modelContext) {
+      webMCPDetected = true;
+      return true;
+    }
+    if (window.__MCP_BRIDGE__) {
+      webMCPDetected = true;
+      return true;
+    }
+    return false;
+  }
+
+  // Initial check
+  checkWebMCPAvailable();
+
+  // Expose the bridge API for CDP to call
+  // Use __mcpCdpBridge to avoid collision with polyfill's __mcpBridge
+  Object.defineProperty(window, '__mcpCdpBridge', {
+    value: {
+    version: BRIDGE_VERSION,
+
+    /**
+     * Send a message to the TabServerTransport (client-to-server direction)
+     * Called by CDP via Runtime.evaluate
+     *
+     * @param {string} payloadJson - JSON string of the payload to send
+     * @returns {boolean} true if message was sent
+     */
+    toServer: function(payloadJson) {
+      try {
+        var payload = JSON.parse(payloadJson);
+
+        window.postMessage({
+          channel: CHANNEL_ID,
+          type: 'mcp',
+          direction: 'client-to-server',
+          payload: payload
+        }, window.location.origin);
+
+        return true;
+      } catch (err) {
+        console.error('[WebMCP Bridge] Failed to send to server:', err);
+        return false;
+      }
+    },
+
+    /**
+     * Check if the bridge is ready and functional
+     * @returns {boolean}
+     */
+    isReady: function() {
+      return true;
+    },
+
+    /**
+     * Check if WebMCP is available on this page
+     * Re-checks each time in case polyfill loaded after bridge injection
+     * @returns {boolean}
+     */
+    hasWebMCP: function() {
+      return checkWebMCPAvailable();
+    },
+
+    /**
+     * Check if the MCP server has signaled ready
+     * @returns {boolean}
+     */
+    isServerReady: function() {
+      return serverReady;
+    },
+
+    /**
+     * Send the check-ready signal to TabServerTransport
+     * This triggers the server to respond with 'mcp-server-ready'
+     */
+    checkReady: function() {
+      window.postMessage({
+        channel: CHANNEL_ID,
+        type: 'mcp',
+        direction: 'client-to-server',
+        payload: 'mcp-check-ready'
+      }, window.location.origin);
+    },
+
+    /**
+     * Get the channel ID being used
+     * @returns {string}
+     */
+    getChannelId: function() {
+      return CHANNEL_ID;
+    },
+
+    /**
+     * Clean up the bridge (remove listeners)
+     */
+    dispose: function() {
+      window.removeEventListener('message', handleServerMessage);
+      delete window.__mcpCdpBridge;
+    }
+  },
+  writable: true,
+  configurable: true
+  });
+
+  return { success: true, version: BRIDGE_VERSION, webMCPDetected: webMCPDetected };
+})();
+`;
+/**
+ * Check if WebMCP (@mcp-b/global) is available on the page.
+ * This script is evaluated before injecting the bridge.
+ */
+export const CHECK_WEBMCP_AVAILABLE_SCRIPT = `
+(function() {
+  // Check for navigator.modelContext (WebMCP polyfill or native)
+  if (typeof navigator !== 'undefined' && navigator.modelContext) {
+    return { available: true, type: 'modelContext' };
+  }
+
+  // Check for internal bridge (set by @mcp-b/global)
+  if (window.__MCP_BRIDGE__) {
+    return { available: true, type: 'bridge' };
+  }
+
+  // Check for TabServerTransport markers
+  // The TabServerTransport broadcasts 'mcp-server-ready' on start
+  // We can't detect this without listening, so we check for common indicators
+
+  return { available: false };
+})();
+`;

package/build/src/transports/WebMCPClientTransport.js

@@ -0,0 +1,401 @@
+/**
+ * @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;
+    /** 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, bridge is gone
+                    this._handleNavigation();
+                }
+            };
+            // 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 - bridge is lost
+     *
+     * Navigation is a normal lifecycle event in browsers, not a fatal error.
+     * We perform full teardown (detach CDP session, remove listeners) and
+     * allow the client to reconnect by creating a new transport instance.
+     */
+    _handleNavigation() {
+        if (this._closed)
+            return;
+        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?.();
+    }
+    /**
+     * 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?.();
+    }
+}