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

package/build/src/tools/snapshot.js

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool, timeoutSchema } from './ToolDefinition.js';
+export const takeSnapshot = defineTool({
+    name: 'take_snapshot',
+    description: `Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique
+identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
+in the DevTools Elements panel (if any).`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
+    },
+    schema: {
+        verbose: zod
+            .boolean()
+            .optional()
+            .describe('Whether to include all possible information available in the full a11y tree. Default is false.'),
+        filePath: zod
+            .string()
+            .optional()
+            .describe('The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.'),
+    },
+    handler: async (request, response) => {
+        response.includeSnapshot({
+            verbose: request.params.verbose ?? false,
+            filePath: request.params.filePath,
+        });
+    },
+});
+export const waitFor = defineTool({
+    name: 'wait_for',
+    description: `Wait for the specified text to appear on the selected page.`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        text: zod.string().describe('Text to appear on the page'),
+        ...timeoutSchema,
+    },
+    handler: async (request, response, context) => {
+        await context.waitForTextOnPage(request.params.text, request.params.timeout);
+        response.appendResponseLine(`Element with text "${request.params.text}" found.`);
+        response.includeSnapshot();
+    },
+});

package/build/src/tools/tools.js

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as consoleTools from './console.js';
+import * as emulationTools from './emulation.js';
+import * as inputTools from './input.js';
+import * as networkTools from './network.js';
+import * as pagesTools from './pages.js';
+import * as performanceTools from './performance.js';
+import * as screenshotTools from './screenshot.js';
+import * as scriptTools from './script.js';
+import * as snapshotTools from './snapshot.js';
+import * as webmcpTools from './webmcp.js';
+const tools = [
+    ...Object.values(consoleTools),
+    ...Object.values(emulationTools),
+    ...Object.values(inputTools),
+    ...Object.values(networkTools),
+    ...Object.values(pagesTools),
+    ...Object.values(performanceTools),
+    ...Object.values(screenshotTools),
+    ...Object.values(scriptTools),
+    ...Object.values(snapshotTools),
+    ...Object.values(webmcpTools),
+];
+tools.sort((a, b) => {
+    return a.name.localeCompare(b.name);
+});
+export { tools };

package/build/src/tools/webmcp.js

