feat: make pageId routing always-on

README.md

@@ -596,9 +596,10 @@ The Chrome DevTools MCP server supports the following configuration option:
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
 
-- **`--experimentalPageIdRouting`/ `--experimental-page-id-routing`**
-  Whether to expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions).
+- **`--pageIdRouting`/ `--page-id-routing`**
+  Expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions). Use --no-page-id-routing to disable.
   - **Type:** boolean
+  - **Default:** `true`
 
 - **`--experimentalDevtools`/ `--experimental-devtools`**
   Whether to enable automation over DevTools targets

docs/tool-reference.md

@@ -66,6 +66,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
 - **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
@@ -79,6 +80,7 @@
 **Parameters:**
 
 - **from_uid** (string) **(required)**: The uid of the element to [`drag`](#drag)
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **to_uid** (string) **(required)**: The uid of the element to drop into
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
 
@@ -90,6 +92,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
 - **value** (string) **(required)**: The value to [`fill`](#fill) in. "true" or "false" for checkboxes and toggles, "true" for radio buttons.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
@@ -103,6 +106,7 @@
 **Parameters:**
 
 - **elements** (array) **(required)**: Elements from snapshot to [`fill`](#fill) out.
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
 
 ---
@@ -114,6 +118,7 @@
 **Parameters:**
 
 - **action** (enum: "accept", "dismiss") **(required)**: Whether to dismiss or accept the dialog
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **promptText** (string) _(optional)_: Optional prompt text to enter into the dialog.
 
 ---
@@ -124,6 +129,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
 
@@ -136,6 +142,7 @@
 **Parameters:**
 
 - **key** (string) **(required)**: A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
 
 ---
@@ -146,6 +153,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **text** (string) **(required)**: The text to type
 - **submitKey** (string) _(optional)_: Optional key to press after typing. E.g., "Enter", "Tab", "Escape"
 
@@ -158,6 +166,7 @@
 **Parameters:**
 
 - **filePath** (string) **(required)**: The local path of the file to upload
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **uid** (string) **(required)**: The uid of the file input element or an element that will open file chooser on the page from the page content snapshot
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
 
@@ -169,6 +178,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **x** (number) **(required)**: The x coordinate
 - **y** (number) **(required)**: The y coordinate
 - **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.
@@ -202,6 +212,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **handleBeforeUnload** (enum: "accept", "decline") _(optional)_: Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.
 - **ignoreCache** (boolean) _(optional)_: Whether to ignore cache on reload.
 - **initScript** (string) _(optional)_: A JavaScript script to be executed on each new document before any other scripts for the next navigation.
@@ -241,6 +252,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **text** (array) **(required)**: Non-empty list of texts. Resolves when any value appears on the page.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
@@ -254,6 +266,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **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.
@@ -271,6 +284,7 @@
 **Parameters:**
 
 - **height** (number) **(required)**: Page height
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **width** (number) **(required)**: Page width
 
 ---
@@ -285,6 +299,7 @@
 
 - **insightName** (string) **(required)**: The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"
 - **insightSetId** (string) **(required)**: The id for the specific insight set. Only use the ids given in the "Available insight sets" list.
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---
 
@@ -294,6 +309,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **autoStop** (boolean) _(optional)_: Determines if the trace recording should be automatically stopped.
 - **filePath** (string) _(optional)_: 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).
 - **reload** (boolean) _(optional)_: 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`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
@@ -306,6 +322,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **filePath** (string) _(optional)_: 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).
 
 ---
@@ -318,6 +335,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **reqid** (number) _(optional)_: The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.
 - **requestFilePath** (string) _(optional)_: The absolute or relative path to a .network-request file to save the request body to. If omitted, the body is returned inline.
 - **responseFilePath** (string) _(optional)_: The absolute or relative path to a .network-response file to save the response body to. If omitted, the body is returned inline.
@@ -330,6 +348,7 @@
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **includePreservedRequests** (boolean) _(optional)_: Set to true to return the preserved requests over the last 3 navigations.
 - **pageIdx** (integer) _(optional)_: Page number to return (0-based). When omitted, returns the first page.
 - **pageSize** (integer) _(optional)_: Maximum number of requests to return. When omitted, returns all requests.
@@ -369,6 +388,7 @@ so returned values have to be JSON-serializable.
 **Parameters:**
 
 - **msgid** (number) **(required)**: The msgid of a console message on the page from the listed console messages
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---
 
@@ -378,6 +398,7 @@ so returned values have to be JSON-serializable.
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **device** (enum: "desktop", "mobile") _(optional)_: Device to [`emulate`](#emulate).
 - **mode** (enum: "navigation", "snapshot") _(optional)_: "navigation" reloads & audits. "snapshot" analyzes current state.
 - **outputDirPath** (string) _(optional)_: Directory for reports. If omitted, uses temporary files.
@@ -390,6 +411,7 @@ so returned values have to be JSON-serializable.
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **includePreservedMessages** (boolean) _(optional)_: Set to true to return the preserved messages over the last 3 navigations.
 - **pageIdx** (integer) _(optional)_: Page number to return (0-based). When omitted, returns the first page.
 - **pageSize** (integer) _(optional)_: Maximum number of messages to return. When omitted, returns all messages.
@@ -403,6 +425,7 @@ so returned values have to be JSON-serializable.
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.
 - **format** (enum: "png", "jpeg", "webp") _(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.
@@ -419,6 +442,7 @@ in the DevTools Elements panel (if any).
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.
 - **verbose** (boolean) _(optional)_: Whether to include all possible information available in the full a11y tree. Default is false.
 
@@ -430,6 +454,7 @@ in the DevTools Elements panel (if any).
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **filePath** (string) _(optional)_: Output file path (.webm,.mp4 are supported). Uses mkdtemp to generate a unique path if not provided.
 
 ---
@@ -438,7 +463,9 @@ in the DevTools Elements panel (if any).
 
 **Description:** Stops the active screencast recording on the selected page. (requires flag: --experimentalScreencast=true)
 
-**Parameters:** None
+**Parameters:**
+
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---
 
@@ -451,6 +478,7 @@ in the DevTools Elements panel (if any).
 **Parameters:**
 
 - **filePath** (string) **(required)**: A path to a .heapsnapshot file to save the heapsnapshot to.
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---
 
@@ -564,6 +592,7 @@ in the DevTools Elements panel (if any).
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **toolName** (string) **(required)**: The name of the tool to execute
 - **params** (string) _(optional)_: The JSON-stringified parameters to pass to the tool
 
@@ -579,7 +608,9 @@ following command to the script:
 This might be helpful when the third-party developer tools return non-serializable values or when composing
 third-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)
 
-**Parameters:** None
+**Parameters:**
+
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---
 
@@ -593,6 +624,7 @@ third-party developer tools with additional functionality. (requires flag: --cat
 
 **Parameters:**
 
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 - **toolName** (string) **(required)**: The name of the WebMCP tool to execute
 - **input** (string) _(optional)_: The JSON-stringified parameters to pass to the WebMCP tool
 
@@ -602,6 +634,8 @@ third-party developer tools with additional functionality. (requires flag: --cat
 
 **Description:** Lists all WebMCP tools the page exposes. (requires flag: --categoryExperimentalWebmcp=true)
 
-**Parameters:** None
+**Parameters:**
+
+- **pageId** (number) **(required)**: Targets a specific page by ID.
 
 ---

scripts/eval_scenarios/page_focus_keyboard_test.ts

@@ -9,7 +9,6 @@ import assert from 'node:assert';
 import type {TestScenario} from '../eval_gemini.ts';
 
 export const scenario: TestScenario = {
-  serverArgs: ['--experimental-page-id-routing'],
   prompt: `Open two pages in the same isolated context "session":
 - Page 1 at data:text/html,<textarea id="ta"></textarea>
 - Page 2 at data:text/html,<h1>Other</h1>

scripts/eval_scenarios/page_id_routing_test.ts

@@ -9,7 +9,6 @@ import assert from 'node:assert';
 import type {TestScenario} from '../eval_gemini.ts';
 
 export const scenario: TestScenario = {
-  serverArgs: ['--experimental-page-id-routing'],
   prompt: `Open two new pages in isolated contexts:
 - Page A (isolatedContext "contextA") at data:text/html,<button>Click A</button>
 - Page B (isolatedContext "contextB") at data:text/html,<button>Click B</button>

scripts/generate-docs.ts

@@ -16,6 +16,7 @@ import {
   OFF_BY_DEFAULT_CATEGORIES,
   labels,
 } from '../build/src/tools/categories.js';
+import {pageIdSchema} from '../build/src/tools/ToolDefinition.js';
 import {createTools} from '../build/src/tools/tools.js';
 
 const OUTPUT_PATH = './docs/tool-reference.md';
@@ -434,7 +435,7 @@ async function generateReference(
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function getToolsAndCategories(tools: any) {
+function getToolsAndCategories(tools: any, slim = false) {
   // Convert ToolDefinitions to ToolWithAnnotations
   const toolsWithAnnotations: ToolWithAnnotations[] = tools
     .filter(tool => {
@@ -455,8 +456,12 @@ function getToolsAndCategories(tools: any) {
       const properties: Record<string, TypeInfo> = {};
       const required: string[] = [];
 
+      const toolSchema = {
+        ...tool.schema,
+        ...(tool.pageScoped && !slim ? pageIdSchema : {}),
+      };
       for (const [key, schema] of Object.entries(
-        tool.schema as unknown as Record<string, ZodSchema>,
+        toolSchema as unknown as Record<string, ZodSchema>,
       )) {
         const info = getZodTypeInfo(schema);
         properties[key] = info;
@@ -536,7 +541,10 @@ async function generateToolDocumentation(): Promise<void> {
 
     {
       const {toolsWithAnnotations, categories, sortedCategories} =
-        getToolsAndCategories(createTools({slim: true} as ParsedArguments));
+        getToolsAndCategories(
+          createTools({slim: true} as ParsedArguments),
+          true,
+        );
       await generateReference(
         'Chrome DevTools MCP Slim Tool Reference',
         SLIM_OUTPUT_PATH,

src/ToolHandler.ts

@@ -161,7 +161,7 @@ export class ToolHandler {
     this.inputSchema =
       'pageScoped' in tool &&
       tool.pageScoped &&
-      serverArgs.experimentalPageIdRouting &&
+      serverArgs.pageIdRouting &&
       !serverArgs.slim
         ? {...tool.schema, ...pageIdSchema}
         : tool.schema;
@@ -224,7 +224,7 @@ export class ToolHandler {
           const pageId =
             typeof params.pageId === 'number' ? params.pageId : undefined;
           const page =
-            this.serverArgs.experimentalPageIdRouting &&
+            this.serverArgs.pageIdRouting &&
             pageId !== undefined &&
             !this.serverArgs.slim
               ? context.getPageById(pageId)