chrome-devtools-mcp 0.5.0 → 0.6.0

package/README.md

@@ -7,6 +7,8 @@ control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
 (MCP) server, giving your AI coding assistant access to the full power of
 Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
 
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md)
+
 ## Key features
 
 - **Get performance insights**: Uses [Chrome
@@ -40,7 +42,7 @@ Add the following config to your MCP client:
   "mcpServers": {
     "chrome-devtools": {
       "command": "npx",
-      "args": ["chrome-devtools-mcp@latest"]
+      "args": ["-y", "chrome-devtools-mcp@latest"]
     }
   }
 }
@@ -94,6 +96,30 @@ startup_timeout_ms = 20_000
 
 </details>
 
+<details>
+  <summary>Copilot CLI</summary>
+
+Start Copilot CLI:
+
+```
+copilot
+```
+
+Start the dialog to add a new MCP server by running:
+
+```
+/mcp add
+```
+
+Configure the following fields and press `CTR-S` to save the configuration:
+
+- **Server name:** `chrome-devtools`
+- **Server Type:** `[1] Local`
+- **Command:** `npx`
+- **Arguments:** `-y, chrome-devtools-mcp@latest`
+
+</details>
+
 <details>
   <summary>Copilot / VS Code</summary>
   Follow the MCP install <a href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server">guide</a>,
@@ -109,7 +135,7 @@ startup_timeout_ms = 20_000
 
 **Click the button to install:**
 
-[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=chrome-devtools&config=eyJjb21tYW5kIjoibnB4IC15IGNocm9tZS1kZXZ0b29scy1tY3BAbGF0ZXN0In0%3D)
 
 **Or install manually:**
 
