@mcp-b/chrome-devtools-mcp 1.2.0 → 1.3.1

package/build/src/browser.js

@@ -8,7 +8,16 @@ import os from 'node:os';
 import path from 'node:path';
 import { logger } from './logger.js';
 import { puppeteer } from './third_party/index.js';
+/** Cached browser instance for reuse across calls. */
 let browser;
+/**
+ * Create a target filter for Puppeteer that excludes internal Chrome pages.
+ *
+ * Includes new tab and inspect pages (may be the only user-accessible page),
+ * but excludes chrome://, chrome-extension://, and chrome-untrusted:// pages.
+ *
+ * @returns A filter function for Puppeteer's targetFilter option.
+ */
 function makeTargetFilter() {
     const ignoredPrefixes = new Set([
         'chrome://',
@@ -19,7 +28,6 @@ function makeTargetFilter() {
         if (target.url() === 'chrome://newtab/') {
             return true;
         }
-        // Could be the only page opened in the browser.
         if (target.url().startsWith('chrome://inspect')) {
             return true;
         }
@@ -31,7 +39,21 @@ function makeTargetFilter() {
         return true;
     };
 }
+/**
+ * Connect to an existing Chrome browser instance.
+ *
+ * Connection priority:
+ * 1. wsEndpoint - Direct WebSocket connection with optional headers
+ * 2. browserURL - HTTP URL to Chrome's DevTools endpoint
+ * 3. userDataDir - Read DevToolsActivePort from profile directory
+ * 4. channel - Derive profile directory from channel name
+ *
+ * @param options - Connection options.
+ * @returns Connected browser instance.
+ * @throws Error if connection fails or no connection method specified.
+ */
 export async function ensureBrowserConnected(options) {
+    const { channel } = options;
     if (browser?.connected) {
         return browser;
     }
@@ -49,14 +71,91 @@ export async function ensureBrowserConnected(options) {
     else if (options.browserURL) {
         connectOptions.browserURL = options.browserURL;
     }
+    else if (channel || options.userDataDir) {
+        const userDataDir = options.userDataDir;
+        if (userDataDir) {
+            // TODO: re-expose this logic via Puppeteer.
+            const portPath = path.join(userDataDir, 'DevToolsActivePort');
+            try {
+                const fileContent = await fs.promises.readFile(portPath, 'utf8');
+                const [rawPort, rawPath] = fileContent
+                    .split('\n')
+                    .map(line => {
+                    return line.trim();
+                })
+                    .filter(line => {
+                    return !!line;
+                });
+                if (!rawPort || !rawPath) {
+                    throw new Error(`Invalid DevToolsActivePort '${fileContent}' found`);
+                }
+                const port = parseInt(rawPort, 10);
+                if (isNaN(port) || port <= 0 || port > 65535) {
+                    throw new Error(`Invalid port '${rawPort}' found`);
+                }
+                const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
+                connectOptions.browserWSEndpoint = browserWSEndpoint;
+            }
+            catch (error) {
+                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled.`, {
+                    cause: error,
+                });
+            }
+        }
+        else {
+            if (!channel) {
+                throw new Error('Channel must be provided if userDataDir is missing');
+            }
+            // Derive the default userDataDir from the channel (same as launch does)
+            const profileDirName = channel && channel !== 'stable'
+                ? `chrome-profile-${channel}`
+                : 'chrome-profile';
+            const derivedUserDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
+            // Try to read DevToolsActivePort from the derived userDataDir
+            const portPath = path.join(derivedUserDataDir, 'DevToolsActivePort');
+            try {
+                const fileContent = await fs.promises.readFile(portPath, 'utf8');
+                const [rawPort, rawPath] = fileContent
+                    .split('\n')
+                    .map(line => line.trim())
+                    .filter(line => !!line);
+                if (!rawPort || !rawPath) {
+                    throw new Error(`Invalid DevToolsActivePort '${fileContent}' found`);
+                }
+                const port = parseInt(rawPort, 10);
+                if (isNaN(port) || port <= 0 || port > 65535) {
+                    throw new Error(`Invalid port '${rawPort}' found`);
+                }
+                const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
+                connectOptions.browserWSEndpoint = browserWSEndpoint;
+            }
+            catch (error) {
+                throw new Error(`Could not connect to Chrome ${channel} channel in ${derivedUserDataDir}. Check if Chrome is running and was launched with remote debugging enabled.`, { cause: error });
+            }
+        }
+    }
     else {
-        throw new Error('Either browserURL or wsEndpoint must be provided');
+        throw new Error('Either browserURL, wsEndpoint, channel or userDataDir must be provided');
     }
     logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
-    browser = await puppeteer.connect(connectOptions);
+    try {
+        browser = await puppeteer.connect(connectOptions);
+    }
+    catch (err) {
+        throw new Error('Could not connect to Chrome. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.', {
+            cause: err,
+        });
+    }
     logger('Connected Puppeteer');
     return browser;
 }
+/**
+ * Launch a new Chrome browser instance.
+ *
+ * @param options - Launch configuration options.
+ * @returns Launched browser instance.
+ * @throws Error if Chrome is already running with the same profile.
+ */
 export async function launch(options) {
     const { channel, executablePath, headless, isolated } = options;
     const profileDirName = channel && channel !== 'stable'
@@ -69,10 +168,21 @@ export async function launch(options) {
             recursive: true,
         });
     }
+    const extraArgs = options.args ?? [];
+    const hasRemoteDebuggingPipe = extraArgs.includes('--remote-debugging-pipe');
+    const hasRemoteDebuggingPort = extraArgs.some(arg => arg.startsWith('--remote-debugging-port'));
+    const hasRemoteDebuggingAddress = extraArgs.some(arg => arg.startsWith('--remote-debugging-address'));
     const args = [
-        ...(options.args ?? []),
+        ...extraArgs,
         '--hide-crash-restore-bubble',
     ];
+    const enableRemoteDebuggingPort = !isolated && !hasRemoteDebuggingPipe && !hasRemoteDebuggingPort;
+    if (enableRemoteDebuggingPort) {
+        args.push('--remote-debugging-port=0');
+        if (!hasRemoteDebuggingAddress) {
+            args.push('--remote-debugging-address=127.0.0.1');
+        }
+    }
     if (headless) {
         args.push('--screen-info={3840x2160}');
     }
@@ -86,6 +196,8 @@ export async function launch(options) {
                 ? `chrome-${channel}`
                 : 'chrome';
     }
+    const usePipe = hasRemoteDebuggingPipe ||
+        (!hasRemoteDebuggingPort && !enableRemoteDebuggingPort);
     try {
         const browser = await puppeteer.launch({
             channel: puppeteerChannel,
@@ -93,7 +205,7 @@ export async function launch(options) {
             executablePath,
             defaultViewport: null,
             userDataDir,
-            pipe: true,
+            pipe: usePipe,
             headless,
             args,
             acceptInsecureCerts: options.acceptInsecureCerts,
@@ -125,6 +237,12 @@ export async function launch(options) {
         throw error;
     }
 }
+/**
+ * Ensure a browser is launched, reusing existing instance if connected.
+ *
+ * @param options - Launch configuration options.
+ * @returns Connected or newly launched browser instance.
+ */
 export async function ensureBrowserLaunched(options) {
     if (browser?.connected) {
         return browser;

package/build/src/cli.js

@@ -5,6 +5,17 @@
  */
 import { yargs, hideBin } from './third_party/index.js';
 export const cliOptions = {
+    autoConnect: {
+        type: 'boolean',
+        description: 'If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param. Falls back to launching a new instance if no running browser is found.',
+        default: true,
+        coerce: (value) => {
+            if (value === false) {
+                return false;
+            }
+            return true;
+        },
+    },
     browserUrl: {
         type: 'string',
         description: 'Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.',
@@ -163,7 +174,7 @@ export function parseArguments(version, argv = process.argv) {
             !args.browserUrl &&
             !args.wsEndpoint &&
             !args.executablePath) {
-            args.channel = 'stable';
+            args.channel = 'dev';
         }
         return true;
     })
@@ -204,6 +215,14 @@ export function parseArguments(version, argv = process.argv) {
             '$0 --user-data-dir=/tmp/user-data-dir',
             'Use a custom user data directory',
         ],
+        [
+            '$0 --auto-connect',
+            'Connect to a stable Chrome instance (Chrome 145+) running instead of launching a new instance',
+        ],
+        [
+            '$0 --auto-connect --channel=canary',
+            'Connect to a canary Chrome instance (Chrome 145+) running instead of launching a new instance',
+        ],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))

package/build/src/main.js

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import process from 'node:process';
 import './polyfill.js';
 import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { parseArguments } from './cli.js';
@@ -15,10 +16,17 @@ import { McpServer, StdioServerTransport, SetLevelRequestSchema, } from './third
 import { registerPrompts } from './prompts/index.js';
 import { ToolCategory } from './tools/categories.js';
 import { tools } from './tools/tools.js';
-// If moved update release-please config
+import { WebMCPToolHub } from './tools/WebMCPToolHub.js';
+/**
+ * Package version (managed by release-please).
+ * @remarks If moved, update release-please config.
+ */
 // x-release-please-start-version
-const VERSION = '0.11.0';
+const VERSION = '0.12.1';
 // x-release-please-end
+process.on('unhandledRejection', (reason, promise) => {
+    logger('Unhandled promise rejection', promise, reason);
+});
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
@@ -26,27 +34,75 @@ const server = new McpServer({
     name: 'chrome_devtools',
     title: 'Chrome DevTools MCP server',
     version: VERSION,
-}, { capabilities: { logging: {}, prompts: {} } });
+}, { capabilities: { logging: {}, prompts: {}, tools: { listChanged: true } } });
 // Register WebMCP development prompts
 registerPrompts(server);
 server.server.setRequestHandler(SetLevelRequestSchema, () => {
     return {};
 });
+/** Cached McpContext instance for the current browser. */
 let context;
+/**
+ * Get or create the McpContext for browser operations.
+ *
+ * Handles browser connection/launch with the following priority:
+ * 1. Explicit browserUrl/wsEndpoint - connect directly
+ * 2. autoConnect enabled - try connecting, fall back to launching
+ * 3. Otherwise - launch a new browser
+ *
+ * @returns Initialized McpContext ready for tool operations.
+ */
 async function getContext() {
     const extraArgs = (args.chromeArg ?? []).map(String);
     if (args.proxyServer) {
         extraArgs.push(`--proxy-server=${args.proxyServer}`);
     }
     const devtools = args.experimentalDevtools ?? false;
-    const browser = args.browserUrl || args.wsEndpoint
-        ? await ensureBrowserConnected({
+    let browser;
+    // If explicit browserUrl or wsEndpoint is provided, connect without fallback
+    if (args.browserUrl || args.wsEndpoint) {
+        browser = await ensureBrowserConnected({
             browserURL: args.browserUrl,
             wsEndpoint: args.wsEndpoint,
             wsHeaders: args.wsHeaders,
             devtools,
-        })
-        : await ensureBrowserLaunched({
+            channel: undefined,
+            userDataDir: args.userDataDir,
+        });
+    }
+    // If autoConnect is true, try connecting first, then fall back to launching
+    else if (args.autoConnect) {
+        try {
+            logger('Attempting to connect to running browser instance...');
+            browser = await ensureBrowserConnected({
+                browserURL: undefined,
+                wsEndpoint: undefined,
+                wsHeaders: undefined,
+                devtools,
+                channel: args.channel,
+                userDataDir: args.userDataDir,
+            });
+            logger('Successfully connected to running browser instance');
+        }
+        catch (err) {
+            logger('Failed to connect to running browser, launching new instance...', err);
+            browser = await ensureBrowserLaunched({
+                headless: args.headless,
+                executablePath: args.executablePath,
+                channel: args.channel,
+                isolated: args.isolated ?? false,
+                userDataDir: args.userDataDir,
+                logFile,
+                viewport: args.viewport,
+                args: extraArgs,
+                acceptInsecureCerts: args.acceptInsecureCerts,
+                devtools,
+            });
+        }
+    }
+    // Otherwise, just launch a new browser
+    else {
+        browser = await ensureBrowserLaunched({
             headless: args.headless,
             executablePath: args.executablePath,
             channel: args.channel,
@@ -58,20 +114,41 @@ async function getContext() {
             acceptInsecureCerts: args.acceptInsecureCerts,
             devtools,
         });
+    }
     if (context?.browser !== browser) {
         context = await McpContext.from(browser, logger, {
             experimentalDevToolsDebugging: devtools,
             experimentalIncludeAllPages: args.experimentalIncludeAllPages,
         });
+        // Initialize WebMCP tool hub for dynamic tool registration
+        const toolHub = new WebMCPToolHub(server, context);
+        context.setToolHub(toolHub);
+        logger('WebMCPToolHub initialized for dynamic tool registration');
     }
     return context;
 }
+/**
+ * Log security disclaimers to stderr.
+ *
+ * Warns users that browser content is exposed to MCP clients.
+ */
 const logDisclaimers = () => {
     console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
 debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
 };
+/**
+ * Mutex to serialize tool execution and prevent concurrent modifications.
+ */
 const toolMutex = new Mutex();
+/**
+ * Register a tool with the MCP server.
+ *
+ * Handles category-based filtering (emulation, performance, network)
+ * and wraps the handler with context initialization and error handling.
+ *
+ * @param tool - Tool definition to register.
+ */
 function registerTool(tool) {
     if (tool.annotations.category === ToolCategory.EMULATION &&
         args.categoryEmulation === false) {
@@ -107,7 +184,10 @@ function registerTool(tool) {
         }
         catch (err) {
             logger(`${tool.name} error:`, err, err?.stack);
-            const errorText = err && 'message' in err ? err.message : String(err);
+            let errorText = err && 'message' in err ? err.message : String(err);
+            if ('cause' in err && err.cause) {
+                errorText += `\nCause: ${err.cause.message}`;
+            }
             return {
                 content: [
                     {

package/build/src/prompts/index.js

@@ -27,8 +27,8 @@ export function registerPrompts(server) {
 1. **Write the Tool**: I'll ask you to create a WebMCP tool in my codebase using @mcp-b/global
 2. **Hot Reload**: My dev server will automatically reload with the new tool
 3. **Navigate**: Use navigate_page to open my dev server (e.g., http://localhost:3000)
-4. **Discover**: Use list_webmcp_tools to see if the tool appears
-5. **Test**: Use call_webmcp_tool to test the tool with sample inputs
+4. **Discover**: Use diff_webmcp_tools to see registered tools (shown with callable names like webmcp_localhost_3000_page0_my_tool)
+5. **Test**: Call the tool directly by its prefixed name (e.g., webmcp_localhost_3000_page0_my_tool)
 6. **Iterate**: If something is wrong, fix the code and repeat
 
 ## Tool Registration Pattern
@@ -92,9 +92,9 @@ What would you like to build? Describe the tool you need and I'll help you imple
 ## Test Plan
 
 1. Navigate to ${url}
-2. Use list_webmcp_tools to discover available tools
+2. Use diff_webmcp_tools to discover registered tools (shown with callable names like webmcp_localhost_3000_page0_tool_name)
 3. ${toolNameInstruction}
-4. Test the tool with various inputs:
+4. Call the tool directly by its prefixed name and test with various inputs:
    - Valid inputs (happy path)
    - Edge cases (empty strings, nulls, etc.)
    - Invalid inputs (wrong types, missing required fields)
@@ -138,7 +138,7 @@ ${urlInstruction}
    - Errors loading @mcp-b/global
    - Tool registration errors
    - Any JavaScript errors
-3. **Test WebMCP**: Try list_webmcp_tools to see if connection works
+3. **Test WebMCP**: Try diff_webmcp_tools to see if connection works
 4. **Verify registration**: If no tools appear, check if the code properly imports '@mcp-b/global' and calls registerTool
 
 ## Common Issues

package/build/src/third_party/index.js

@@ -10,7 +10,7 @@ export { hideBin } from 'yargs/helpers';
 export { default as debug } from 'debug';
 export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-export { SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+export { SetLevelRequestSchema, ToolListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
 export { z as zod } from 'zod';
 export { Locator, PredefinedNetworkConditions, CDPSessionEvent, } from 'puppeteer-core';
 export { default as puppeteer } from 'puppeteer-core';