From d142b3384c6a8159bcb009aff88640625eb71a1d Mon Sep 17 00:00:00 2001
From: Pedro Durek <pedro.durek@shopify.com>
Date: Tue, 12 May 2026 13:47:13 -0600
Subject: [PATCH 1/6] feat: add extraHTTPHeaders parameter to emulate tool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend the existing emulate tool with an extraHTTPHeaders parameter
that calls Puppeteer's page.setExtraHTTPHeaders() (which uses CDP
Network.setExtraHTTPHeaders under the hood).

This enables setting custom HTTP headers on all requests — including
the initial document navigation and <script> tag loads — which
initScript cannot do since it runs after the document is already
fetched.

Per reviewer feedback, the parameter is a JSON string (not an object)
for CLI compatibility. Empty string clears the headers.

Closes #1175

Usage:
  // Set headers
  emulate({ extraHTTPHeaders: '{"X-Custom": "value"}' })

  // Clear headers
  emulate({ extraHTTPHeaders: '' })

  // Combine with other emulation settings
  emulate({ extraHTTPHeaders: '{"X-Branch": "feature-1"}', userAgent: 'MyBot/1.0' })
---
 src/McpContext.ts             |  13 +++
 src/tools/emulation.ts        |  29 ++++++
 src/types.ts                  |   1 +
 tests/tools/emulation.test.ts | 167 ++++++++++++++++++++++++++++++++++
 4 files changed, 210 insertions(+)