@@ -151,6 +177,14 @@ The same way chrome-devtools-mcp can be configured for JetBrains Junie in `Setti
 
 </details>
 
+<details>
+  <summary>Visual Studio</summary>
+  
+  **Click the button to install:**
+  
+  [<img src="https://img.shields.io/badge/Visual_Studio-Install-C16FDE?logo=visualstudio&logoColor=white" alt="Install in Visual Studio">](https://vs-open.link/mcp-install?%7B%22name%22%3A%22chrome-devtools%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22chrome-devtools-mcp%40latest%22%5D%7D)
+</details>
+
 ### Your first prompt
 
 Enter the following prompt in your MCP Client to check if everything is working:
@@ -166,6 +200,8 @@ Your MCP client should open the browser and record a performance trace.
 
 ## Tools
 
+If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md).
+
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
 - **Input automation** (7 tools)
@@ -236,6 +272,18 @@ The Chrome DevTools MCP server supports the following configuration option:
   Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
   - **Type:** string
 
+- **`--viewport`**
+  Initial viewport size for the Chromee instances started by the server. For example, `1280x720`
+  - **Type:** string
+
+- **`--proxyServer`**
+  Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
+  - **Type:** string
+
+- **`--acceptInsecureCerts`**
+  If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
+  - **Type:** boolean
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:

package/build/node_modules/chrome-devtools-frontend/front_end/core/host/InspectorFrontendHost.js

@@ -301,6 +301,9 @@ export class InspectorFrontendHostStub {
             devToolsFlexibleLayout: {
                 verticalDrawerEnabled: true,
             },
+            devToolsStartingStyleDebugging: {
+                enabled: false,
+            },
         };
         if ('hostConfigForTesting' in globalThis) {
             const { hostConfigForTesting } = globalThis;

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/CSSModel.js

@@ -368,6 +368,11 @@ export class CSSModel extends SDKModel {
             null;
         return new InlineStyleResult(inlineStyle, attributesStyle);
     }
+    forceStartingStyle(node, forced) {
+        void this.agent.invoke_forceStartingStyle({ nodeId: node.id, forced });
+        this.dispatchEventToListeners(Events.StartingStylesStateForced, node);
+        return true;
+    }
     forcePseudoState(node, pseudoClass, enable) {
         const forcedPseudoClasses = node.marker(PseudoStateMarker) || [];
         const hasPseudoClass = forcedPseudoClasses.includes(pseudoClass);
@@ -781,6 +786,7 @@ export var Events;
     Events["ModelWasEnabled"] = "ModelWasEnabled";
     Events["ModelDisposed"] = "ModelDisposed";
     Events["PseudoStateForced"] = "PseudoStateForced";
+    Events["StartingStylesStateForced"] = "StartingStylesStateForced";
     Events["StyleSheetAdded"] = "StyleSheetAdded";
     Events["StyleSheetChanged"] = "StyleSheetChanged";
     Events["StyleSheetRemoved"] = "StyleSheetRemoved";

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/CSSRule.js

@@ -7,6 +7,7 @@ import { CSSContainerQuery } from './CSSContainerQuery.js';
 import { CSSLayer } from './CSSLayer.js';
 import { CSSMedia } from './CSSMedia.js';
 import { CSSScope } from './CSSScope.js';
+import { CSSStartingStyle } from './CSSStartingStyle.js';
 import { CSSStyleDeclaration, Type } from './CSSStyleDeclaration.js';
 import { CSSSupports } from './CSSSupports.js';
 function styleSheetHeaderForRule(cssModel, { styleSheetId }) {
@@ -83,6 +84,7 @@ export class CSSStyleRule extends CSSRule {
     scopes;
     layers;
     ruleTypes;
+    startingStyles;
     wasUsed;
     constructor(cssModel, payload, wasUsed) {
         super(cssModel, { origin: payload.origin, style: payload.style, header: styleSheetHeaderForRule(cssModel, payload) });
@@ -95,6 +97,8 @@ export class CSSStyleRule extends CSSRule {
         this.scopes = payload.scopes ? CSSScope.parseScopesPayload(cssModel, payload.scopes) : [];
         this.supports = payload.supports ? CSSSupports.parseSupportsPayload(cssModel, payload.supports) : [];
         this.layers = payload.layers ? CSSLayer.parseLayerPayload(cssModel, payload.layers) : [];
+        this.startingStyles =
+            payload.startingStyles ? CSSStartingStyle.parseStartingStylePayload(cssModel, payload.startingStyles) : [];
         this.ruleTypes = payload.ruleTypes || [];
         this.wasUsed = wasUsed || false;
     }

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/CSSStartingStyle.js

@@ -0,0 +1,21 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as TextUtils from '../../models/text_utils/text_utils.js';
+import { CSSQuery } from './CSSQuery.js';
+export class CSSStartingStyle extends CSSQuery {
+    static parseStartingStylePayload(cssModel, payload) {
+        return payload.map(p => new CSSStartingStyle(cssModel, p));
+    }
+    constructor(cssModel, payload) {
+        super(cssModel);
+        this.reinitialize(payload);
+    }
+    reinitialize(payload) {
+        this.range = payload.range ? TextUtils.TextRange.TextRange.fromObject(payload.range) : null;
+        this.styleSheetId = payload.styleSheetId;
+    }
+    active() {
+        return true;
+    }
+}

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/DOMModel.js

@@ -88,6 +88,7 @@ export class DOMNode {
     #xmlVersion;
     #isSVGNode;
     #isScrollable;
+    #affectedByStartingStyles;
     #creationStackTrace = null;
     #pseudoElements = new Map();
     #distributedNodes = [];
@@ -148,6 +149,7 @@ export class DOMNode {
         this.#xmlVersion = payload.xmlVersion;
         this.#isSVGNode = Boolean(payload.isSVG);
         this.#isScrollable = Boolean(payload.isScrollable);
+        this.#affectedByStartingStyles = Boolean(payload.affectedByStartingStyles);
         this.#retainedNodes = retainedNodes;
         if (this.#retainedNodes?.has(this.backendNodeId())) {
             this.retained = true;
@@ -237,6 +239,9 @@ export class DOMNode {
     isScrollable() {
         return this.#isScrollable;
     }
+    affectedByStartingStyles() {
+        return this.#affectedByStartingStyles;
+    }
     isMediaNode() {
         return this.#nodeName === 'AUDIO' || this.#nodeName === 'VIDEO';
     }
@@ -279,6 +284,9 @@ export class DOMNode {
     setIsScrollable(isScrollable) {
         this.#isScrollable = isScrollable;
     }
+    setAffectedByStartingStyles(affectedByStartingStyles) {
+        this.#affectedByStartingStyles = affectedByStartingStyles;
+    }
     hasAttributes() {
         return this.#attributes.size > 0;
     }
@@ -1327,6 +1335,14 @@ export class DOMModel extends SDKModel {
         node.setIsScrollable(isScrollable);
         this.dispatchEventToListeners(Events.ScrollableFlagUpdated, { node });
     }
+    affectedByStartingStylesFlagUpdated(nodeId, affectedByStartingStyles) {
+        const node = this.nodeForId(nodeId);
+        if (!node || node.affectedByStartingStyles() === affectedByStartingStyles) {
+            return;
+        }
+        node.setAffectedByStartingStyles(affectedByStartingStyles);
+        this.dispatchEventToListeners(Events.AffectedByStartingStylesFlagUpdated, { node });
+    }
     topLayerElementsUpdated() {
         this.dispatchEventToListeners(Events.TopLayerElementsChanged);
     }
@@ -1478,6 +1494,7 @@ export var Events;
     Events["MarkersChanged"] = "MarkersChanged";
     Events["TopLayerElementsChanged"] = "TopLayerElementsChanged";
     Events["ScrollableFlagUpdated"] = "ScrollableFlagUpdated";
+    Events["AffectedByStartingStylesFlagUpdated"] = "AffectedByStartingStylesFlagUpdated";
     /* eslint-enable @typescript-eslint/naming-convention */
 })(Events || (Events = {}));
 class DOMDispatcher {
@@ -1533,7 +1550,8 @@ class DOMDispatcher {
     scrollableFlagUpdated({ nodeId, isScrollable }) {
         this.#domModel.scrollableFlagUpdated(nodeId, isScrollable);
     }
-    affectedByStartingStylesFlagUpdated(_) {
+    affectedByStartingStylesFlagUpdated({ nodeId, affectedByStartingStyles }) {
+        this.#domModel.affectedByStartingStylesFlagUpdated(nodeId, affectedByStartingStyles);
     }
 }
 let domModelUndoStackInstance = null;

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/RehydratingConnection.js

@@ -164,7 +164,11 @@ class RehydratingSessionBase {
         this.connection = connection;
     }
     sendMessageToFrontend(payload) {
-        this.connection?.postToFrontend(payload);
+        // The frontend doesn't expect CDP responses within the same synchronous event loop, so it breaks unexpectedly.
+        //  Any async boundary will do, so we use setTimeout.
+        setTimeout(() => {
+            this.connection?.postToFrontend(payload);
+        });
     }
     handleFrontendMessageAsFakeCDPAgent(data) {
         // Send default response in default session.

package/build/node_modules/chrome-devtools-frontend/front_end/core/sdk/sdk.js

@@ -33,6 +33,7 @@ import * as CSSPropertyParserMatchers from './CSSPropertyParserMatchers.js';
 import * as CSSQuery from './CSSQuery.js';
 import * as CSSRule from './CSSRule.js';
 import * as CSSScope from './CSSScope.js';
+import * as CSSStartingStyle from './CSSStartingStyle.js';
 import * as CSSStyleDeclaration from './CSSStyleDeclaration.js';
 import * as CSSStyleSheetHeader from './CSSStyleSheetHeader.js';
 import * as CSSSupports from './CSSSupports.js';
@@ -85,5 +86,5 @@ import * as Target from './Target.js';
 import * as TargetManager from './TargetManager.js';
 import * as TraceObject from './TraceObject.js';
 import * as WebAuthnModel from './WebAuthnModel.js';
-export { AccessibilityModel, AnimationModel, AutofillModel, CategorizedBreakpoint, ChildTargetManager, CompilerSourceMappingContentProvider, Connections, ConsoleModel, Cookie, CookieModel, CookieParser, CPUProfilerModel, CPUThrottlingManager, CSSContainerQuery, CSSFontFace, CSSLayer, CSSMatchedStyles, CSSMedia, CSSMetadata, CSSModel, CSSProperty, CSSPropertyParser, CSSPropertyParserMatchers, CSSQuery, CSSRule, CSSScope, CSSStyleDeclaration, CSSStyleSheetHeader, CSSSupports, DebuggerModel, DOMDebuggerModel, DOMModel, EmulationModel, EnhancedTracesParser, EventBreakpointsModel, FrameAssociated, FrameManager, HeapProfilerModel, IOModel, IsolateManager, IssuesModel, LayerTreeBase, LogModel, NetworkManager, NetworkRequest, OverlayColorGenerator, OverlayModel, OverlayPersistentHighlighter, PageLoad, PageResourceLoader, PaintProfiler, PerformanceMetricsModel, PreloadingModel, RehydratingConnection, // TODO(crbug.com/444191656): Exported for tests.
+export { AccessibilityModel, AnimationModel, AutofillModel, CategorizedBreakpoint, ChildTargetManager, CompilerSourceMappingContentProvider, Connections, ConsoleModel, Cookie, CookieModel, CookieParser, CPUProfilerModel, CPUThrottlingManager, CSSContainerQuery, CSSFontFace, CSSLayer, CSSMatchedStyles, CSSMedia, CSSMetadata, CSSModel, CSSProperty, CSSPropertyParser, CSSPropertyParserMatchers, CSSQuery, CSSRule, CSSScope, CSSStartingStyle, CSSStyleDeclaration, CSSStyleSheetHeader, CSSSupports, DebuggerModel, DOMDebuggerModel, DOMModel, EmulationModel, EnhancedTracesParser, EventBreakpointsModel, FrameAssociated, FrameManager, HeapProfilerModel, IOModel, IsolateManager, IssuesModel, LayerTreeBase, LogModel, NetworkManager, NetworkRequest, OverlayColorGenerator, OverlayModel, OverlayPersistentHighlighter, PageLoad, PageResourceLoader, PaintProfiler, PerformanceMetricsModel, PreloadingModel, RehydratingConnection, // TODO(crbug.com/444191656): Exported for tests.
 RemoteObject, Resource, ResourceTreeModel, RuntimeModel, ScreenCaptureModel, Script, SDKModel, SecurityOriginManager, ServerSentEventProtocol, ServerTiming, ServiceWorkerCacheModel, ServiceWorkerManager, SourceMap, SourceMapCache, SourceMapFunctionRanges, SourceMapManager, SourceMapScopeChainEntry, SourceMapScopesInfo, StorageBucketsModel, StorageKeyManager, Target, TargetManager, TraceObject, WebAuthnModel, };

package/build/node_modules/chrome-devtools-frontend/front_end/generated/InspectorBackendCommands.js

@@ -286,7 +286,7 @@ export function registerCommands(inspectorBackend) {
     inspectorBackend.registerType("CSS.Specificity", [{ "name": "a", "type": "number", "optional": false, "description": "The a component, which represents the number of ID selectors.", "typeRef": null }, { "name": "b", "type": "number", "optional": false, "description": "The b component, which represents the number of class selectors, attributes selectors, and pseudo-classes.", "typeRef": null }, { "name": "c", "type": "number", "optional": false, "description": "The c component, which represents the number of type selectors and pseudo-elements.", "typeRef": null }]);
     inspectorBackend.registerType("CSS.SelectorList", [{ "name": "selectors", "type": "array", "optional": false, "description": "Selectors in the list.", "typeRef": "CSS.Value" }, { "name": "text", "type": "string", "optional": false, "description": "Rule selector text.", "typeRef": null }]);
     inspectorBackend.registerType("CSS.CSSStyleSheetHeader", [{ "name": "styleSheetId", "type": "string", "optional": false, "description": "The stylesheet identifier.", "typeRef": "CSS.StyleSheetId" }, { "name": "frameId", "type": "string", "optional": false, "description": "Owner frame identifier.", "typeRef": "Page.FrameId" }, { "name": "sourceURL", "type": "string", "optional": false, "description": "Stylesheet resource URL. Empty if this is a constructed stylesheet created using new CSSStyleSheet() (but non-empty if this is a constructed stylesheet imported as a CSS module script).", "typeRef": null }, { "name": "sourceMapURL", "type": "string", "optional": true, "description": "URL of source map associated with the stylesheet (if any).", "typeRef": null }, { "name": "origin", "type": "string", "optional": false, "description": "Stylesheet origin.", "typeRef": "CSS.StyleSheetOrigin" }, { "name": "title", "type": "string", "optional": false, "description": "Stylesheet title.", "typeRef": null }, { "name": "ownerNode", "type": "number", "optional": true, "description": "The backend id for the owner node of the stylesheet.", "typeRef": "DOM.BackendNodeId" }, { "name": "disabled", "type": "boolean", "optional": false, "description": "Denotes whether the stylesheet is disabled.", "typeRef": null }, { "name": "hasSourceURL", "type": "boolean", "optional": true, "description": "Whether the sourceURL field value comes from the sourceURL comment.", "typeRef": null }, { "name": "isInline", "type": "boolean", "optional": false, "description": "Whether this stylesheet is created for STYLE tag by parser. This flag is not set for document.written STYLE tags.", "typeRef": null }, { "name": "isMutable", "type": "boolean", "optional": false, "description": "Whether this stylesheet is mutable. Inline stylesheets become mutable after they have been modified via CSSOM API. `<link>` element's stylesheets become mutable only if DevTools modifies them. Constructed stylesheets (new CSSStyleSheet()) are mutable immediately after creation.", "typeRef": null }, { "name": "isConstructed", "type": "boolean", "optional": false, "description": "True if this stylesheet is created through new CSSStyleSheet() or imported as a CSS module script.", "typeRef": null }, { "name": "startLine", "type": "number", "optional": false, "description": "Line offset of the stylesheet within the resource (zero based).", "typeRef": null }, { "name": "startColumn", "type": "number", "optional": false, "description": "Column offset of the stylesheet within the resource (zero based).", "typeRef": null }, { "name": "length", "type": "number", "optional": false, "description": "Size of the content (in characters).", "typeRef": null }, { "name": "endLine", "type": "number", "optional": false, "description": "Line offset of the end of the stylesheet within the resource (zero based).", "typeRef": null }, { "name": "endColumn", "type": "number", "optional": false, "description": "Column offset of the end of the stylesheet within the resource (zero based).", "typeRef": null }, { "name": "loadingFailed", "type": "boolean", "optional": true, "description": "If the style sheet was loaded from a network resource, this indicates when the resource failed to load", "typeRef": null }]);
-    inspectorBackend.registerType("CSS.CSSRule", [{ "name": "styleSheetId", "type": "string", "optional": true, "description": "The css style sheet identifier (absent for user agent stylesheet and user-specified stylesheet rules) this rule came from.", "typeRef": "CSS.StyleSheetId" }, { "name": "selectorList", "type": "object", "optional": false, "description": "Rule selector data.", "typeRef": "CSS.SelectorList" }, { "name": "nestingSelectors", "type": "array", "optional": true, "description": "Array of selectors from ancestor style rules, sorted by distance from the current rule.", "typeRef": "string" }, { "name": "origin", "type": "string", "optional": false, "description": "Parent stylesheet's origin.", "typeRef": "CSS.StyleSheetOrigin" }, { "name": "style", "type": "object", "optional": false, "description": "Associated style declaration.", "typeRef": "CSS.CSSStyle" }, { "name": "media", "type": "array", "optional": true, "description": "Media list array (for rules involving media queries). The array enumerates media queries starting with the innermost one, going outwards.", "typeRef": "CSS.CSSMedia" }, { "name": "containerQueries", "type": "array", "optional": true, "description": "Container query list array (for rules involving container queries). The array enumerates container queries starting with the innermost one, going outwards.", "typeRef": "CSS.CSSContainerQuery" }, { "name": "supports", "type": "array", "optional": true, "description": "@supports CSS at-rule array. The array enumerates @supports at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSSupports" }, { "name": "layers", "type": "array", "optional": true, "description": "Cascade layer array. Contains the layer hierarchy that this rule belongs to starting with the innermost layer and going outwards.", "typeRef": "CSS.CSSLayer" }, { "name": "scopes", "type": "array", "optional": true, "description": "@scope CSS at-rule array. The array enumerates @scope at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSScope" }, { "name": "ruleTypes", "type": "array", "optional": true, "description": "The array keeps the types of ancestor CSSRules from the innermost going outwards.", "typeRef": "CSS.CSSRuleType" }, { "name": "startingStyles", "type": "array", "optional": true, "description": "@starting-style CSS at-rule array. The array enumerates @starting-style at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSStartingStyle" }]);
+    inspectorBackend.registerType("CSS.CSSRule", [{ "name": "styleSheetId", "type": "string", "optional": true, "description": "The css style sheet identifier (absent for user agent stylesheet and user-specified stylesheet rules) this rule came from.", "typeRef": "CSS.StyleSheetId" }, { "name": "selectorList", "type": "object", "optional": false, "description": "Rule selector data.", "typeRef": "CSS.SelectorList" }, { "name": "nestingSelectors", "type": "array", "optional": true, "description": "Array of selectors from ancestor style rules, sorted by distance from the current rule.", "typeRef": "string" }, { "name": "origin", "type": "string", "optional": false, "description": "Parent stylesheet's origin.", "typeRef": "CSS.StyleSheetOrigin" }, { "name": "style", "type": "object", "optional": false, "description": "Associated style declaration.", "typeRef": "CSS.CSSStyle" }, { "name": "originTreeScopeNodeId", "type": "number", "optional": true, "description": "The BackendNodeId of the DOM node that constitutes the origin tree scope of this rule.", "typeRef": "DOM.BackendNodeId" }, { "name": "media", "type": "array", "optional": true, "description": "Media list array (for rules involving media queries). The array enumerates media queries starting with the innermost one, going outwards.", "typeRef": "CSS.CSSMedia" }, { "name": "containerQueries", "type": "array", "optional": true, "description": "Container query list array (for rules involving container queries). The array enumerates container queries starting with the innermost one, going outwards.", "typeRef": "CSS.CSSContainerQuery" }, { "name": "supports", "type": "array", "optional": true, "description": "@supports CSS at-rule array. The array enumerates @supports at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSSupports" }, { "name": "layers", "type": "array", "optional": true, "description": "Cascade layer array. Contains the layer hierarchy that this rule belongs to starting with the innermost layer and going outwards.", "typeRef": "CSS.CSSLayer" }, { "name": "scopes", "type": "array", "optional": true, "description": "@scope CSS at-rule array. The array enumerates @scope at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSScope" }, { "name": "ruleTypes", "type": "array", "optional": true, "description": "The array keeps the types of ancestor CSSRules from the innermost going outwards.", "typeRef": "CSS.CSSRuleType" }, { "name": "startingStyles", "type": "array", "optional": true, "description": "@starting-style CSS at-rule array. The array enumerates @starting-style at-rules starting with the innermost one, going outwards.", "typeRef": "CSS.CSSStartingStyle" }]);
     inspectorBackend.registerType("CSS.RuleUsage", [{ "name": "styleSheetId", "type": "string", "optional": false, "description": "The css style sheet identifier (absent for user agent stylesheet and user-specified stylesheet rules) this rule came from.", "typeRef": "CSS.StyleSheetId" }, { "name": "startOffset", "type": "number", "optional": false, "description": "Offset of the start of the rule (including selector) from the beginning of the stylesheet.", "typeRef": null }, { "name": "endOffset", "type": "number", "optional": false, "description": "Offset of the end of the rule body from the beginning of the stylesheet.", "typeRef": null }, { "name": "used", "type": "boolean", "optional": false, "description": "Indicates whether the rule was actually used by some element in the page.", "typeRef": null }]);
     inspectorBackend.registerType("CSS.SourceRange", [{ "name": "startLine", "type": "number", "optional": false, "description": "Start line of range.", "typeRef": null }, { "name": "startColumn", "type": "number", "optional": false, "description": "Start column of range (inclusive).", "typeRef": null }, { "name": "endLine", "type": "number", "optional": false, "description": "End line of range", "typeRef": null }, { "name": "endColumn", "type": "number", "optional": false, "description": "End column of range (exclusive).", "typeRef": null }]);
     inspectorBackend.registerType("CSS.ShorthandEntry", [{ "name": "name", "type": "string", "optional": false, "description": "Shorthand name.", "typeRef": null }, { "name": "value", "type": "string", "optional": false, "description": "Shorthand value.", "typeRef": null }, { "name": "important", "type": "boolean", "optional": true, "description": "Whether the property has \\\"!important\\\" annotation (implies `false` if absent).", "typeRef": null }]);
@@ -1221,7 +1221,8 @@ export function registerCommands(inspectorBackend) {
     inspectorBackend.registerEvent("Storage.attributionReportingTriggerRegistered", ["registration", "eventLevel", "aggregatable"]);
     inspectorBackend.registerEvent("Storage.attributionReportingReportSent", ["url", "body", "result", "netError", "netErrorName", "httpStatusCode"]);
     inspectorBackend.registerEvent("Storage.attributionReportingVerboseDebugReportSent", ["url", "body", "netError", "netErrorName", "httpStatusCode"]);
-    inspectorBackend.registerCommand("Storage.getStorageKeyForFrame", [{ "name": "frameId", "type": "string", "optional": false, "description": "", "typeRef": "Page.FrameId" }], ["storageKey"], "Returns a storage key given a frame id.");
+    inspectorBackend.registerCommand("Storage.getStorageKeyForFrame", [{ "name": "frameId", "type": "string", "optional": false, "description": "", "typeRef": "Page.FrameId" }], ["storageKey"], "Returns a storage key given a frame id. Deprecated. Please use Storage.getStorageKey instead.");
+    inspectorBackend.registerCommand("Storage.getStorageKey", [{ "name": "frameId", "type": "string", "optional": true, "description": "", "typeRef": "Page.FrameId" }], ["storageKey"], "Returns storage key for the given frame. If no frame ID is provided, the storage key of the target executing this command is returned.");
     inspectorBackend.registerCommand("Storage.clearDataForOrigin", [{ "name": "origin", "type": "string", "optional": false, "description": "Security origin.", "typeRef": null }, { "name": "storageTypes", "type": "string", "optional": false, "description": "Comma separated list of StorageType to clear.", "typeRef": null }], [], "Clears storage for origin.");
     inspectorBackend.registerCommand("Storage.clearDataForStorageKey", [{ "name": "storageKey", "type": "string", "optional": false, "description": "Storage key.", "typeRef": null }, { "name": "storageTypes", "type": "string", "optional": false, "description": "Comma separated list of StorageType to clear.", "typeRef": null }], [], "Clears storage for storage key.");
     inspectorBackend.registerCommand("Storage.getCookies", [{ "name": "browserContextId", "type": "string", "optional": true, "description": "Browser context to use when called on the browser endpoint.", "typeRef": "Browser.BrowserContextID" }], ["cookies"], "Returns all browser cookies.");

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/handlers/ScriptsHandler.js

@@ -17,7 +17,7 @@ export function handleEvent(event) {
     const getOrMakeScript = (isolate, scriptIdAsNumber) => {
         const scriptId = String(scriptIdAsNumber);
         const key = `${isolate}.${scriptId}`;
-        return Platform.MapUtilities.getWithDefault(scriptById, key, () => ({ isolate, scriptId, frame: '', ts: 0 }));
+        return Platform.MapUtilities.getWithDefault(scriptById, key, () => ({ isolate, scriptId, frame: '', ts: event.ts }));
     };
     if (Types.Events.isRundownScriptCompiled(event) && event.args.data) {
         const { isolate, scriptId, frame } = event.args.data;
@@ -30,6 +30,7 @@ export function handleEvent(event) {
         const { isolate, scriptId, url, sourceUrl, sourceMapUrl, sourceMapUrlElided } = event.args.data;
         const script = getOrMakeScript(isolate, scriptId);
         script.url = url;
+        script.ts = event.ts;
         if (sourceUrl) {
             script.sourceUrl = sourceUrl;
         }

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/insights/LegacyJavaScript.js

@@ -48,7 +48,8 @@ export function generateInsight(data, context) {
         if (script.url?.startsWith('chrome-extension://')) {
             return false;
         }
-        return Helpers.Timing.timestampIsInBounds(context.bounds, script.ts);
+        return Helpers.Timing.timestampIsInBounds(context.bounds, script.ts) ||
+            (script.request && Helpers.Timing.eventIsInBounds(script.request, context.bounds));
     });
     const legacyJavaScriptResults = new Map();
     const wastedBytesByRequestId = new Map();

package/build/src/McpContext.js

@@ -223,7 +223,9 @@ export class McpContext {
      */
     async createTextSnapshot() {
         const page = this.getSelectedPage();
-        const rootNode = await page.accessibility.snapshot();
+        const rootNode = await page.accessibility.snapshot({
+            includeIframes: true,
+        });
         if (!rootNode) {
             return;
         }
@@ -256,8 +258,13 @@ export class McpContext {
     async saveTemporaryFile(data, mimeType) {
         try {
             const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
-            const filename = path.join(dir, mimeType == 'image/png' ? `screenshot.png` : 'screenshot.jpg');
-            await fs.writeFile(path.join(dir, `screenshot.png`), data);
+            const ext = mimeType === 'image/png'
+                ? 'png'
+                : mimeType === 'image/jpeg'
+                    ? 'jpg'
+                    : 'webp';
+            const filename = path.join(dir, `screenshot.${ext}`);
+            await fs.writeFile(filename, data);
             return { filename };
         }
         catch (err) {

package/build/src/McpResponse.js

@@ -96,7 +96,7 @@ export class McpResponse {
         if (networkConditions) {
             response.push(`## Network emulation`);
             response.push(`Emulating: ${networkConditions}`);