@@ -0,0 +1,233 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { WebMCPClientTransport, CHECK_WEBMCP_AVAILABLE_SCRIPT, } from '../transports/index.js';
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+/**
+ * Module-level storage for WebMCP client and transport.
+ * Only one connection is maintained at a time per page.
+ */
+let webMCPClient = null;
+let webMCPTransport = null;
+/**
+ * Connect to MCP tools registered on the current webpage via WebMCP.
+ *
+ * This tool injects a bridge into the page that connects to the page's
+ * TabServerTransport, enabling access to tools registered with @mcp-b/global.
+ */
+export const connectWebMCP = defineTool({
+    name: 'connect_webmcp',
+    description: 'Connect to MCP tools registered on the current webpage via WebMCP. ' +
+        'This enables calling tools that the website has exposed through the Web Model Context API. ' +
+        'The page must have @mcp-b/global loaded.',
+    annotations: {
+        title: 'Connect to Website MCP Tools',
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        const page = context.getSelectedPage();
+        // Check if already connected
+        if (webMCPClient) {
+            response.appendResponseLine('Already connected to WebMCP. Use disconnect_webmcp first to reconnect.');
+            return;
+        }
+        // Check if WebMCP is available on the page
+        let hasWebMCP = false;
+        try {
+            const result = (await page.evaluate(CHECK_WEBMCP_AVAILABLE_SCRIPT));
+            hasWebMCP = result.available;
+        }
+        catch {
+            hasWebMCP = false;
+        }
+        if (!hasWebMCP) {
+            response.appendResponseLine('WebMCP not detected on this page.');
+            response.appendResponseLine('');
+            response.appendResponseLine('To use website tools, the page needs @mcp-b/global loaded.');
+            response.appendResponseLine('Add to your page:');
+            response.appendResponseLine('  <script type="module" src="https://unpkg.com/@mcp-b/global"></script>');
+            return;
+        }
+        try {
+            // Create transport and client
+            const transport = new WebMCPClientTransport({
+                page,
+                readyTimeout: 10000,
+                requireWebMCP: false, // We already checked
+            });
+            const client = new Client({ name: 'chrome-devtools-mcp', version: '1.0.0' }, { capabilities: {} });
+            await client.connect(transport);
+            // Store for later use
+            webMCPTransport = transport;
+            webMCPClient = client;
+            // List available tools
+            const { tools } = await client.listTools();
+            response.appendResponseLine('Connected to WebMCP server');
+            response.appendResponseLine('');
+            response.appendResponseLine(`Found ${tools.length} tool(s):`);
+            if (tools.length === 0) {
+                response.appendResponseLine('  (no tools registered yet)');
+            }
+            else {
+                for (const tool of tools) {
+                    response.appendResponseLine(`  - ${tool.name}`);
+                    if (tool.description) {
+                        response.appendResponseLine(`    ${tool.description}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            response.appendResponseLine(`Failed to connect: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    },
+});
+/**
+ * List all MCP tools available on the connected webpage.
+ */
+export const listWebMCPTools = defineTool({
+    name: 'list_webmcp_tools',
+    description: 'List all MCP tools available on the connected webpage. ' +
+        'Run connect_webmcp first to establish a connection.',
+    annotations: {
+        title: 'List Website MCP Tools',
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, _context) => {
+        if (!webMCPClient) {
+            response.appendResponseLine('Not connected to WebMCP. Run connect_webmcp first.');
+            return;
+        }
+        try {
+            const { tools } = await webMCPClient.listTools();
+            response.appendResponseLine(`${tools.length} tool(s) available:`);
+            response.appendResponseLine('');
+            for (const tool of tools) {
+                response.appendResponseLine(`- ${tool.name}`);
+                if (tool.description) {
+                    response.appendResponseLine(`  Description: ${tool.description}`);
+                }
+                if (tool.inputSchema) {
+                    const schemaStr = JSON.stringify(tool.inputSchema, null, 2);
+                    // Only show schema if it's not too long
+                    if (schemaStr.length < 500) {
+                        response.appendResponseLine(`  Input Schema: ${schemaStr}`);
+                    }
+                    else {
+                        response.appendResponseLine(`  Input Schema: (complex schema, ${schemaStr.length} chars)`);
+                    }
+                }
+                response.appendResponseLine('');
+            }
+        }
+        catch (err) {
+            response.appendResponseLine(`Failed to list tools: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    },
+});
+/**
+ * Call a tool registered on the webpage via WebMCP.
+ */
+export const callWebMCPTool = defineTool({
+    name: 'call_webmcp_tool',
+    description: 'Call a tool registered on the webpage via WebMCP. ' +
+        'Use list_webmcp_tools to see available tools and their schemas.',
+    annotations: {
+        title: 'Call Website MCP Tool',
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: false, // Tools may have side effects
+    },
+    schema: {
+        name: zod.string().describe('The name of the tool to call'),
+        arguments: zod
+            .record(zod.any())
+            .optional()
+            .describe('Arguments to pass to the tool as a JSON object'),
+    },
+    handler: async (request, response, _context) => {
+        if (!webMCPClient) {
+            response.appendResponseLine('Not connected to WebMCP. Run connect_webmcp first.');
+            return;
+        }
+        const { name, arguments: args } = request.params;
+        try {
+            response.appendResponseLine(`Calling tool: ${name}`);
+            if (args && Object.keys(args).length > 0) {
+                response.appendResponseLine(`Arguments: ${JSON.stringify(args)}`);
+            }
+            response.appendResponseLine('');
+            const result = await webMCPClient.callTool({
+                name,
+                arguments: args || {},
+            });
+            response.appendResponseLine('Result:');
+            // Format the result content
+            if (result.content && Array.isArray(result.content)) {
+                for (const content of result.content) {
+                    if (content.type === 'text') {
+                        response.appendResponseLine(content.text);
+                    }
+                    else if (content.type === 'image') {
+                        response.appendResponseLine(`[Image: ${content.mimeType}, ${content.data.length} bytes]`);
+                    }
+                    else if (content.type === 'resource') {
+                        response.appendResponseLine(`[Resource: ${JSON.stringify(content.resource)}]`);
+                    }
+                    else {
+                        response.appendResponseLine(JSON.stringify(content, null, 2));
+                    }
+                }
+            }
+            else {
+                response.appendResponseLine(JSON.stringify(result, null, 2));
+            }
+            if (result.isError) {
+                response.appendResponseLine('');
+                response.appendResponseLine('(Tool returned an error)');
+            }
+        }
+        catch (err) {
+            response.appendResponseLine(`Failed to call tool: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    },
+});
+/**
+ * Disconnect from the WebMCP server on the current page.
+ */
+export const disconnectWebMCP = defineTool({
+    name: 'disconnect_webmcp',
+    description: 'Disconnect from the WebMCP server on the current page.',
+    annotations: {
+        title: 'Disconnect from Website MCP',
+        category: ToolCategory.WEBMCP,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, _context) => {
+        if (!webMCPClient) {
+            response.appendResponseLine('Not connected to WebMCP.');
+            return;
+        }
+        try {
+            await webMCPClient.close();
+            webMCPClient = null;
+            webMCPTransport = null;
+            response.appendResponseLine('Disconnected from WebMCP.');
+        }
+        catch (err) {
+            response.appendResponseLine(`Error disconnecting: ${err instanceof Error ? err.message : String(err)}`);
+            // Clear anyway
+            webMCPClient = null;
+            webMCPTransport = null;
+        }
+    },
+});

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 '../../node_modules/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,196 @@
+/**
+ * @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 __mcpBridge.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.0.0';
+
+  // Prevent double injection
+  if (window.__mcpBridge && window.__mcpBridge.version === BRIDGE_VERSION) {
+    console.log('[WebMCP Bridge] Already injected (v' + BRIDGE_VERSION + '), skipping');
+    return { alreadyInjected: true };
+  }
+
+  console.log('[WebMCP Bridge] Initializing CDP <-> TabServer bridge v' + BRIDGE_VERSION);
+
+  // Track if we've seen the server ready signal
+  var serverReady = false;
+  var pendingMessages = [];
+
+  // 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') {
+      console.log('[WebMCP Bridge] Server ready signal received');
+      serverReady = true;
+    } else if (payload === 'mcp-server-stopped') {
+      console.log('[WebMCP Bridge] Server stopped signal received');
+      serverReady = false;
+    }
+
+    // Forward to CDP client via the binding
+    // The binding '__mcpBridgeToClient' is set up by CDPClientTransport before injection
+    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);
+      }
+    } else {
+      console.warn('[WebMCP Bridge] CDP binding not available, message dropped');
+    }
+  }
+
+  window.addEventListener('message', handleServerMessage);
+
+  // Expose the bridge API for CDP to call
+  window.__mcpBridge = {
+    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 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() {
+      console.log('[WebMCP Bridge] Sending check-ready signal');
+      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() {
+      console.log('[WebMCP Bridge] Disposing');
+      window.removeEventListener('message', handleServerMessage);
+      delete window.__mcpBridge;
+    }
+  };
+
+  console.log('[WebMCP Bridge] Ready - window.__mcpBridge available');
+
+  return { success: true, version: BRIDGE_VERSION };
+})();
+`;
+/**
+ * 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 };
+})();
+`;