chrome-devtools-mcp 1.1.1 → 1.3.0

package/build/src/ToolHandler.js

@@ -139,15 +139,21 @@ export class ToolHandler {
         const startTime = Date.now();
         let success = false;
         try {
-            logger(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            logger?.(`${this.tool.name} request: ${JSON.stringify(params, null, '  ')}`);
             const context = await this.getContext();
-            logger(`${this.tool.name} context: resolved`);
+            logger?.(`${this.tool.name} context: resolved`);
             await context.detectOpenDevToolsWindows();
             const response = this.serverArgs.slim
                 ? new SlimMcpResponse(this.serverArgs)
                 : new McpResponse(this.serverArgs);
             response.setRedactNetworkHeaders(this.serverArgs.redactNetworkHeaders);
             try {
+                if (this.tool.verifyFilesSchema) {
+                    for (const key of this.tool.verifyFilesSchema) {
+                        const filePath = params[key];
+                        await context.validatePath(filePath);
+                    }
+                }
                 if (isPageScopedTool(this.tool)) {
                     const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
                     const page = this.serverArgs.experimentalPageIdRouting &&
@@ -173,7 +179,7 @@ export class ToolHandler {
             catch (err) {
                 response.setError(err);
             }
-            const { content, structuredContent } = await response.handle(this.tool.name, context);
+            const { content, structuredContent } = await response.handle(this.tool.name, context, this.serverArgs.experimentalToonFormat ?? false);
             const result = {
                 content,
             };
@@ -187,7 +193,7 @@ export class ToolHandler {
             return result;
         }
         catch (err) {
-            logger(`${this.tool.name} error:`, err, err?.stack);
+            logger?.(`${this.tool.name} error:`, err, err?.stack);
             let errorText = err && 'message' in err ? err.message : String(err);
             if ('cause' in err && err.cause) {
                 errorText += `\nCause: ${err.cause.message}`;

package/build/src/WaitForHelper.js

@@ -138,7 +138,7 @@ export class WaitForHelper {
             }
             return;
         })
-            .catch(error => logger(error));
+            .catch(error => logger?.(error));
         try {
             await action();
         }
@@ -157,7 +157,7 @@ export class WaitForHelper {
             await this.waitForStableDom();
         }
         catch (error) {
-            logger(error);
+            logger?.(error);
         }
         finally {
             this.#abortController.abort();

package/build/src/bin/chrome-devtools-cli-options.js

@@ -58,6 +58,18 @@ export const commands = {
             },
         },
     },
+    close_heapsnapshot: {
+        description: 'Closes a previously loaded memory heapsnapshot, freeing its memory. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to the .heapsnapshot file to close.',
+                required: true,
+            },
+        },
+    },
     close_page: {
         description: 'Closes the page by its index. The last open page cannot be closed.',
         category: 'Navigation automation',
@@ -247,7 +259,7 @@ export const commands = {
         },
     },
     get_heapsnapshot_class_nodes: {
-        description: 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --experimentalMemory=true)',
+        description: 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs. (requires flag: --memoryDebugging=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -277,7 +289,7 @@ export const commands = {
         },
     },
     get_heapsnapshot_details: {
-        description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --experimentalMemory=true)',
+        description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates. (requires flag: --memoryDebugging=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -300,8 +312,56 @@ export const commands = {
             },
         },
     },
+    get_heapsnapshot_dominators: {
+        description: 'Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            nodeId: {
+                name: 'nodeId',
+                type: 'number',
+                description: 'The node ID to get the dominator chain for.',
+                required: true,
+            },
+        },
+    },
+    get_heapsnapshot_edges: {
+        description: 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            nodeId: {
+                name: 'nodeId',
+                type: 'number',
+                description: 'The node ID to get outgoing edges for.',
+                required: true,
+            },
+            pageIdx: {
+                name: 'pageIdx',
+                type: 'number',
+                description: 'The page index for pagination.',
+                required: false,
+            },
+            pageSize: {
+                name: 'pageSize',
+                type: 'number',
+                description: 'The page size for pagination.',
+                required: false,
+            },
+        },
+    },
     get_heapsnapshot_retainers: {
-        description: 'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --experimentalMemory=true)',
+        description: 'Loads a memory heapsnapshot and returns retainers for a specific node ID. (requires flag: --memoryDebugging=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -330,8 +390,44 @@ export const commands = {
             },
         },
     },