-            response.push(`Navigation timeout set to ${context.getNavigationTimeout()} ms`);
+            response.push(`Default navigation timeout set to ${context.getNavigationTimeout()} ms`);
         }
         const cpuThrottlingRate = context.getCpuThrottlingRate();
         if (cpuThrottlingRate > 1) {

package/build/src/PageCollector.js

@@ -6,6 +6,11 @@
 export class PageCollector {
     #browser;
     #initializer;
+    /**
+     * The Array in this map should only be set once
+     * As we use the reference to it.
+     * Use methods that manipulate the array in place.
+     */
     storage = new WeakMap();
     constructor(browser, initializer) {
         this.#browser = browser;
@@ -31,6 +36,8 @@ export class PageCollector {
         if (this.storage.has(page)) {
             return;
         }
+        const stored = [];
+        this.storage.set(page, stored);
         page.on('framenavigated', frame => {
             // Only reset the storage on main frame navigation
             if (frame !== page.mainFrame()) {
@@ -39,15 +46,15 @@ export class PageCollector {
             this.cleanup(page);
         });
         this.#initializer(page, value => {
-            const stored = this.storage.get(page) ?? [];
             stored.push(value);
-            this.storage.set(page, stored);
         });
     }
     cleanup(page) {
-        const collection = this.storage.get(page) ?? [];
-        // Keep the reference alive
-        collection.length = 0;
+        const collection = this.storage.get(page);
+        if (collection) {
+            // Keep the reference alive
+            collection.length = 0;
+        }
     }
     getData(page) {
         return this.storage.get(page) ?? [];
@@ -56,6 +63,9 @@ export class PageCollector {
 export class NetworkCollector extends PageCollector {
     cleanup(page) {
         const requests = this.storage.get(page) ?? [];
+        if (!requests) {
+            return;
+        }
         const lastRequestIdx = requests.findLastIndex(request => {
             return request.frame() === page.mainFrame()
                 ? request.isNavigationRequest()
@@ -63,6 +73,7 @@ export class NetworkCollector extends PageCollector {
         });
         // Keep all requests since the last navigation request including that
         // navigation request itself.
-        this.storage.set(page, requests.slice(Math.max(lastRequestIdx, 0)));
+        // Keep the reference
+        requests.splice(0, Math.max(lastRequestIdx, 0));
     }
 }

package/build/src/browser.js

@@ -30,7 +30,7 @@ const connectOptions = {
     // We do not expect any single CDP command to take more than 10sec.
     protocolTimeout: 10_000,
 };
-async function ensureBrowserConnected(browserURL) {
+export async function ensureBrowserConnected(browserURL) {
     if (browser?.connected) {
         return browser;
     }
@@ -53,7 +53,10 @@ export async function launch(options) {
             recursive: true,
         });
     }
-    const args = ['--hide-crash-restore-bubble'];
+    const args = [
+        ...(options.args ?? []),
+        '--hide-crash-restore-bubble',
+    ];
     if (customDevTools) {
         args.push(`--custom-devtools-frontend=file://${customDevTools}`);
     }
@@ -74,6 +77,7 @@ export async function launch(options) {
             pipe: true,
             headless,
             args,
+            acceptInsecureCerts: options.acceptInsecureCerts,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We
@@ -81,6 +85,14 @@ export async function launch(options) {
             browser.process()?.stderr?.pipe(options.logFile);
             browser.process()?.stdout?.pipe(options.logFile);
         }
+        if (options.viewport) {
+            const [page] = await browser.pages();
+            // @ts-expect-error internal API for now.
+            await page?.resize({
+                contentWidth: options.viewport.width,
+                contentHeight: options.viewport.height,
+            });
+        }
         return browser;
     }
     catch (error) {
@@ -95,16 +107,10 @@ export async function launch(options) {
         throw error;
     }
 }
-async function ensureBrowserLaunched(options) {
+export async function ensureBrowserLaunched(options) {
     if (browser?.connected) {
         return browser;
     }
     browser = await launch(options);
     return browser;
 }
-export async function resolveBrowser(options) {
-    const browser = options.browserUrl
-        ? await ensureBrowserConnected(options.browserUrl)
-        : await ensureBrowserLaunched(options);
-    return browser;
-}

package/build/src/cli.js

@@ -48,6 +48,31 @@ export const cliOptions = {
         type: 'string',
         describe: 'Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.',
     },
+    viewport: {
+        type: 'string',
+        describe: 'Initial viewport size for the Chromee instances started by the server. For example, `1280x720`',
+        coerce: (arg) => {
+            if (arg === undefined) {
+                return;
+            }
+            const [width, height] = arg.split('x').map(Number);
+            if (!width || !height || Number.isNaN(width) || Number.isNaN(height)) {
+                throw new Error('Invalid viewport. Expected format is `1280x720`.');
+            }
+            return {
+                width,
+                height,
+            };
+        },
+    },
+    proxyServer: {
+        type: 'string',
+        description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
+    },
+    acceptInsecureCerts: {
+        type: 'boolean',
+        description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))
@@ -72,6 +97,10 @@ export function parseArguments(version, argv = process.argv) {
         ['$0 --channel stable', 'Use stable Chrome installed on this system'],
         ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
         ['$0 --help', 'Print CLI options'],
+        [
+            '$0 --viewport 1280x720',
+            'Launch Chrome with the initial viewport size of 1280x720px',
+        ],
     ]);
     return yargsInstance
         .wrap(Math.min(120, yargsInstance.terminalWidth()))

package/build/src/index.js

@@ -6,12 +6,16 @@
  */
 import { version } from 'node:process';
 const [major, minor] = version.substring(1).split('.').map(Number);
+if (major === 20 && minor < 19) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
 if (major === 22 && minor < 12) {
     console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 LTS or a newer LTS.`);
     process.exit(1);
 }
 if (major < 20) {
-    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20 LTS or a newer LTS.`);
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
     process.exit(1);
 }
 await import('./main.js');

package/build/src/logger.js

@@ -13,12 +13,12 @@ const namespacesToEnable = [
 export function saveLogsToFile(fileName) {
     // Enable overrides everything so we need to add them
     debug.enable(namespacesToEnable.join(','));
-    const logFile = fs.createWriteStream(fileName, { flags: 'a' });
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
     debug.log = function (...chunks) {
         logFile.write(`${chunks.join(' ')}\n`);
     };
     logFile.on('error', function (error) {
-        console.log(`Error when opening/writing to log file: ${error.message}`);
+        console.error(`Error when opening/writing to log file: ${error.message}`);
         logFile.end();
         process.exit(1);
     });

package/build/src/main.js

@@ -10,7 +10,7 @@ import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { resolveBrowser } from './browser.js';
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
 import { parseArguments } from './cli.js';
 import { logger, saveLogsToFile } from './logger.js';
 import { McpContext } from './McpContext.js';
@@ -54,15 +54,23 @@ server.server.setRequestHandler(SetLevelRequestSchema, () => {
 });
 let context;
 async function getContext() {
-    const browser = await resolveBrowser({
-        browserUrl: args.browserUrl,
-        headless: args.headless,
-        executablePath: args.executablePath,
-        customDevTools: args.customDevtools,
-        channel: args.channel,
-        isolated: args.isolated,
-        logFile,
-    });
+    const extraArgs = [];
+    if (args.proxyServer) {
+        extraArgs.push(`--proxy-server=${args.proxyServer}`);
+    }
+    const browser = args.browserUrl
+        ? await ensureBrowserConnected(args.browserUrl)
+        : await ensureBrowserLaunched({
+            headless: args.headless,
+            executablePath: args.executablePath,
+            customDevTools: args.customDevtools,
+            channel: args.channel,
+            isolated: args.isolated,
+            logFile,
+            viewport: args.viewport,
+            args: extraArgs,
+            acceptInsecureCerts: args.acceptInsecureCerts,
+        });
     if (context?.browser !== browser) {
         context = await McpContext.from(browser, logger);
     }

package/build/src/tools/ToolDefinition.js

@@ -3,7 +3,18 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import z from 'zod';
 export function defineTool(definition) {
     return definition;
 }
 export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';
+export const timeoutSchema = {
+    timeout: z
+        .number()
+        .int()
+        .optional()
+        .describe(`Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`)
+        .transform(value => {
+        return value && value <= 0 ? undefined : value;
+    }),
+};

package/build/src/tools/input.js

@@ -180,7 +180,7 @@ export const uploadFile = defineTool({
                 // a type=file element. In this case, we want to default to
                 // Page.waitForFileChooser() and upload the file this way.
                 try {
-                    const page = await context.getSelectedPage();
+                    const page = context.getSelectedPage();
                     const [fileChooser] = await Promise.all([
                         page.waitForFileChooser({ timeout: 3000 }),
                         handle.asLocator().click(),

package/build/src/tools/network.js

@@ -72,6 +72,5 @@ export const getNetworkRequest = defineTool({
     },
     handler: async (request, response, _context) => {
         response.attachNetworkRequest(request.params.url);
-        response.setIncludeNetworkRequests(true);
     },
 });

package/build/src/tools/pages.js

@@ -6,7 +6,7 @@
 import z from 'zod';
 import { logger } from '../logger.js';
 import { ToolCategories } from './categories.js';
-import { CLOSE_PAGE_ERROR, defineTool } from './ToolDefinition.js';
+import { CLOSE_PAGE_ERROR, defineTool, timeoutSchema } from './ToolDefinition.js';
 export const listPages = defineTool({
     name: 'list_pages',
     description: `Get a list of pages open in the browser.`,
@@ -74,11 +74,14 @@ export const newPage = defineTool({
     },
     schema: {
         url: z.string().describe('URL to load in a new page.'),
+        ...timeoutSchema,
     },
     handler: async (request, response, context) => {
         const page = await context.newPage();
         await context.waitForEventsAfterAction(async () => {
-            await page.goto(request.params.url);
+            await page.goto(request.params.url, {
+                timeout: request.params.timeout,
+            });
         });
         response.setIncludePages(true);
     },
@@ -92,11 +95,14 @@ export const navigatePage = defineTool({
     },
     schema: {
         url: z.string().describe('URL to navigate the page to'),
+        ...timeoutSchema,
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
         await context.waitForEventsAfterAction(async () => {
-            await page.goto(request.params.url);
+            await page.goto(request.params.url, {
+                timeout: request.params.timeout,
+            });
         });
         response.setIncludePages(true);
     },
@@ -112,15 +118,19 @@ export const navigatePageHistory = defineTool({
         navigate: z
             .enum(['back', 'forward'])
             .describe('Whether to navigate back or navigate forward in the selected pages history'),
+        ...timeoutSchema,
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
+        const options = {
+            timeout: request.params.timeout,
+        };
         try {
             if (request.params.navigate === 'back') {
-                await page.goBack();
+                await page.goBack(options);
             }
             else {
-                await page.goForward();
+                await page.goForward(options);
             }
         }
         catch {

package/build/src/tools/screenshot.js

@@ -3,6 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { writeFile } from 'node:fs/promises';
 import z from 'zod';
 import { ToolCategories } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
@@ -15,7 +16,7 @@ export const screenshot = defineTool({
     },
     schema: {
         format: z
-            .enum(['png', 'jpeg'])
+            .enum(['png', 'jpeg', 'webp'])
             .default('png')
             .describe('Type of format to save the screenshot as. Default is "png"'),
         quality: z
@@ -23,7 +24,7 @@ export const screenshot = defineTool({
             .min(0)
             .max(100)
             .optional()
-            .describe('Compression quality for JPEG format (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.'),
+            .describe('Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.'),
         uid: z
             .string()
             .optional()
@@ -32,6 +33,10 @@ export const screenshot = defineTool({
             .boolean()
             .optional()
             .describe('If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.'),
+        filePath: z
+            .string()
+            .optional()
+            .describe('The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.'),
     },
     handler: async (request, response, context) => {
         if (request.params.uid && request.params.fullPage) {
@@ -59,7 +64,11 @@ export const screenshot = defineTool({
         else {
             response.appendResponseLine("Took a screenshot of the current page's viewport.");
         }
-        if (screenshot.length >= 2_000_000) {
+        if (request.params.filePath) {
+            await writeFile(request.params.filePath, screenshot);
+            response.appendResponseLine(`Saved screenshot to ${request.params.filePath}.`);
+        }
+        else if (screenshot.length >= 2_000_000) {
             const { filename } = await context.saveTemporaryFile(screenshot, `image/${request.params.format}`);
             response.appendResponseLine(`Saved screenshot to ${filename}.`);
         }

package/build/src/tools/snapshot.js

@@ -6,7 +6,7 @@
 import { Locator } from 'puppeteer-core';
 import z from 'zod';
 import { ToolCategories } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { defineTool, timeoutSchema } from './ToolDefinition.js';
 export const takeSnapshot = defineTool({
     name: 'take_snapshot',
     description: `Take a text snapshot of the currently selected page. The snapshot lists page elements along with a unique
@@ -29,13 +29,19 @@ export const waitFor = defineTool({
     },
     schema: {
         text: z.string().describe('Text to appear on the page'),
+        ...timeoutSchema,
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
-        await Locator.race([
-            page.locator(`aria/${request.params.text}`),
-            page.locator(`text/${request.params.text}`),
-        ]).wait();
+        const frames = page.frames();
+        const locator = Locator.race(frames.flatMap(frame => [
+            frame.locator(`aria/${request.params.text}`),
+            frame.locator(`text/${request.params.text}`),
+        ]));
+        if (request.params.timeout) {
+            locator.setTimeout(request.params.timeout);
+        }
+        await locator.wait();
         response.appendResponseLine(`Element with text "${request.params.text}" found.`);
         response.setIncludeSnapshot(true);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -53,7 +53,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1520535",
+    "chrome-devtools-frontend": "1.0.1521880",
     "eslint": "^9.35.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
@@ -65,6 +65,6 @@
     "typescript-eslint": "^8.43.0"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^20.19.0 || ^22.12.0 || >=23"
   }
 }