diff --git a/src/McpContext.ts b/src/McpContext.ts
index 88fa344c0..79440aa2a 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -301,6 +301,7 @@ export class McpContext implements Context {
       userAgent?: string;
       colorScheme?: 'dark' | 'light' | 'auto';
       viewport?: Viewport;
+      extraHTTPHeaders?: Record<string, string> | null | undefined;
     },
     targetPage?: Page,
   ): Promise<void> {
@@ -379,6 +380,18 @@ export class McpContext implements Context {
       newSettings.viewport = viewport;
     }
 
+    if (options.extraHTTPHeaders !== undefined) {
+      if (options.extraHTTPHeaders === null) {
+        // Clear headers when null (from empty string)
+        await page.setExtraHTTPHeaders({});
+        delete newSettings.extraHTTPHeaders;
+      } else {
+        // Set headers when we have an object
+        await page.setExtraHTTPHeaders(options.extraHTTPHeaders);
+        newSettings.extraHTTPHeaders = options.extraHTTPHeaders;
+      }
+    }
+
     mcpPage.emulationSettings = Object.keys(newSettings).length
       ? newSettings
       : {};
diff --git a/src/tools/emulation.ts b/src/tools/emulation.ts
index 7eebe9200..4c282539b 100644
--- a/src/tools/emulation.ts
+++ b/src/tools/emulation.ts
@@ -14,6 +14,28 @@ import {
   viewportTransform,
 } from './ToolDefinition.js';
 
+function headerStringTransform(
+  value: string | undefined,
+): Record<string, string> | null | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === '') {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      throw new Error('Headers must be a JSON object');
+    }
+    return parsed as Record<string, string>;
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON for headers: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
 const throttlingOptions: [string, ...string[]] = [
   'Offline',
   ...Object.keys(PredefinedNetworkConditions),
@@ -65,6 +87,13 @@ export const emulate = definePageTool({
       .describe(
         `Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`,
       ),
+    extraHTTPHeaders: zod
+      .string()
+      .optional()
+      .transform(headerStringTransform)
+      .describe(
+        'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers persist across navigations until cleared. Pass an empty string to clear all extra headers.',
+      ),
   },
   blockedByDialog: true,
   handler: async (request, response, context) => {
diff --git a/src/types.ts b/src/types.ts
index 13e64f58d..c7246d796 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -31,4 +31,5 @@ export interface EmulationSettings {
   userAgent?: string;
   colorScheme?: 'dark' | 'light';
   viewport?: Viewport;
+  extraHTTPHeaders?: Record<string, string>;
 }
diff --git a/tests/tools/emulation.test.ts b/tests/tools/emulation.test.ts
index b1a19a904..bbaca45a9 100644
--- a/tests/tools/emulation.test.ts
+++ b/tests/tools/emulation.test.ts
@@ -5,6 +5,7 @@
  */
 
 import assert from 'node:assert';
+import type {IncomingHttpHeaders} from 'node:http';
 import {beforeEach, describe, it} from 'node:test';
 
 import {emulate} from '../../src/tools/emulation.js';
@@ -571,6 +572,172 @@ describe('emulation', () => {
     });
   });
 
+  describe('extraHTTPHeaders', () => {
+    it('sets extra headers on requests', async () => {
+      let receivedHeaders: IncomingHttpHeaders = {};
+      server.addRoute('/headers-test', async (req, res) => {
+        receivedHeaders = req.headers;
+        res.writeHead(200, {'Content-Type': 'text/html'});
+        res.end('<main>Headers Test</main>');
+      });
+
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: {'X-Custom-Header': 'test-value'},
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        await page.goto(server.getRoute('/headers-test'));
+        assert.strictEqual(receivedHeaders['x-custom-header'], 'test-value');
+      });
+    });
+
+    it('clears extra headers when null is passed', async () => {
+      let receivedHeaders: IncomingHttpHeaders = {};
+      server.addRoute('/headers-clear', async (req, res) => {
+        receivedHeaders = req.headers;
+        res.writeHead(200, {'Content-Type': 'text/html'});
+        res.end('<main>Headers Clear</main>');
+      });
+
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        // Set headers first
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: {'X-To-Clear': 'value'},
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        // Clear headers
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: null,
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        await page.goto(server.getRoute('/headers-clear'));
+        assert.strictEqual(receivedHeaders['x-to-clear'], undefined);
+        assert.strictEqual(
+          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          undefined,
+        );
+      });
+    });
+
+    it('headers persist across navigations', async () => {
+      const receivedHeaders: IncomingHttpHeaders[] = [];
+      server.addRoute('/persist-one', async (req, res) => {
+        receivedHeaders.push({...req.headers});
+        res.writeHead(200, {'Content-Type': 'text/html'});
+        res.end('<main>Page One</main>');
+      });
+      server.addRoute('/persist-two', async (req, res) => {
+        receivedHeaders.push({...req.headers});
+        res.writeHead(200, {'Content-Type': 'text/html'});
+        res.end('<main>Page Two</main>');
+      });
+
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: {'X-Persist': 'yes'},
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        await page.goto(server.getRoute('/persist-one'));
+        await page.goto(server.getRoute('/persist-two'));
+
+        assert.strictEqual(receivedHeaders[0]?.['x-persist'], 'yes');
+        assert.strictEqual(receivedHeaders[1]?.['x-persist'], 'yes');
+      });
+    });
+
+    it('does not affect other emulation settings', async () => {
+      await withMcpContext(async (response, context) => {
+        // Set userAgent first
+        await emulate.handler(
+          {
+            params: {
+              userAgent: 'MyUA',
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        // Set extraHTTPHeaders separately
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: {'X-Test': 'value'},
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        const settings = context.getSelectedMcpPage().emulationSettings;
+        assert.deepStrictEqual(settings.extraHTTPHeaders, {
+          'X-Test': 'value',
+        });
+      });
+    });
+
+    it('reports correctly for the currently selected page', async () => {
+      await withMcpContext(async (response, context) => {
+        await emulate.handler(
+          {
+            params: {
+              extraHTTPHeaders: {'X-Page': 'one'},
+            },
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+
+        assert.deepStrictEqual(
+          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          {'X-Page': 'one'},
+        );
+
+        const page = await context.newPage();
+        context.selectPage(page);
+
+        assert.strictEqual(
+          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          undefined,
+        );
+      });
+    });
+  });
+
   describe('colorScheme', () => {
     it('emulates color scheme', async () => {
       await withMcpContext(async (response, context) => {

From 8eb653967207c21944259c93ef8f36739ce3b4d7 Mon Sep 17 00:00:00 2001
From: Alex Rudenko <alexrudenko@chromium.org>
Date: Thu, 14 May 2026 07:52:16 +0200
Subject: [PATCH 2/6] chore: format

---
 docs/tool-reference.md    |   4 +-
 src/bin/cliDefinitions.ts | 713 ++++++++++++++++++++++++++++++++++++++
 src/tools/emulation.ts    |   8 +-
 3 files changed, 722 insertions(+), 3 deletions(-)
 create mode 100644 src/bin/cliDefinitions.ts

diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 6e8a2ba8b..510679008 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -1,6 +1,7 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
 # Chrome DevTools MCP Tool Reference
+# Chrome DevTools MCP Tool Reference (~7019 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (10 tools)
   - [`click`](#click)
@@ -256,7 +257,8 @@
 
 - **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling
-- **geolocation** (string) _(optional)_: Geolocation (`&lt;latitude&gt;,&lt;longitude&gt;`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.
+- **extraHTTPHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
+- **geolocation** (string) _(optional)_: Geolocation (`&lt;latitude&gt;x&lt;longitude&gt;`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.
 - **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.
 - **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.
 - **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '&lt;width&gt;x&lt;height&gt;x&lt;devicePixelRatio&gt;[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.
diff --git a/src/bin/cliDefinitions.ts b/src/bin/cliDefinitions.ts
new file mode 100644
index 000000000..611e4effa
--- /dev/null
+++ b/src/bin/cliDefinitions.ts
@@ -0,0 +1,713 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// NOTE: do not edit manually. Auto-generated by 'npm run cli:generate'.
+
+export interface ArgDef {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+  default?: string | number | boolean;
+  enum?: ReadonlyArray<string | number>;
+}
+export type Commands = Record<
+  string,
+  {
+    description: string;
+    category: string;
+    args: Record<string, ArgDef>;
+  }
+>;
+export const commands: Commands = {
+  click: {
+    description: 'Clicks on the provided element',
+    category: 'Input automation',
+    args: {
+      uid: {
+        name: 'uid',
+        type: 'string',
+        description:
+          'The uid of an element on the page from the page content snapshot',
+        required: true,
+      },
+      dblClick: {
+        name: 'dblClick',
+        type: 'boolean',
+        description: 'Set to true for double clicks. Default is false.',
+        required: false,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+  close_page: {
+    description:
+      'Closes the page by its index. The last open page cannot be closed.',
+    category: 'Navigation automation',
+    args: {
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'The ID of the page to close. Call list_pages to list pages.',
+        required: true,
+      },
+    },
+  },
+  drag: {
+    description: 'Drag an element onto another element',
+    category: 'Input automation',
+    args: {
+      from_uid: {
+        name: 'from_uid',
+        type: 'string',
+        description: 'The uid of the element to drag',
+        required: true,
+      },
+      to_uid: {
+        name: 'to_uid',
+        type: 'string',
+        description: 'The uid of the element to drop into',
+        required: true,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+  emulate: {
+    description: 'Emulates various features on the selected page.',
+    category: 'Emulation',
+    args: {
+      networkConditions: {
+        name: 'networkConditions',
+        type: 'string',
+        description: 'Throttle network. Omit to disable throttling.',
+        required: false,
+        enum: ['Offline', 'Slow 3G', 'Fast 3G', 'Slow 4G', 'Fast 4G'],
+      },
+      cpuThrottlingRate: {
+        name: 'cpuThrottlingRate',
+        type: 'number',
+        description:
+          'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling',
+        required: false,
+      },
+      geolocation: {
+        name: 'geolocation',
+        type: 'string',
+        description:
+          'Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.',
+        required: false,
+      },
+      userAgent: {
+        name: 'userAgent',
+        type: 'string',
+        description:
+          'User agent to emulate. Set to empty string to clear the user agent override.',
+        required: false,
+      },
+      colorScheme: {
+        name: 'colorScheme',
+        type: 'string',
+        description:
+          'Emulate the dark or the light mode. Set to "auto" to reset to the default.',
+        required: false,
+        enum: ['dark', 'light', 'auto'],
+      },
+      viewport: {
+        name: 'viewport',
+        type: 'string',
+        description:
+          "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",
+        required: false,
+      },
+      extraHTTPHeaders: {
+        name: 'extraHTTPHeaders',
+        type: 'string',
+        description:
+          'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
+        required: false,
+      },
+    },
+  },
+  evaluate_script: {
+    description:
+      'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.',
+    category: 'Debugging',
+    args: {
+      function: {
+        name: 'function',
+        type: 'string',
+        description:
+          'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n  return document.title\n}` or `async () => {\n  return await fetch("example.com")\n}`.\nExample with arguments: `(el) => {\n  return el.innerText;\n}`\n',
+        required: true,
+      },
+      args: {
+        name: 'args',
+        type: 'array',
+        description: 'An optional list of arguments to pass to the function.',
+        required: false,
+      },
+    },
+  },
+  fill: {
+    description:
+      'Type text into a input, text area or select an option from a <select> element.',
+    category: 'Input automation',
+    args: {
+      uid: {
+        name: 'uid',
+        type: 'string',
+        description:
+          'The uid of an element on the page from the page content snapshot',
+        required: true,
+      },
+      value: {
+        name: 'value',
+        type: 'string',
+        description: 'The value to fill in',
+        required: true,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+  get_console_message: {
+    description:
+      'Gets a console message by its ID. You can get all messages by calling list_console_messages.',
+    category: 'Debugging',
+    args: {
+      msgid: {
+        name: 'msgid',
+        type: 'number',
+        description:
+          'The msgid of a console message on the page from the listed console messages',
+        required: true,
+      },
+    },
+  },
+  get_network_request: {
+    description:
+      'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.',
+    category: 'Network',
+    args: {
+      reqid: {
+        name: 'reqid',
+        type: 'number',
+        description:
+          'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.',
+        required: false,
+      },
+      requestFilePath: {
+        name: 'requestFilePath',
+        type: 'string',
+        description:
+          'The absolute or relative path to save the request body to. If omitted, the body is returned inline.',
+        required: false,
+      },
+      responseFilePath: {
+        name: 'responseFilePath',
+        type: 'string',
+        description:
+          'The absolute or relative path to save the response body to. If omitted, the body is returned inline.',
+        required: false,
+      },
+    },
+  },
+  handle_dialog: {
+    description:
+      'If a browser dialog was opened, use this command to handle it',
+    category: 'Input automation',
+    args: {
+      action: {
+        name: 'action',
+        type: 'string',
+        description: 'Whether to dismiss or accept the dialog',
+        required: true,
+        enum: ['accept', 'dismiss'],
+      },
+      promptText: {
+        name: 'promptText',
+        type: 'string',
+        description: 'Optional prompt text to enter into the dialog.',
+        required: false,
+      },
+    },
+  },
+  hover: {
+    description: 'Hover over the provided element',
+    category: 'Input automation',
+    args: {
+      uid: {
+        name: 'uid',
+        type: 'string',
+        description:
+          'The uid of an element on the page from the page content snapshot',
+        required: true,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+  lighthouse_audit: {
+    description:
+      'Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace',
+    category: 'Debugging',
+    args: {
+      mode: {
+        name: 'mode',
+        type: 'string',
+        description:
+          '"navigation" reloads & audits. "snapshot" analyzes current state.',
+        required: false,
+        default: 'navigation',
+        enum: ['navigation', 'snapshot'],
+      },
+      device: {
+        name: 'device',
+        type: 'string',
+        description: 'Device to emulate.',
+        required: false,
+        default: 'desktop',
+        enum: ['desktop', 'mobile'],
+      },
+      outputDirPath: {
+        name: 'outputDirPath',
+        type: 'string',
+        description: 'Directory for reports. If omitted, uses temporary files.',
+        required: false,
+      },
+    },
+  },
+  list_console_messages: {
+    description:
+      'List all console messages for the currently selected page since the last navigation.',
+    category: 'Debugging',
+    args: {
+      pageSize: {
+        name: 'pageSize',
+        type: 'integer',
+        description:
+          'Maximum number of messages to return. When omitted, returns all requests.',
+        required: false,
+      },
+      pageIdx: {
+        name: 'pageIdx',
+        type: 'integer',
+        description:
+          'Page number to return (0-based). When omitted, returns the first page.',
+        required: false,
+      },
+      types: {
+        name: 'types',
+        type: 'array',
+        description:
+          'Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.',
+        required: false,
+      },
+      includePreservedMessages: {
+        name: 'includePreservedMessages',
+        type: 'boolean',
+        description:
+          'Set to true to return the preserved messages over the last 3 navigations.',
+        required: false,
+        default: false,
+      },
+    },
+  },
+  list_network_requests: {
+    description:
+      'List all requests for the currently selected page since the last navigation.',
+    category: 'Network',
+    args: {
+      pageSize: {
+        name: 'pageSize',
+        type: 'integer',
+        description:
+          'Maximum number of requests to return. When omitted, returns all requests.',
+        required: false,
+      },
+      pageIdx: {
+        name: 'pageIdx',
+        type: 'integer',
+        description:
+          'Page number to return (0-based). When omitted, returns the first page.',
+        required: false,
+      },
+      resourceTypes: {
+        name: 'resourceTypes',
+        type: 'array',
+        description:
+          'Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.',
+        required: false,
+      },
+      includePreservedRequests: {
+        name: 'includePreservedRequests',
+        type: 'boolean',
+        description:
+          'Set to true to return the preserved requests over the last 3 navigations.',
+        required: false,
+        default: false,
+      },
+    },
+  },
+  list_pages: {
+    description: 'Get a list of pages  open in the browser.',
+    category: 'Navigation automation',
+    args: {},
+  },
+  navigate_page: {
+    description:
+      'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
+    category: 'Navigation automation',
+    args: {
+      type: {
+        name: 'type',
+        type: 'string',
+        description:
+          'Navigate the page by URL, back or forward in history, or reload.',
+        required: false,
+        enum: ['url', 'back', 'forward', 'reload'],
+      },
+      url: {
+        name: 'url',
+        type: 'string',
+        description: 'Target URL (only type=url)',
+        required: false,
+      },
+      ignoreCache: {
+        name: 'ignoreCache',
+        type: 'boolean',
+        description: 'Whether to ignore cache on reload.',
+        required: false,
+      },
+      handleBeforeUnload: {
+        name: 'handleBeforeUnload',
+        type: 'string',
+        description:
+          'Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.',
+        required: false,
+        enum: ['accept', 'decline'],
+      },
+      initScript: {
+        name: 'initScript',
+        type: 'string',
+        description:
+          'A JavaScript script to be executed on each new document before any other scripts for the next navigation.',
+        required: false,
+      },
+      timeout: {
+        name: 'timeout',
+        type: 'integer',
+        description:
+          'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
+        required: false,
+      },
+    },
+  },
+  new_page: {
+    description:
+      'Open a new tab and load a URL. Use project URL if not specified otherwise.',
+    category: 'Navigation automation',
+    args: {
+      url: {
+        name: 'url',
+        type: 'string',
+        description: 'URL to load in a new page.',
+        required: true,
+      },
+      background: {
+        name: 'background',
+        type: 'boolean',
+        description:
+          'Whether to open the page in the background without bringing it to the front. Default is false (foreground).',
+        required: false,
+      },
+      isolatedContext: {
+        name: 'isolatedContext',
+        type: 'string',
+        description:
+          'If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.',
+        required: false,
+      },
+      timeout: {
+        name: 'timeout',
+        type: 'integer',
+        description:
+          'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
+        required: false,
+      },
+    },
+  },
+  performance_analyze_insight: {
+    description:
+      'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
+    category: 'Performance',
+    args: {
+      insightSetId: {
+        name: 'insightSetId',
+        type: 'string',
+        description:
+          'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.',
+        required: true,
+      },
+      insightName: {
+        name: 'insightName',
+        type: 'string',
+        description:
+          'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
+        required: true,
+      },
+    },
+  },
+  performance_start_trace: {
+    description:
+      'Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.',
+    category: 'Performance',
+    args: {
+      reload: {
+        name: 'reload',
+        type: 'boolean',
+        description:
+          'Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.',
+        required: false,
+        default: true,
+      },
+      autoStop: {
+        name: 'autoStop',
+        type: 'boolean',
+        description:
+          'Determines if the trace recording should be automatically stopped.',
+        required: false,
+        default: true,
+      },
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
+        required: false,
+      },
+    },
+  },
+  performance_stop_trace: {
+    description:
+      'Stop the active performance trace recording on the selected webpage.',
+    category: 'Performance',
+    args: {
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
+        required: false,
+      },
+    },
+  },
+  press_key: {
+    description:
+      'Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).',
+    category: 'Input automation',
+    args: {
+      key: {
+        name: 'key',
+        type: 'string',
+        description:
+          'A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta',
+        required: true,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+  resize_page: {
+    description:
+      "Resizes the selected page's window so that the page has specified dimension",
+    category: 'Emulation',
+    args: {
+      width: {
+        name: 'width',
+        type: 'number',
+        description: 'Page width',
+        required: true,
+      },
+      height: {
+        name: 'height',
+        type: 'number',
+        description: 'Page height',
+        required: true,
+      },
+    },
+  },
+  select_page: {
+    description: 'Select a page as a context for future tool calls.',
+    category: 'Navigation automation',
+    args: {
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'The ID of the page to select. Call list_pages to get available pages.',
+        required: true,
+      },
+      bringToFront: {
+        name: 'bringToFront',
+        type: 'boolean',
+        description: 'Whether to focus the page and bring it to the top.',
+        required: false,
+      },
+    },
+  },
+  take_memory_snapshot: {
+    description:
+      'Capture a memory heapsnapshot of the currently selected page to memory leak debugging',
+    category: 'Performance',
+    args: {
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'A path to a .heapsnapshot file to save the heapsnapshot to.',
+        required: true,
+      },
+    },
+  },
+  take_screenshot: {
+    description: 'Take a screenshot of the page or element.',
+    category: 'Debugging',
+    args: {
+      format: {
+        name: 'format',
+        type: 'string',
+        description:
+          'Type of format to save the screenshot as. Default is "png"',
+        required: false,
+        default: 'png',
+        enum: ['png', 'jpeg', 'webp'],
+      },
+      quality: {
+        name: 'quality',
+        type: 'number',
+        description:
+          'Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.',
+        required: false,
+      },
+      uid: {
+        name: 'uid',
+        type: 'string',
+        description:
+          'The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.',
+        required: false,
+      },
+      fullPage: {
+        name: 'fullPage',
+        type: 'boolean',
+        description:
+          'If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.',
+        required: false,
+      },
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.',
+        required: false,
+      },
+    },
+  },
+  take_snapshot: {
+    description:
+      'Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique\nidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected\nin the DevTools Elements panel (if any).',
+    category: 'Debugging',
+    args: {
+      verbose: {
+        name: 'verbose',
+        type: 'boolean',
+        description:
+          'Whether to include all possible information available in the full a11y tree. Default is false.',
+        required: false,
+      },
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description:
+          'The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.',
+        required: false,
+      },
+    },
+  },
+  type_text: {
+    description: 'Type text using keyboard into a previously focused input',
+    category: 'Input automation',
+    args: {
+      text: {
+        name: 'text',
+        type: 'string',
+        description: 'The text to type',
+        required: true,
+      },
+      submitKey: {
+        name: 'submitKey',
+        type: 'string',
+        description:
+          'Optional key to press after typing. E.g., "Enter", "Tab", "Escape"',
+        required: false,
+      },
+    },
+  },
+  upload_file: {
+    description: 'Upload a file through a provided element.',
+    category: 'Input automation',
+    args: {
+      uid: {
+        name: 'uid',
+        type: 'string',
+        description:
+          'The uid of the file input element or an element that will open file chooser on the page from the page content snapshot',
+        required: true,
+      },
+      filePath: {
+        name: 'filePath',
+        type: 'string',
+        description: 'The local path of the file to upload',
+        required: true,
+      },
+      includeSnapshot: {
+        name: 'includeSnapshot',
+        type: 'boolean',
+        description:
+          'Whether to include a snapshot in the response. Default is false.',
+        required: false,
+      },
+    },
+  },
+} as const;
diff --git a/src/tools/emulation.ts b/src/tools/emulation.ts
index 4c282539b..36ba95faa 100644
--- a/src/tools/emulation.ts
+++ b/src/tools/emulation.ts
@@ -25,7 +25,11 @@ function headerStringTransform(
   }
   try {
     const parsed = JSON.parse(value);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
       throw new Error('Headers must be a JSON object');
     }
     return parsed as Record<string, string>;
@@ -92,7 +96,7 @@ export const emulate = definePageTool({
       .optional()
       .transform(headerStringTransform)
       .describe(
-        'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers persist across navigations until cleared. Pass an empty string to clear all extra headers.',
+        'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
       ),
   },
   blockedByDialog: true,

From c9fbd5888afb8b87ee80f5f51056929a61d1b14c Mon Sep 17 00:00:00 2001
From: Alex Rudenko <alexrudenko@chromium.org>
Date: Thu, 14 May 2026 07:58:51 +0200
Subject: [PATCH 3/6] chore: rebase

---
 docs/tool-reference.md                 |   3 +-
 src/bin/chrome-devtools-cli-options.ts |   7 +
 src/bin/cliDefinitions.ts              | 713 -------------------------
 src/telemetry/tool_call_metrics.json   |   4 +
 4 files changed, 12 insertions(+), 715 deletions(-)
 delete mode 100644 src/bin/cliDefinitions.ts

diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 510679008..655ff61c8 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -1,7 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
 # Chrome DevTools MCP Tool Reference
-# Chrome DevTools MCP Tool Reference (~7019 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (10 tools)
   - [`click`](#click)
@@ -258,7 +257,7 @@
 - **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling
 - **extraHTTPHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
-- **geolocation** (string) _(optional)_: Geolocation (`&lt;latitude&gt;x&lt;longitude&gt;`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.
+- **geolocation** (string) _(optional)_: Geolocation (`&lt;latitude&gt;,&lt;longitude&gt;`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.
 - **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.
 - **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.
 - **viewport** (string) _(optional)_: [`Emulate`](#emulate) device viewports '&lt;width&gt;x&lt;height&gt;x&lt;devicePixelRatio&gt;[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to [`emulate`](#emulate) mobile devices. 'landscape' to [`emulate`](#emulate) landscape mode.
diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.ts
index 221ad3ebe..faf1c6a97 100644
--- a/src/bin/chrome-devtools-cli-options.ts
+++ b/src/bin/chrome-devtools-cli-options.ts
@@ -167,6 +167,13 @@ export const commands: Commands = {
           "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",
         required: false,
       },
+      extraHTTPHeaders: {
+        name: 'extraHTTPHeaders',
+        type: 'string',
+        description:
+          'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
+        required: false,
+      },
     },
   },
   evaluate_script: {
diff --git a/src/bin/cliDefinitions.ts b/src/bin/cliDefinitions.ts
deleted file mode 100644
index 611e4effa..000000000
--- a/src/bin/cliDefinitions.ts
+++ /dev/null
@@ -1,713 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-// NOTE: do not edit manually. Auto-generated by 'npm run cli:generate'.
-
-export interface ArgDef {
-  name: string;
-  type: string;
-  description: string;
-  required: boolean;
-  default?: string | number | boolean;
-  enum?: ReadonlyArray<string | number>;
-}
-export type Commands = Record<
-  string,
-  {
-    description: string;
-    category: string;
-    args: Record<string, ArgDef>;
-  }
->;
-export const commands: Commands = {
-  click: {
-    description: 'Clicks on the provided element',
-    category: 'Input automation',
-    args: {
-      uid: {
-        name: 'uid',
-        type: 'string',
-        description:
-          'The uid of an element on the page from the page content snapshot',
-        required: true,
-      },
-      dblClick: {
-        name: 'dblClick',
-        type: 'boolean',
-        description: 'Set to true for double clicks. Default is false.',
-        required: false,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-  close_page: {
-    description:
-      'Closes the page by its index. The last open page cannot be closed.',
-    category: 'Navigation automation',
-    args: {
-      pageId: {
-        name: 'pageId',
-        type: 'number',
-        description:
-          'The ID of the page to close. Call list_pages to list pages.',
-        required: true,
-      },
-    },
-  },
-  drag: {
-    description: 'Drag an element onto another element',
-    category: 'Input automation',
-    args: {
-      from_uid: {
-        name: 'from_uid',
-        type: 'string',
-        description: 'The uid of the element to drag',
-        required: true,
-      },
-      to_uid: {
-        name: 'to_uid',
-        type: 'string',
-        description: 'The uid of the element to drop into',
-        required: true,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-  emulate: {
-    description: 'Emulates various features on the selected page.',
-    category: 'Emulation',
-    args: {
-      networkConditions: {
-        name: 'networkConditions',
-        type: 'string',
-        description: 'Throttle network. Omit to disable throttling.',
-        required: false,
-        enum: ['Offline', 'Slow 3G', 'Fast 3G', 'Slow 4G', 'Fast 4G'],
-      },
-      cpuThrottlingRate: {
-        name: 'cpuThrottlingRate',
-        type: 'number',
-        description:
-          'Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling',
-        required: false,
-      },
-      geolocation: {
-        name: 'geolocation',
-        type: 'string',
-        description:
-          'Geolocation (`<latitude>x<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit clear the geolocation override.',
-        required: false,
-      },
-      userAgent: {
-        name: 'userAgent',
-        type: 'string',
-        description:
-          'User agent to emulate. Set to empty string to clear the user agent override.',
-        required: false,
-      },
-      colorScheme: {
-        name: 'colorScheme',
-        type: 'string',
-        description:
-          'Emulate the dark or the light mode. Set to "auto" to reset to the default.',
-        required: false,
-        enum: ['dark', 'light', 'auto'],
-      },
-      viewport: {
-        name: 'viewport',
-        type: 'string',
-        description:
-          "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",
-        required: false,
-      },
-      extraHTTPHeaders: {
-        name: 'extraHTTPHeaders',
-        type: 'string',
-        description:
-          'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
-        required: false,
-      },
-    },
-  },
-  evaluate_script: {
-    description:
-      'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.',
-    category: 'Debugging',
-    args: {
-      function: {
-        name: 'function',
-        type: 'string',
-        description:
-          'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n  return document.title\n}` or `async () => {\n  return await fetch("example.com")\n}`.\nExample with arguments: `(el) => {\n  return el.innerText;\n}`\n',
-        required: true,
-      },
-      args: {
-        name: 'args',
-        type: 'array',
-        description: 'An optional list of arguments to pass to the function.',
-        required: false,
-      },
-    },
-  },
-  fill: {
-    description:
-      'Type text into a input, text area or select an option from a <select> element.',
-    category: 'Input automation',
-    args: {
-      uid: {
-        name: 'uid',
-        type: 'string',
-        description:
-          'The uid of an element on the page from the page content snapshot',
-        required: true,
-      },
-      value: {
-        name: 'value',
-        type: 'string',
-        description: 'The value to fill in',
-        required: true,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-  get_console_message: {
-    description:
-      'Gets a console message by its ID. You can get all messages by calling list_console_messages.',
-    category: 'Debugging',
-    args: {
-      msgid: {
-        name: 'msgid',
-        type: 'number',
-        description:
-          'The msgid of a console message on the page from the listed console messages',
-        required: true,
-      },
-    },
-  },
-  get_network_request: {
-    description:
-      'Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.',
-    category: 'Network',
-    args: {
-      reqid: {
-        name: 'reqid',
-        type: 'number',
-        description:
-          'The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.',
-        required: false,
-      },
-      requestFilePath: {
-        name: 'requestFilePath',
-        type: 'string',
-        description:
-          'The absolute or relative path to save the request body to. If omitted, the body is returned inline.',
-        required: false,
-      },
-      responseFilePath: {
-        name: 'responseFilePath',
-        type: 'string',
-        description:
-          'The absolute or relative path to save the response body to. If omitted, the body is returned inline.',
-        required: false,
-      },
-    },
-  },
-  handle_dialog: {
-    description:
-      'If a browser dialog was opened, use this command to handle it',
-    category: 'Input automation',
-    args: {
-      action: {
-        name: 'action',
-        type: 'string',
-        description: 'Whether to dismiss or accept the dialog',
-        required: true,
-        enum: ['accept', 'dismiss'],
-      },
-      promptText: {
-        name: 'promptText',
-        type: 'string',
-        description: 'Optional prompt text to enter into the dialog.',
-        required: false,
-      },
-    },
-  },
-  hover: {
-    description: 'Hover over the provided element',
-    category: 'Input automation',
-    args: {
-      uid: {
-        name: 'uid',
-        type: 'string',
-        description:
-          'The uid of an element on the page from the page content snapshot',
-        required: true,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-  lighthouse_audit: {
-    description:
-      'Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace',
-    category: 'Debugging',
-    args: {
-      mode: {
-        name: 'mode',
-        type: 'string',
-        description:
-          '"navigation" reloads & audits. "snapshot" analyzes current state.',
-        required: false,
-        default: 'navigation',
-        enum: ['navigation', 'snapshot'],
-      },
-      device: {
-        name: 'device',
-        type: 'string',
-        description: 'Device to emulate.',
-        required: false,
-        default: 'desktop',
-        enum: ['desktop', 'mobile'],
-      },
-      outputDirPath: {
-        name: 'outputDirPath',
-        type: 'string',
-        description: 'Directory for reports. If omitted, uses temporary files.',
-        required: false,
-      },
-    },
-  },
-  list_console_messages: {
-    description:
-      'List all console messages for the currently selected page since the last navigation.',
-    category: 'Debugging',
-    args: {
-      pageSize: {
-        name: 'pageSize',
-        type: 'integer',
-        description:
-          'Maximum number of messages to return. When omitted, returns all requests.',
-        required: false,
-      },
-      pageIdx: {
-        name: 'pageIdx',
-        type: 'integer',
-        description:
-          'Page number to return (0-based). When omitted, returns the first page.',
-        required: false,
-      },
-      types: {
-        name: 'types',
-        type: 'array',
-        description:
-          'Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.',
-        required: false,
-      },
-      includePreservedMessages: {
-        name: 'includePreservedMessages',
-        type: 'boolean',
-        description:
-          'Set to true to return the preserved messages over the last 3 navigations.',
-        required: false,
-        default: false,
-      },
-    },
-  },
-  list_network_requests: {
-    description:
-      'List all requests for the currently selected page since the last navigation.',
-    category: 'Network',
-    args: {
-      pageSize: {
-        name: 'pageSize',
-        type: 'integer',
-        description:
-          'Maximum number of requests to return. When omitted, returns all requests.',
-        required: false,
-      },
-      pageIdx: {
-        name: 'pageIdx',
-        type: 'integer',
-        description:
-          'Page number to return (0-based). When omitted, returns the first page.',
-        required: false,
-      },
-      resourceTypes: {
-        name: 'resourceTypes',
-        type: 'array',
-        description:
-          'Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.',
-        required: false,
-      },
-      includePreservedRequests: {
-        name: 'includePreservedRequests',
-        type: 'boolean',
-        description:
-          'Set to true to return the preserved requests over the last 3 navigations.',
-        required: false,
-        default: false,
-      },
-    },
-  },
-  list_pages: {
-    description: 'Get a list of pages  open in the browser.',
-    category: 'Navigation automation',
-    args: {},
-  },
-  navigate_page: {
-    description:
-      'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
-    category: 'Navigation automation',
-    args: {
-      type: {
-        name: 'type',
-        type: 'string',
-        description:
-          'Navigate the page by URL, back or forward in history, or reload.',
-        required: false,
-        enum: ['url', 'back', 'forward', 'reload'],
-      },
-      url: {
-        name: 'url',
-        type: 'string',
-        description: 'Target URL (only type=url)',
-        required: false,
-      },
-      ignoreCache: {
-        name: 'ignoreCache',
-        type: 'boolean',
-        description: 'Whether to ignore cache on reload.',
-        required: false,
-      },
-      handleBeforeUnload: {
-        name: 'handleBeforeUnload',
-        type: 'string',
-        description:
-          'Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.',
-        required: false,
-        enum: ['accept', 'decline'],
-      },
-      initScript: {
-        name: 'initScript',
-        type: 'string',
-        description:
-          'A JavaScript script to be executed on each new document before any other scripts for the next navigation.',
-        required: false,
-      },
-      timeout: {
-        name: 'timeout',
-        type: 'integer',
-        description:
-          'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
-        required: false,
-      },
-    },
-  },
-  new_page: {
-    description:
-      'Open a new tab and load a URL. Use project URL if not specified otherwise.',
-    category: 'Navigation automation',
-    args: {
-      url: {
-        name: 'url',
-        type: 'string',
-        description: 'URL to load in a new page.',
-        required: true,
-      },
-      background: {
-        name: 'background',
-        type: 'boolean',
-        description:
-          'Whether to open the page in the background without bringing it to the front. Default is false (foreground).',
-        required: false,
-      },
-      isolatedContext: {
-        name: 'isolatedContext',
-        type: 'string',
-        description:
-          'If specified, the page is created in an isolated browser context with the given name. Pages in the same browser context share cookies and storage. Pages in different browser contexts are fully isolated.',
-        required: false,
-      },
-      timeout: {
-        name: 'timeout',
-        type: 'integer',
-        description:
-          'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
-        required: false,
-      },
-    },
-  },
-  performance_analyze_insight: {
-    description:
-      'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
-    category: 'Performance',
-    args: {
-      insightSetId: {
-        name: 'insightSetId',
-        type: 'string',
-        description:
-          'The id for the specific insight set. Only use the ids given in the "Available insight sets" list.',
-        required: true,
-      },
-      insightName: {
-        name: 'insightName',
-        type: 'string',
-        description:
-          'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
-        required: true,
-      },
-    },
-  },
-  performance_start_trace: {
-    description:
-      'Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.',
-    category: 'Performance',
-    args: {
-      reload: {
-        name: 'reload',
-        type: 'boolean',
-        description:
-          'Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.',
-        required: false,
-        default: true,
-      },
-      autoStop: {
-        name: 'autoStop',
-        type: 'boolean',
-        description:
-          'Determines if the trace recording should be automatically stopped.',
-        required: false,
-        default: true,
-      },
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description:
-          'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
-        required: false,
-      },
-    },
-  },
-  performance_stop_trace: {
-    description:
-      'Stop the active performance trace recording on the selected webpage.',
-    category: 'Performance',
-    args: {
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description:
-          'The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).',
-        required: false,
-      },
-    },
-  },
-  press_key: {
-    description:
-      'Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).',
-    category: 'Input automation',
-    args: {
-      key: {
-        name: 'key',
-        type: 'string',
-        description:
-          'A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta',
-        required: true,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-  resize_page: {
-    description:
-      "Resizes the selected page's window so that the page has specified dimension",
-    category: 'Emulation',
-    args: {
-      width: {
-        name: 'width',
-        type: 'number',
-        description: 'Page width',
-        required: true,
-      },
-      height: {
-        name: 'height',
-        type: 'number',
-        description: 'Page height',
-        required: true,
-      },
-    },
-  },
-  select_page: {
-    description: 'Select a page as a context for future tool calls.',
-    category: 'Navigation automation',
-    args: {
-      pageId: {
-        name: 'pageId',
-        type: 'number',
-        description:
-          'The ID of the page to select. Call list_pages to get available pages.',
-        required: true,
-      },
-      bringToFront: {
-        name: 'bringToFront',
-        type: 'boolean',
-        description: 'Whether to focus the page and bring it to the top.',
-        required: false,
-      },
-    },
-  },
-  take_memory_snapshot: {
-    description:
-      'Capture a memory heapsnapshot of the currently selected page to memory leak debugging',
-    category: 'Performance',
-    args: {
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description:
-          'A path to a .heapsnapshot file to save the heapsnapshot to.',
-        required: true,
-      },
-    },
-  },
-  take_screenshot: {
-    description: 'Take a screenshot of the page or element.',
-    category: 'Debugging',
-    args: {
-      format: {
-        name: 'format',
-        type: 'string',
-        description:
-          'Type of format to save the screenshot as. Default is "png"',
-        required: false,
-        default: 'png',
-        enum: ['png', 'jpeg', 'webp'],
-      },
-      quality: {
-        name: 'quality',
-        type: 'number',
-        description:
-          'Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.',
-        required: false,
-      },
-      uid: {
-        name: 'uid',
-        type: 'string',
-        description:
-          'The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.',
-        required: false,
-      },
-      fullPage: {
-        name: 'fullPage',
-        type: 'boolean',
-        description:
-          'If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.',
-        required: false,
-      },
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description:
-          'The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.',
-        required: false,
-      },
-    },
-  },
-  take_snapshot: {
-    description:
-      'Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique\nidentifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected\nin the DevTools Elements panel (if any).',
-    category: 'Debugging',
-    args: {
-      verbose: {
-        name: 'verbose',
-        type: 'boolean',
-        description:
-          'Whether to include all possible information available in the full a11y tree. Default is false.',
-        required: false,
-      },
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description:
-          'The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.',
-        required: false,
-      },
-    },
-  },
-  type_text: {
-    description: 'Type text using keyboard into a previously focused input',
-    category: 'Input automation',
-    args: {
-      text: {
-        name: 'text',
-        type: 'string',
-        description: 'The text to type',
-        required: true,
-      },
-      submitKey: {
-        name: 'submitKey',
-        type: 'string',
-        description:
-          'Optional key to press after typing. E.g., "Enter", "Tab", "Escape"',
-        required: false,
-      },
-    },
-  },
-  upload_file: {
-    description: 'Upload a file through a provided element.',
-    category: 'Input automation',
-    args: {
-      uid: {
-        name: 'uid',
-        type: 'string',
-        description:
-          'The uid of the file input element or an element that will open file chooser on the page from the page content snapshot',
-        required: true,
-      },
-      filePath: {
-        name: 'filePath',
-        type: 'string',
-        description: 'The local path of the file to upload',
-        required: true,
-      },
-      includeSnapshot: {
-        name: 'includeSnapshot',
-        type: 'boolean',
-        description:
-          'Whether to include a snapshot in the response. Default is false.',
-        required: false,
-      },
-    },
-  },
-} as const;
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index 9453d60f4..5c49bd80e 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -85,6 +85,10 @@
       {
         "name": "viewport_length",
         "argType": "number"
+      },
+      {
+        "name": "extra_h_t_t_p_headers_length",
+        "argType": "number"
       }
     ]
   },

From bc57d9c3b4eee05a75b7fc15455b27065422c997 Mon Sep 17 00:00:00 2001
From: Nicholas Roscino <nroscino@google.com>
Date: Tue, 19 May 2026 18:20:45 +0200
Subject: [PATCH 4/6] chore: address PR comments

---
 docs/tool-reference.md                 |  2 +-
 src/McpContext.ts                      | 16 ++++++----------
 src/bin/chrome-devtools-cli-options.ts |  4 ++--
 src/telemetry/tool_call_metrics.json   |  8 +++++++-
 src/tools/emulation.ts                 |  6 +++---
 src/types.ts                           |  2 +-
 tests/tools/emulation.test.ts          | 22 +++++++++++-----------
 7 files changed, 31 insertions(+), 29 deletions(-)

diff --git a/docs/tool-reference.md b/docs/tool-reference.md
index 655ff61c8..747193452 100644
--- a/docs/tool-reference.md
+++ b/docs/tool-reference.md
@@ -256,7 +256,7 @@
 
 - **colorScheme** (enum: "dark", "light", "auto") _(optional)_: [`Emulate`](#emulate) the dark or the light mode. Set to "auto" to reset to the default.
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling
-- **extraHTTPHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
+- **extraHttpHeaders** (string) _(optional)_: Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.
 - **geolocation** (string) _(optional)_: Geolocation (`&lt;latitude&gt;,&lt;longitude&gt;`) to [`emulate`](#emulate). Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.
 - **networkConditions** (enum: "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Omit to disable throttling.
 - **userAgent** (string) _(optional)_: User agent to [`emulate`](#emulate). Set to empty string to clear the user agent override.
diff --git a/src/McpContext.ts b/src/McpContext.ts
index 79440aa2a..a77bc06bc 100644
--- a/src/McpContext.ts
+++ b/src/McpContext.ts
@@ -301,7 +301,7 @@ export class McpContext implements Context {
       userAgent?: string;
       colorScheme?: 'dark' | 'light' | 'auto';
       viewport?: Viewport;
-      extraHTTPHeaders?: Record<string, string> | null | undefined;
+      extraHttpHeaders?: Record<string, string> | undefined;
     },
     targetPage?: Page,
   ): Promise<void> {
@@ -380,15 +380,11 @@ export class McpContext implements Context {
       newSettings.viewport = viewport;
     }
 
-    if (options.extraHTTPHeaders !== undefined) {
-      if (options.extraHTTPHeaders === null) {
-        // Clear headers when null (from empty string)
-        await page.setExtraHTTPHeaders({});
-        delete newSettings.extraHTTPHeaders;
-      } else {
-        // Set headers when we have an object
-        await page.setExtraHTTPHeaders(options.extraHTTPHeaders);
-        newSettings.extraHTTPHeaders = options.extraHTTPHeaders;
+    if (options.extraHttpHeaders !== undefined) {
+      await page.setExtraHTTPHeaders(options.extraHttpHeaders);
+      newSettings.extraHttpHeaders = options.extraHttpHeaders;
+      if (Object.keys(options.extraHttpHeaders).length === 0) {
+        delete newSettings.extraHttpHeaders;
       }
     }
 
diff --git a/src/bin/chrome-devtools-cli-options.ts b/src/bin/chrome-devtools-cli-options.ts
index faf1c6a97..af92dccd5 100644
--- a/src/bin/chrome-devtools-cli-options.ts
+++ b/src/bin/chrome-devtools-cli-options.ts
@@ -167,8 +167,8 @@ export const commands: Commands = {
           "Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.",
         required: false,
       },
-      extraHTTPHeaders: {
-        name: 'extraHTTPHeaders',
+      extraHttpHeaders: {
+        name: 'extraHttpHeaders',
         type: 'string',
         description:
           'Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.',
diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index 5c49bd80e..a9aff13c2 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -86,9 +86,15 @@
         "name": "viewport_length",
         "argType": "number"
       },
+      {
+        "name": "extra_http_headers_length",
+        "argType": "number",
+        "isDeprecated": true
+      },
       {
         "name": "extra_h_t_t_p_headers_length",
-        "argType": "number"
+        "argType": "number",
+        "isDeprecated": true
       }
     ]
   },
diff --git a/src/tools/emulation.ts b/src/tools/emulation.ts
index 36ba95faa..519ad5a10 100644
--- a/src/tools/emulation.ts
+++ b/src/tools/emulation.ts
@@ -16,12 +16,12 @@ import {
 
 function headerStringTransform(
   value: string | undefined,
-): Record<string, string> | null | undefined {
+): Record<string, string> | undefined {
   if (value === undefined) {
     return undefined;
   }
   if (value === '') {
-    return null;
+    return {};
   }
   try {
     const parsed = JSON.parse(value);
@@ -91,7 +91,7 @@ export const emulate = definePageTool({
       .describe(
         `Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`,
       ),
-    extraHTTPHeaders: zod
+    extraHttpHeaders: zod
       .string()
       .optional()
       .transform(headerStringTransform)
diff --git a/src/types.ts b/src/types.ts
index c7246d796..2107b558f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -31,5 +31,5 @@ export interface EmulationSettings {
   userAgent?: string;
   colorScheme?: 'dark' | 'light';
   viewport?: Viewport;
-  extraHTTPHeaders?: Record<string, string>;
+  extraHttpHeaders?: Record<string, string>;
 }
diff --git a/tests/tools/emulation.test.ts b/tests/tools/emulation.test.ts
index bbaca45a9..84a3b7828 100644
--- a/tests/tools/emulation.test.ts
+++ b/tests/tools/emulation.test.ts
@@ -572,7 +572,7 @@ describe('emulation', () => {
     });
   });
 
-  describe('extraHTTPHeaders', () => {
+  describe('extraHttpHeaders', () => {
     it('sets extra headers on requests', async () => {
       let receivedHeaders: IncomingHttpHeaders = {};
       server.addRoute('/headers-test', async (req, res) => {
@@ -586,7 +586,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: {'X-Custom-Header': 'test-value'},
+              extraHttpHeaders: {'X-Custom-Header': 'test-value'},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -613,7 +613,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: {'X-To-Clear': 'value'},
+              extraHttpHeaders: {'X-To-Clear': 'value'},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -625,7 +625,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: null,
+              extraHttpHeaders: {},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -636,7 +636,7 @@ describe('emulation', () => {
         await page.goto(server.getRoute('/headers-clear'));
         assert.strictEqual(receivedHeaders['x-to-clear'], undefined);
         assert.strictEqual(
-          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          context.getSelectedMcpPage().emulationSettings.extraHttpHeaders,
           undefined,
         );
       });
@@ -660,7 +660,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: {'X-Persist': 'yes'},
+              extraHttpHeaders: {'X-Persist': 'yes'},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -694,7 +694,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: {'X-Test': 'value'},
+              extraHttpHeaders: {'X-Test': 'value'},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -703,7 +703,7 @@ describe('emulation', () => {
         );
 
         const settings = context.getSelectedMcpPage().emulationSettings;
-        assert.deepStrictEqual(settings.extraHTTPHeaders, {
+        assert.deepStrictEqual(settings.extraHttpHeaders, {
           'X-Test': 'value',
         });
       });
@@ -714,7 +714,7 @@ describe('emulation', () => {
         await emulate.handler(
           {
             params: {
-              extraHTTPHeaders: {'X-Page': 'one'},
+              extraHttpHeaders: {'X-Page': 'one'},
             },
             page: context.getSelectedMcpPage(),
           },
@@ -723,7 +723,7 @@ describe('emulation', () => {
         );
 
         assert.deepStrictEqual(
-          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          context.getSelectedMcpPage().emulationSettings.extraHttpHeaders,
           {'X-Page': 'one'},
         );
 
@@ -731,7 +731,7 @@ describe('emulation', () => {
         context.selectPage(page);
 
         assert.strictEqual(
-          context.getSelectedMcpPage().emulationSettings.extraHTTPHeaders,
+          context.getSelectedMcpPage().emulationSettings.extraHttpHeaders,
           undefined,
         );
       });

From a8bfa567c70e40fc37b832b347f4a24e429b0f46 Mon Sep 17 00:00:00 2001
From: Nicholas Roscino <nroscino@google.com>
Date: Wed, 20 May 2026 11:12:13 +0200
Subject: [PATCH 5/6] chore: fix tool_call_metrics file

---
 src/telemetry/tool_call_metrics.json | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/src/telemetry/tool_call_metrics.json b/src/telemetry/tool_call_metrics.json
index a9aff13c2..597bfa7a3 100644
--- a/src/telemetry/tool_call_metrics.json
+++ b/src/telemetry/tool_call_metrics.json
@@ -88,13 +88,7 @@
       },
       {
         "name": "extra_http_headers_length",
-        "argType": "number",
-        "isDeprecated": true
-      },
-      {
-        "name": "extra_h_t_t_p_headers_length",
-        "argType": "number",
-        "isDeprecated": true
+        "argType": "number"
       }
     ]
   },

From 1100e6fc0eaca789d7ba4a42e7889a1141f9052d Mon Sep 17 00:00:00 2001
From: Nicholas Roscino <nroscino@google.com>
Date: Wed, 20 May 2026 11:16:03 +0200
Subject: [PATCH 6/6] chore: merge main

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 80647b2cc..b17b72451 100644
--- a/README.md
+++ b/README.md
@@ -249,7 +249,7 @@ and the expert guidance it needs to use them effectively.
 
 1.  Open the **Command Palette** (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux).
 2.  Search for and run the **Chat: Install Plugin From Source** command.
-3.  Paste in our repository URL: `https://github.com/ChromeDevTools/chrome-devtools-mcp`
+3.  Paste in our repository name: `ChromeDevTools/chrome-devtools-mcp`.
 
 That's it! Your agent is now supercharged with Chrome DevTools capabilities.