+    get_heapsnapshot_retaining_paths: {
+        description: 'Loads a memory heapsnapshot and returns retaining paths for a specific node ID. This helps to understand why a node is not being garbage collected. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            nodeId: {
+                name: 'nodeId',
+                type: 'number',
+                description: 'The node ID to get retaining paths for.',
+                required: true,
+            },
+            maxDepth: {
+                name: 'maxDepth',
+                type: 'number',
+                description: 'The maximum depth to search for retaining paths.',
+                required: false,
+            },
+            maxNodes: {
+                name: 'maxNodes',
+                type: 'number',
+                description: 'The maximum number of nodes to return.',
+                required: false,
+            },
+            maxSiblings: {
+                name: 'maxSiblings',
+                type: 'number',
+                description: 'The maximum number of siblings to return.',
+                required: false,
+            },
+        },
+    },
     get_heapsnapshot_summary: {
-        description: 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --experimentalMemory=true)',
+        description: 'Loads a memory heapsnapshot and returns snapshot summary stats. (requires flag: --memoryDebugging=true)',
         category: 'Memory',
         args: {
             filePath: {
@@ -477,6 +573,12 @@ export const commands = {
                 required: false,
                 default: false,
             },
+            serviceWorkerId: {
+                name: 'serviceWorkerId',
+                type: 'string',
+                description: 'Filter messages to only return messages of the specified service worker.',
+                required: false,
+            },
         },
     },
     list_extensions: {

package/build/src/bin/chrome-devtools-mcp-cli-options.js

@@ -146,14 +146,20 @@ export const cliOptions = {
         type: 'boolean',
         describe: 'Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.',
     },
-    experimentalMemory: {
+    memoryDebugging: {
         type: 'boolean',
-        describe: 'Whether to enable experimental memory tools.',
+        describe: 'Whether to enable memory debugging tools.',
+        alias: 'experimentalMemory',
     },
     experimentalStructuredContent: {
         type: 'boolean',
         describe: 'Whether to output structured formatted content.',
     },
+    experimentalToonFormat: {
+        type: 'boolean',
+        describe: 'Whether to format structured data in text response using Token-Oriented Object Notation. Defaults to false which represents the embedded content as formatted JSON instead.',
+        hidden: true,
+    },
     experimentalIncludeAllPages: {
         type: 'boolean',
         describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
@@ -179,12 +185,22 @@ export const cliOptions = {
     },
     categoryExperimentalWebmcp: {
         type: 'boolean',
-        describe: 'Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`',
+        describe: 'Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCP,DevToolsWebMCPSupport`',
     },
     chromeArg: {
         type: 'array',
         describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
     },
+    blockedUrlPattern: {
+        type: 'array',
+        describe: 'Restricts network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.',
+        conflicts: ['allowedUrlPattern'],
+    },
+    allowedUrlPattern: {
+        type: 'array',
+        describe: 'Restricts network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.',
+        conflicts: ['blockedUrlPattern'],
+    },
     ignoreDefaultChromeArg: {
         type: 'array',
         describe: 'Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
@@ -240,6 +256,50 @@ export const cliOptions = {
         hidden: true,
         describe: 'Include watchdog PID in Clearcut request headers (for testing).',
     },
+    screenshotFormat: {
+        type: 'string',
+        description: 'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").',
+        choices: ['jpeg', 'png', 'webp'],
+    },
+    screenshotQuality: {
+        type: 'number',
+        description: 'Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.',
+        coerce: (value) => {
+            if (value === undefined) {
+                return;
+            }
+            if (!Number.isInteger(value) || value < 0 || value > 100) {
+                throw new Error(`Invalid screenshotQuality ${value}. Expected an integer between 0 and 100.`);
+            }
+            return value;
+        },
+    },
+    screenshotMaxWidth: {
+        type: 'number',
+        description: 'Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.',
+        coerce: (value) => {
+            if (value === undefined) {
+                return;
+            }
+            if (!Number.isInteger(value) || value <= 0) {
+                throw new Error(`Invalid screenshotMaxWidth ${value}. Expected a positive integer.`);
+            }
+            return value;
+        },
+    },
+    screenshotMaxHeight: {
+        type: 'number',
+        description: 'Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.',
+        coerce: (value) => {
+            if (value === undefined) {
+                return;
+            }
+            if (!Number.isInteger(value) || value <= 0) {
+                throw new Error(`Invalid screenshotMaxHeight ${value}. Expected a positive integer.`);
+            }
+            return value;
+        },
+    },
     slim: {
         type: 'boolean',
         describe: 'Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.',
@@ -259,7 +319,7 @@ export function parseArguments(version, argv = process.argv, env = process.env)
     const yargsInstance = yargs(hideBin(argv))
         .scriptName('npx chrome-devtools-mcp@latest')
         .options(cliOptions)
-        .check(args => {
+        .middleware(args => {
         // We can't set default in the options else
         // Yargs will complain
         if (!args.channel &&
@@ -272,7 +332,6 @@ export function parseArguments(version, argv = process.argv, env = process.env)
             console.error("turning off usage statistics. process.env['CI'] || process.env['CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.");
             args.usageStatistics = false;
         }
-        return true;
     })
         .example([
         [

package/build/src/bin/chrome-devtools-mcp-main.js

@@ -19,7 +19,7 @@ export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 if (process.env['CHROME_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {
     process.on('unhandledRejection', (reason, promise) => {
-        logger('Unhandled promise rejection', promise, reason);
+        logger?.('Unhandled promise rejection', promise, reason);
     });
 }
 // Shutdown on stdin EOF (stdio MCP convention — the client closes the
@@ -32,13 +32,13 @@ async function shutdown(reason) {
         return;
     }
     shuttingDown = true;
-    logger(`Shutting down (${reason})`);
+    logger?.(`Shutting down (${reason})`);
     // Backstop in case browser teardown hangs (e.g. unresponsive Chrome,
     // slow beforeunload handlers, many tabs). Exits 0 because we still
     // honored the shutdown request; the log line preserves observability.
     // Unref'd so it doesn't keep the loop alive on the clean path.
     setTimeout(() => {
-        logger('Shutdown timeout exceeded, forcing exit');
+        logger?.('Shutdown timeout exceeded, forcing exit');
         process.exit(0);
     }, 10000).unref();
     await closeBrowser();
@@ -59,13 +59,13 @@ process.on('SIGINT', () => {
 process.on('SIGHUP', () => {
     void shutdown('SIGHUP');
 });
-logger(`Starting Chrome DevTools MCP Server v${VERSION}`);
+logger?.(`Starting Chrome DevTools MCP Server v${VERSION}`);
 const { server } = await createMcpServer(args, {
     logFile,
 });
 const transport = new StdioServerTransport();
 await server.connect(transport);
-logger('Chrome DevTools MCP Server connected');
+logger?.('Chrome DevTools MCP Server connected');
 logDisclaimers(args);
 void ClearcutLogger.get()?.logDailyActiveIfNeeded();
 void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, cliOptions));

package/build/src/browser.js

@@ -41,6 +41,8 @@ export async function ensureBrowserConnected(options) {
         targetFilter: makeTargetFilter(enableExtensions),
         defaultViewport: null,
         handleDevToolsAsPage: true,
+        blocklist: options.blocklist,
+        allowlist: options.allowlist,
     };
     let autoConnect = false;
     if (options.wsEndpoint) {
@@ -94,7 +96,7 @@ export async function ensureBrowserConnected(options) {
     else {
         throw new Error('Either browserURL, wsEndpoint, channel or userDataDir must be provided');
     }
-    logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
+    logger?.('Connecting Puppeteer to ', JSON.stringify(connectOptions));
     try {
         // Assign mode before browser so a concurrent closeBrowser() never sees
         // `browser` set with `browserMode` still undefined (would fall through
@@ -108,7 +110,7 @@ export async function ensureBrowserConnected(options) {
             cause: err,
         });
     }
-    logger('Connected Puppeteer');
+    logger?.('Connected Puppeteer');
     return browser;
 }
 export function detectDisplay() {
@@ -174,6 +176,8 @@ export async function launch(options) {
             acceptInsecureCerts: options.acceptInsecureCerts,
             handleDevToolsAsPage: true,
             enableExtensions: options.enableExtensions,
+            blocklist: options.blocklist,
+            allowlist: options.allowlist,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We
@@ -227,12 +231,12 @@ export async function closeBrowser() {
     }
     if (mode === 'launched') {
         await b.close().catch(err => {
-            logger('Failed to close browser', err);
+            logger?.('Failed to close browser', err);
         });
         return;
     }
     await b.disconnect().catch(err => {
-        logger('Failed to disconnect from browser', err);
+        logger?.('Failed to disconnect from browser', err);
     });
 }
 //# sourceMappingURL=browser.js.map

package/build/src/daemon/client.js

@@ -50,14 +50,14 @@ function waitForFile(filePath, removed = false) {
 }
 export async function startDaemon(mcpArgs = [], sessionId) {
     if (isDaemonRunning(sessionId)) {
-        logger('Daemon is already running');
+        logger?.('Daemon is already running');
         return;
     }
     const pidFilePath = getPidFilePath(sessionId);
     if (fs.existsSync(pidFilePath)) {
         fs.unlinkSync(pidFilePath);
     }
-    logger('Starting daemon...', ...mcpArgs);
+    logger?.('Starting daemon...', ...mcpArgs);
     const child = spawn(process.execPath, [DAEMON_SCRIPT_PATH, ...mcpArgs], {
         detached: true,
         stdio: 'ignore',
@@ -85,26 +85,26 @@ export async function sendCommand(command, sessionId) {
         const transport = new PipeTransport(socket, socket);
         transport.onmessage = async (message) => {
             clearTimeout(timer);
-            logger('onmessage', message);
+            logger?.('onmessage', message);
             resolve(JSON.parse(message));
         };
         socket.on('error', error => {
             clearTimeout(timer);
-            logger('Socket error:', error);
+            logger?.('Socket error:', error);
             reject(error);
         });
         socket.on('close', () => {
             clearTimeout(timer);
-            logger('Socket closed:');
+            logger?.('Socket closed:');
             reject(new Error('Socket closed'));
         });
-        logger('Sending message', command);
+        logger?.('Sending message', command);
         transport.send(JSON.stringify(command));
     });
 }
 export async function stopDaemon(sessionId) {
     if (!isDaemonRunning(sessionId)) {
-        logger('Daemon is not running');
+        logger?.('Daemon is not running');
         return;
     }
     const pidFilePath = getPidFilePath(sessionId);

package/build/src/daemon/daemon.js

@@ -14,9 +14,9 @@ import { Client, PipeTransport, StdioClientTransport, } from '../third_party/ind
 import { VERSION } from '../version.js';
 import { DAEMON_CLIENT_NAME, getPidFilePath, getSocketPath, INDEX_SCRIPT_PATH, IS_WINDOWS, isDaemonRunning, } from './utils.js';
 const sessionId = process.env.CHROME_DEVTOOLS_MCP_SESSION_ID || '';
-logger(`Daemon sessionId: ${sessionId}`);
+logger?.(`Daemon sessionId: ${sessionId}`);
 if (isDaemonRunning(sessionId)) {
-    logger('Another daemon process is running.');
+    logger?.('Another daemon process is running.');
     process.exit(1);
 }
 const pidFilePath = getPidFilePath(sessionId);
@@ -80,7 +80,7 @@ finally {
         }
     }
 }
-logger(`Writing ${process.pid.toString()} to ${pidFilePath}`);
+logger?.(`Writing ${process.pid.toString()} to ${pidFilePath}`);
 const socketPath = getSocketPath(sessionId);
 const startDate = new Date();
 const mcpServerArgs = process.argv.slice(2);
@@ -173,13 +173,13 @@ async function startSocketServer() {
         server = createServer(socket => {
             const transport = new PipeTransport(socket, socket);
             transport.onmessage = async (message) => {
-                logger('onmessage', message);
+                logger?.('onmessage', message);
                 const response = await handleRequest(JSON.parse(message));
                 transport.send(JSON.stringify(response));
                 socket.end();
             };
             socket.on('error', error => {
-                logger('Socket error:', error);
+                logger?.('Socket error:', error);
             });
         });
         server.listen({
@@ -198,7 +198,7 @@ async function startSocketServer() {
             }
         });
         server.on('error', error => {
-            logger('Server error:', error);
+            logger?.('Server error:', error);
             reject(error);
         });
     });
@@ -209,13 +209,13 @@ async function cleanup() {
         await mcpClient?.close();
     }
     catch (error) {
-        logger('Error closing MCP client:', error);
+        logger?.('Error closing MCP client:', error);
     }
     try {
         await mcpTransport?.close();
     }
     catch (error) {
-        logger('Error closing MCP transport:', error);
+        logger?.('Error closing MCP transport:', error);
     }
     if (server) {
         await new Promise(resolve => {
@@ -230,7 +230,7 @@ async function cleanup() {
             // ignore errors
         }
     }
-    logger(`unlinking ${pidFilePath}`);
+    logger?.(`unlinking ${pidFilePath}`);
     if (fs.existsSync(pidFilePath)) {
         fs.unlinkSync(pidFilePath);
     }
@@ -248,14 +248,14 @@ process.on('SIGHUP', () => {
 });
 // Handle uncaught errors
 process.on('uncaughtException', error => {
-    logger('Uncaught exception:', error);
+    logger?.('Uncaught exception:', error);
 });
 process.on('unhandledRejection', error => {
-    logger('Unhandled rejection:', error);
+    logger?.('Unhandled rejection:', error);
 });
 // Start the server
 const started = startSocketServer().catch(error => {
-    logger('Failed to start daemon server:', error);
+    logger?.('Failed to start daemon server:', error);
     process.exit(1);
 });
 //# sourceMappingURL=daemon.js.map

package/build/src/daemon/utils.js

@@ -56,13 +56,13 @@ export function getPidFilePath(sessionId) {
 export function getDaemonPid(sessionId) {
     try {
         const pidFile = getPidFilePath(sessionId);
-        logger(`Daemon pid file ${pidFile} sessionId=${sessionId}`);
+        logger?.(`Daemon pid file ${pidFile} sessionId=${sessionId}`);
         if (!fs.existsSync(pidFile)) {
             return null;
         }
         const pidContent = fs.readFileSync(pidFile, 'utf-8');
         const pid = parseInt(pidContent.trim(), 10);
-        logger(`Daemon pid: ${pid}`);
+        logger?.(`Daemon pid: ${pid}`);
         if (isNaN(pid)) {
             return null;
         }

package/build/src/{DevToolsConnectionAdapter.js → devtools/DevToolsConnectionAdapter.js}

@@ -3,7 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { CDPSessionEvent } from './third_party/index.js';
+import { CDPSessionEvent } from '../third_party/index.js';
 /**
  * This class makes a puppeteer connection look like DevTools CDPConnection.
  *