chrome-devtools-mcp 1.1.1 → 1.3.0

package/README.md

@@ -514,11 +514,15 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
   - [`screencast_start`](docs/tool-reference.md#screencast_start)
   - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
-- **Memory** (5 tools)
+- **Memory** (9 tools)
   - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
+  - [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
   - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
   - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
+  - [`get_heapsnapshot_dominators`](docs/tool-reference.md#get_heapsnapshot_dominators)
+  - [`get_heapsnapshot_edges`](docs/tool-reference.md#get_heapsnapshot_edges)
   - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
+  - [`get_heapsnapshot_retaining_paths`](docs/tool-reference.md#get_heapsnapshot_retaining_paths)
   - [`get_heapsnapshot_summary`](docs/tool-reference.md#get_heapsnapshot_summary)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
@@ -608,8 +612,8 @@ The Chrome DevTools MCP server supports the following configuration option:
   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.
   - **Type:** boolean
 
-- **`--experimentalMemory`/ `--experimental-memory`**
-  Whether to enable experimental memory tools.
+- **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`**
+  Whether to enable memory debugging tools.
   - **Type:** boolean
 
 - **`--experimentalStructuredContent`/ `--experimental-structured-content`**
@@ -629,13 +633,21 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** string
 
 - **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
-  Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
+  Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCP,DevToolsWebMCPSupport`
   - **Type:** boolean
 
 - **`--chromeArg`/ `--chrome-arg`**
   Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
   - **Type:** array
 
+- **`--blockedUrlPattern`/ `--blocked-url-pattern`**
+  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.
+  - **Type:** array
+
+- **`--allowedUrlPattern`/ `--allowed-url-pattern`**
+  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.
+  - **Type:** array
+
 - **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
   Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
   - **Type:** array
@@ -675,6 +687,23 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--screenshotFormat`/ `--screenshot-format`**
+  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").
+  - **Type:** string
+  - **Choices:** `jpeg`, `png`, `webp`
+
+- **`--screenshotQuality`/ `--screenshot-quality`**
+  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.
+  - **Type:** number
+
+- **`--screenshotMaxWidth`/ `--screenshot-max-width`**
+  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.
+  - **Type:** number
+
+- **`--screenshotMaxHeight`/ `--screenshot-max-height`**
+  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.
+  - **Type:** number
+
 - **`--slim`**
   Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.
   - **Type:** boolean

package/build/src/HeapSnapshotManager.js

@@ -5,7 +5,6 @@
  */
 import fsSync from 'node:fs';
 import path from 'node:path';
-import { isNodeLike } from './formatters/HeapSnapshotFormatter.js';
 import { DevTools } from './third_party/index.js';
 import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
 export class HeapSnapshotManager {
@@ -67,28 +66,38 @@ export class HeapSnapshotManager {
         const provider = snapshot.createNodesProviderForClass(className, filter);
         return await provider.serializeItemsRange(0, Infinity);
     }
-    async findNodeIndexById(filePath, nodeId) {
+    async getRetainers(filePath, nodeId) {
         const snapshot = await this.getSnapshot(filePath);
-        const aggregates = await this.getAggregates(filePath);
-        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
-        for (const classKey of Object.keys(aggregates)) {
-            const provider = snapshot.createNodesProviderForClass(classKey, filter);
-            const range = await provider.serializeItemsRange(0, Infinity);
-            for (const item of range.items) {
-                if (isNodeLike(item) && item.id === nodeId) {
-                    return item.nodeIndex;
-                }
-            }
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
         }
-        return undefined;
+        const provider = snapshot.createRetainingEdgesProvider(nodeIndex);
+        return await provider.serializeItemsRange(0, Infinity);
     }
-    async getRetainers(filePath, nodeId) {
-        const nodeIndex = await this.findNodeIndexById(filePath, nodeId);
+    async getRetainingPaths(filePath, nodeId, maxDepth, maxNodes, maxSiblings) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        return await snapshot.getRetainingPaths(nodeIndex, maxDepth, maxNodes, maxSiblings);
+    }
+    async getDominatorsOf(filePath, nodeId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
         if (nodeIndex === undefined) {
             throw new Error(`Node with ID ${nodeId} not found`);
         }
+        return await snapshot.getDominatorsOf(nodeIndex);
+    }
+    async getEdges(filePath, nodeId) {
         const snapshot = await this.getSnapshot(filePath);
-        const provider = snapshot.createRetainingEdgesProvider(nodeIndex);
+        const nodeIndex = await snapshot.nodeIndexForId(nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        const provider = snapshot.createEdgesProvider(nodeIndex);
         return await provider.serializeItemsRange(0, Infinity);
     }
     #getCachedSnapshot(filePath) {
@@ -122,13 +131,18 @@ export class HeapSnapshotManager {
         const snapshot = await snapshotPromise;
         return { snapshot, worker: workerProxy };
     }
+    hasSnapshots() {
+        return this.#snapshots.size > 0;
+    }
     dispose(filePath) {
         const absolutePath = path.resolve(filePath);
         const cached = this.#snapshots.get(absolutePath);
         if (cached) {
             cached.worker.dispose();
             this.#snapshots.delete(absolutePath);
+            return true;
         }
+        return false;
     }
 }
 //# sourceMappingURL=HeapSnapshotManager.js.map

package/build/src/McpContext.js

@@ -8,10 +8,11 @@ import fsPromises from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { UniverseManager } from './DevtoolsUtils.js';
+import { overrideDevToolsGlobals, UniverseManager, } from './devtools/DevtoolsUtils.js';
 import { HeapSnapshotManager } from './HeapSnapshotManager.js';
 import { McpPage } from './McpPage.js';
 import { NetworkCollector, ConsoleCollector, } from './PageCollector.js';
+import { ServiceWorkerConsoleCollector } from './ServiceWorkerCollector.js';
 import { Locator, PredefinedNetworkConditions, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
@@ -33,6 +34,7 @@ export class McpContext {
     #networkCollector;
     #consoleCollector;
     #devtoolsUniverseManager;
+    #serviceWorkerConsoleCollector;
     #isRunningTrace = false;
     #screenRecorderData = null;
     #nextPageId = 1;
@@ -45,6 +47,11 @@ export class McpContext {
     #heapSnapshotManager = new HeapSnapshotManager();
     #roots = undefined;
     constructor(browser, logger, options, locatorClass) {
+        overrideDevToolsGlobals({
+            loadResource: (url) => {
+                return this.loadResource(url);
+            },
+        });
         this.browser = browser;
         this.logger = logger;
         this.#locatorClass = locatorClass;
@@ -63,19 +70,22 @@ export class McpContext {
                 },
             };
         });
+        this.#serviceWorkerConsoleCollector = new ServiceWorkerConsoleCollector(this.browser);
         this.#devtoolsUniverseManager = new UniverseManager(this.browser);
     }
     async #init() {
         const pages = await this.createPagesSnapshot();
-        await this.createExtensionServiceWorkersSnapshot();
+        const workers = await this.createExtensionServiceWorkersSnapshot();
         await this.#networkCollector.init(pages);
         await this.#consoleCollector.init(pages);
         await this.#devtoolsUniverseManager.init(pages);
+        await this.#serviceWorkerConsoleCollector.init(workers);
     }
     dispose() {
         this.#networkCollector.dispose();
         this.#consoleCollector.dispose();
         this.#devtoolsUniverseManager.dispose();
+        this.#serviceWorkerConsoleCollector.dispose();
         for (const mcpPage of this.#mcpPages.values()) {
             mcpPage.dispose();
         }
@@ -148,7 +158,7 @@ export class McpContext {
     }
     resolveCdpRequestId(page, cdpRequestId) {
         if (!cdpRequestId) {
-            this.logger('no network request');
+            this.logger?.('no network request');
             return;
         }
         const request = this.#networkCollector.find(page.pptrPage, request => {
@@ -156,7 +166,7 @@ export class McpContext {
             return request.id === cdpRequestId;
         });
         if (!request) {
-            this.logger('no network request for ' + cdpRequestId);
+            this.logger?.('no network request for ' + cdpRequestId);
             return;
         }
         return this.#networkCollector.getIdForResource(request);
@@ -217,7 +227,13 @@ export class McpContext {
         const page = targetPage ?? this.getSelectedPptrPage();
         const mcpPage = this.#getMcpPage(page);
         const newSettings = { ...mcpPage.emulationSettings };
-        if (!options.networkConditions) {
+        // Skip network emulation if blocklist/allowlist is configured, as it conflicts with blocking rules in Puppeteer.
+        if (this.#options.hasNetworkBlockOrAllowlist) {
+            if (options.networkConditions !== undefined) {
+                throw new Error('Network throttling is not supported when network blocking (allowlist/blocklist) is configured.');
+            }
+        }
+        else if (!options.networkConditions) {
             await page.emulateNetworkConditions(null);
             delete newSettings.networkConditions;
         }
@@ -412,6 +428,9 @@ export class McpContext {
         });
         return this.#extensionServiceWorkers;
     }
+    getServiceWorkerConsoleData(extensionId) {
+        return this.#serviceWorkerConsoleCollector.getData(extensionId);
+    }
     async createPagesSnapshot() {
         const { pages: allPages, isolatedContextNames } = await this.#getAllPages();
         for (const page of allPages) {
@@ -421,7 +440,7 @@ export class McpContext {
                 this.#mcpPages.set(page, mcpPage);
                 // We emulate a focused page for all pages to support multi-agent workflows.
                 void page.emulateFocusedPage(true).catch(error => {
-                    this.logger('Error turning on focused page emulation', error);
+                    this.logger?.('Error turning on focused page emulation', error);
                 });
             }
             mcpPage.isolatedContextName = isolatedContextNames.get(page);
@@ -467,7 +486,7 @@ export class McpContext {
                         this.#extensionPages.set(target, page);
                     }
                     catch (e) {
-                        this.logger('Failed to get page for extension target', e);
+                        this.logger?.('Failed to get page for extension target', e);
                     }
                 }
             }
@@ -502,7 +521,7 @@ export class McpContext {
         return { pages: allPages, isolatedContextNames };
     }
     async detectOpenDevToolsWindows() {
-        this.logger('Detecting open DevTools windows');
+        this.logger?.('Detecting open DevTools windows');
         const { pages } = await this.#getAllPages();
         await Promise.all(pages.map(async (page) => {
             const mcpPage = this.#mcpPages.get(page);
@@ -557,7 +576,7 @@ export class McpContext {
             return { filename: filePath };
         }
         catch (err) {
-            this.logger(err);
+            this.logger?.(err);
             throw new Error('Could not save a file', { cause: err });
         }
     }
@@ -639,5 +658,40 @@ export class McpContext {
     async getHeapSnapshotRetainers(filePath, nodeId) {
         return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);
     }
+    async closeHeapSnapshot(filePath) {
+        return this.#heapSnapshotManager.dispose(filePath);
+    }
+    hasHeapSnapshots() {
+        return this.#heapSnapshotManager.hasSnapshots();
+    }
+    async getHeapSnapshotRetainingPaths(filePath, nodeId, maxDepth, maxNodes, maxSiblings) {
+        return await this.#heapSnapshotManager.getRetainingPaths(filePath, nodeId, maxDepth, maxNodes, maxSiblings);
+    }
+    async getHeapSnapshotDominators(filePath, nodeId) {
+        return await this.#heapSnapshotManager.getDominatorsOf(filePath, nodeId);
+    }
+    async loadResource(path) {
+        const url = new URL(path);
+        switch (url.protocol) {
+            case 'https:':
+            case 'http:': {
+                // TODO: Verify allow/block list
+                const response = await fetch(url);
+                if (!response.ok) {
+                    throw new Error(`Failed to load resource: ${url}`);
+                }
+                return response.text();
+            }
+            case 'file:': {
+                await this.validatePath(fileURLToPath(url));
+                return await fsPromises.readFile(url, 'utf-8');
+            }
+            default:
+                throw new Error(`Unsupported protocol for: ${url}`);
+        }
+    }
+    async getHeapSnapshotEdges(filePath, nodeId) {
+        return await this.#heapSnapshotManager.getEdges(filePath, nodeId);
+    }
 }
 //# sourceMappingURL=McpContext.js.map

package/build/src/McpPage.js

@@ -30,7 +30,7 @@ export class McpPage {
     // Dialog
     #dialog;
     #dialogHandler;
-    thirdPartyDeveloperTools;
+    thirdPartyDeveloperTools = [];
     constructor(page, id) {
         this.pptrPage = page;
         this.id = id;
@@ -194,18 +194,18 @@ export class McpPage {
             for (const handle of oldHandles) {
                 await handle
                     .dispose()
-                    .catch(e => logger('Failed to dispose old handle', e));
+                    .catch(e => logger?.('Failed to dispose old handle', e));
             }
         }
         const cdpElementIds = await Promise.all(elementHandles.map(async (elementHandle, index) => {
             const backendNodeId = await elementHandle.backendNodeId();
             if (!backendNodeId) {
-                logger(`No backendNodeId for stashed DOM element with index ${index}`);
+                logger?.(`No backendNodeId for stashed DOM element with index ${index}`);
                 return `stashed-${index}`;
             }
             const cdpElementId = this.resolveCdpElementId(backendNodeId);
             if (!cdpElementId) {
-                logger(`Could not get cdpElementId for backend node ${backendNodeId}`);
+                logger?.(`Could not get cdpElementId for backend node ${backendNodeId}`);
                 return `stashed-${index}`;
             }
             return cdpElementId;
@@ -263,12 +263,12 @@ export class McpPage {
     }
     resolveCdpElementId(cdpBackendNodeId) {
         if (!cdpBackendNodeId) {
-            logger('no cdpBackendNodeId');
+            logger?.('no cdpBackendNodeId');
             return;
         }
         const snapshot = this.textSnapshot;
         if (!snapshot) {
-            logger('no text snapshot');
+            logger?.('no text snapshot');
             return;
         }
         // TODO: index by backendNodeId instead.
@@ -286,10 +286,10 @@ export class McpPage {
     }
     async getDevToolsData() {
         try {
-            logger('Getting DevTools UI data');
+            logger?.('Getting DevTools UI data');
             const devtoolsPage = this.devToolsPage;
             if (!devtoolsPage) {
-                logger('No DevTools page detected');
+                logger?.('No DevTools page detected');
                 return {};
             }
             const { cdpRequestId, cdpBackendNodeId } = await devtoolsPage.evaluate(async () => {
@@ -307,7 +307,7 @@ export class McpPage {
             return { cdpBackendNodeId, cdpRequestId };
         }
         catch (err) {
-            logger('error getting devtools data', err);
+            logger?.('error getting devtools data', err);
         }
         return {};
     }