Merge branch 'main' into patch-1

sebastianbenz · web-flow · commit 80ae1942eb6a · 2025-09-29T17:45:55.000+02:00
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -20,7 +20,7 @@ jobs:
           - windows-latest
           - macos-latest
         node:
-          - 22.12.0
+          - 20
           - 22
           - 23
           - 24
@@ -34,19 +34,34 @@ jobs:
         uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
         with:
           cache: npm
-          node-version: ${{ matrix.node }}
+          node-version: 22 # build works only with 22+.
 
       - name: Install dependencies
         shell: bash
         run: npm ci
 
+      - name: Build
+        run: npm run build
+
+      - name: Set up Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          cache: npm
+          node-version: ${{ matrix.node }}
+
       - name: Disable AppArmor
         if: ${{ matrix.os == 'ubuntu-latest' }}
         shell: bash
         run: echo 0 | sudo tee /proc/sys/kernel/apparmor_restrict_unprivileged_userns
 
+      - name: Run tests (node20)
+        if: ${{ matrix.node == '20' }}
+        shell: bash
+        run: npm run test:node20
+
       - name: Run tests
         shell: bash
+        if: ${{ matrix.node != '20' }}
         run: npm run test
 
   # Gating job for branch protection.
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.1"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.5.1](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.5.0...chrome-devtools-mcp-v0.5.1) (2025-09-29)
+
+
+### Bug Fixes
+
+* update package.json engines to reflect node20 support ([#210](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/210)) ([b31e647](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/b31e64713e0524f28cbf760fad27b25829ec419d))
+
+## [0.5.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.4.0...chrome-devtools-mcp-v0.5.0) (2025-09-29)
+
+
+### Features
+
+* **screenshot:** add JPEG quality parameter support ([#184](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/184)) ([139cfd1](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/139cfd135cdb07573fe87d824631fcdb6153186e))
+
+
+### Bug Fixes
+
+* do not error if the dialog was already handled ([#208](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/208)) ([d9f77f8](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/d9f77f85098ffe851308c5de05effb03ac21237b))
+* reference to handle_dialog tool ([#209](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/209)) ([205eef5](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/205eef5cdff19ccb7ddbd113bb1450cb87e8f398))
+* support node20 ([#52](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/52)) ([13613b4](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/13613b4a33ab7cf2d4fb1f4849bfa6b82f546945))
+* update tool reference in an error ([#205](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/205)) ([7765bb3](https://github.com/ChromeDevTools/chrome-devtools-mcp/commit/7765bb381ad9d01219547faf879a74978188754a))
+
 ## [0.4.0](https://github.com/ChromeDevTools/chrome-devtools-mcp/compare/chrome-devtools-mcp-v0.3.0...chrome-devtools-mcp-v0.4.0) (2025-09-26)
 
 
diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ MCP clients.
 
 ## Requirements
 
-- [Node.js 22.12.0](https://nodejs.org/) or newer.
+- [Node.js 20](https://nodejs.org/) or a newer [latest maintainance LTS](https://github.com/nodejs/Release#release-schedule) version.
 - [Chrome](https://www.google.com/chrome/) current stable version or newer.
 - [npm](https://www.npmjs.com/).
 
@@ -75,6 +75,23 @@ claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
 codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
 ```
 
+**On Windows 11**
+
+Configure the Chrome install location and increase the startup timeout by updating `.codex/config.toml` and adding the following `env` and `startup_timeout_ms` parameters:
+
+```
+[mcp_servers.chrome-devtools]
+command = "cmd"
+args = [
+    "/c",
+    "npx",
+    "-y",
+    "chrome-devtools-mcp@latest",
+]
+env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
+startup_timeout_ms = 20_000
+```
+
 </details>
 
 <details>
diff --git a/docs/tool-reference.md b/docs/tool-reference.md
@@ -308,6 +308,7 @@ so returned values have to JSON-serializable.
 
 - **format** (enum: "png", "jpeg") _(optional)_: Type of format to save the screenshot as. Default is "png"
 - **fullPage** (boolean) _(optional)_: If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.
+- **quality** (number) _(optional)_: Compression quality for JPEG format (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.
 - **uid** (string) _(optional)_: The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.
 
 ---
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -14,6 +14,7 @@
     "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
     "start": "npm run build && node build/src/index.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
+    "test:node20": "node --require ./build/tests/setup.js --test-reporter spec --test-force-exit --test build/tests",
     "test": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test \"build/tests/**/*.test.js\"",
     "test:only": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
     "test:only:no-build": "node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
@@ -36,7 +37,8 @@
   "homepage": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme",
   "mcpName": "io.github.ChromeDevTools/chrome-devtools-mcp",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.18.1",
+    "@modelcontextprotocol/sdk": "1.18.2",
+    "core-js": "3.45.1",
     "debug": "4.4.3",
     "puppeteer-core": "24.22.3",
     "yargs": "18.0.0"
@@ -53,16 +55,16 @@
     "@typescript-eslint/parser": "^8.43.0",
     "chrome-devtools-frontend": "1.0.1520535",
     "eslint": "^9.35.0",
-    "eslint-plugin-import": "^2.32.0",
     "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
     "puppeteer": "24.22.3",
     "sinon": "^21.0.0",
-    "typescript-eslint": "^8.43.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^20.19.0 || ^22.12.0 || >=23"
   }
 }
diff --git a/src/McpContext.ts b/src/McpContext.ts
@@ -21,6 +21,7 @@ import type {
 
 import {NetworkCollector, PageCollector} from './PageCollector.js';
 import {listPages} from './tools/pages.js';
+import {takeSnapshot} from './tools/snapshot.js';
 import {CLOSE_PAGE_ERROR} from './tools/ToolDefinition.js';
 import type {Context} from './tools/ToolDefinition.js';
 import type {TraceResult} from './trace-processing/parse.js';
@@ -261,7 +262,9 @@ export class McpContext implements Context {
 
   async getElementByUid(uid: string): Promise<ElementHandle<Element>> {
     if (!this.#textSnapshot?.idToNode.size) {
-      throw new Error('No snapshot found. Use browser_snapshot to capture one');
+      throw new Error(
+        `No snapshot found. Use ${takeSnapshot.name} to capture one.`,
+      );
     }
     const [snapshotId] = uid.split('_');
 
diff --git a/src/McpResponse.ts b/src/McpResponse.ts
@@ -17,6 +17,7 @@ import {
 } from './formatters/networkFormatter.js';
 import {formatA11ySnapshot} from './formatters/snapshotFormatter.js';
 import type {McpContext} from './McpContext.js';
+import {handleDialog} from './tools/pages.js';
 import type {ImageContentData, Response} from './tools/ToolDefinition.js';
 import {paginate, type PaginationOptions} from './utils/pagination.js';
 
@@ -167,7 +168,7 @@ export class McpResponse implements Response {
     if (dialog) {
       response.push(`# Open dialog
 ${dialog.type()}: ${dialog.message()} (default value: ${dialog.message()}).
-Call browser_handle_dialog to handle it before continuing.`);
+Call ${handleDialog.name} to handle it before continuing.`);
     }
 
     if (this.#includePages) {
diff --git a/src/index.ts b/src/index.ts
@@ -10,9 +10,23 @@ import {version} from 'node:process';
 
 const [major, minor] = version.substring(1).split('.').map(Number);
 
-if (major < 22 || (major === 22 && minor < 12)) {
+if (major === 20 && minor < 19) {
   console.error(
-    `ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 or newer.`,
+    `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.19.0 LTS or a newer LTS.`,
   );
   process.exit(1);
 }
diff --git a/src/main.ts b/src/main.ts
@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import './polyfill.js';
+
 import assert from 'node:assert';
 import fs from 'node:fs';
 import path from 'node:path';
diff --git a/src/polyfill.ts b/src/polyfill.ts
@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import 'core-js/modules/es.promise.with-resolvers.js';
+import 'core-js/proposals/iterator-helpers.js';
diff --git a/src/tools/pages.ts b/src/tools/pages.ts
@@ -6,6 +6,8 @@
 
 import z from 'zod';
 
+import {logger} from '../logger.js';
+
 import {ToolCategories} from './categories.js';
 import {CLOSE_PAGE_ERROR, defineTool} from './ToolDefinition.js';
 
@@ -195,12 +197,22 @@ export const handleDialog = defineTool({
 
     switch (request.params.action) {
       case 'accept': {
-        await dialog.accept(request.params.promptText);
+        try {
+          await dialog.accept(request.params.promptText);
+        } catch (err) {
+          // Likely already handled by the user outside of MCP.
+          logger(err);
+        }
         response.appendResponseLine('Successfully accepted the dialog');
         break;
       }
       case 'dismiss': {
-        await dialog.dismiss();
+        try {
+          await dialog.dismiss();
+        } catch (err) {
+          // Likely already handled.
+          logger(err);
+        }
         response.appendResponseLine('Successfully dismissed the dialog');
         break;
       }
diff --git a/src/tools/screenshot.ts b/src/tools/screenshot.ts
@@ -22,6 +22,14 @@ export const screenshot = defineTool({
       .enum(['png', 'jpeg'])
       .default('png')
       .describe('Type of format to save the screenshot as. Default is "png"'),
+    quality: z
+      .number()
+      .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.',
+      ),
     uid: z
       .string()
       .optional()
@@ -50,6 +58,8 @@ export const screenshot = defineTool({
     const screenshot = await pageOrHandle.screenshot({
       type: request.params.format,
       fullPage: request.params.fullPage,
+      quality: request.params.quality,
+      optimizeForSpeed: true, // Bonus: optimize encoding for speed
     });
 
     if (request.params.uid) {
diff --git a/tests/McpResponse.test.ts b/tests/McpResponse.test.ts
@@ -169,7 +169,7 @@ Emulating: 4x slowdown`,
         `# test response
 # Open dialog
 alert: test (default value: test).
-Call browser_handle_dialog to handle it before continuing.`,
+Call handle_dialog to handle it before continuing.`,
       );
     });
   });
diff --git a/tests/setup.ts b/tests/setup.ts
@@ -3,6 +3,8 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import '../src/polyfill.js';
+
 import path from 'node:path';
 import {it} from 'node:test';
 
diff --git a/tests/tools/pages.test.ts b/tests/tools/pages.test.ts
diff --git a/tests/utils.ts b/tests/utils.ts

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`{`
`2`		`- ".": "0.4.0"`
	`2`	`+ ".": "0.5.1"`
`3`	`3`	`}`