feat: make pageId routing always-on and fix waitForEventsAfterAction page isolation

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6940 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~8190 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
@@ -193,7 +193,7 @@
 
 ### `select_page`
 
-**Description:** Select a page as a context for future tool calls.
+**Description:** Select a page as a context for future tool calls. For multi-agent workflows, prefer passing pageId directly to each tool instead of using [`select_page`](#select_page).
 
 **Parameters:**
 
@@ -333,6 +333,7 @@ so returned values have to be JSON-serializable.
 }`
 
 - **args** (array) _(optional)_: An optional list of arguments to pass to the function.
+- **pageId** (number) _(optional)_: Targets a specific page by ID. Use [`list_pages`](#list_pages) to get available page IDs. If omitted, operates on the most recently selected page.
 
 ---
 

src/McpContext.ts

@@ -851,9 +851,11 @@ export class McpContext implements Context {
 
   waitForEventsAfterAction(
     action: () => Promise<unknown>,
-    options?: {timeout?: number},
+    options?: {timeout?: number; page?: McpPage},
   ): Promise<void> {
-    const page = this.#getSelectedMcpPage();
+    const page = options?.page
+      ? this.#getMcpPage(options.page.pptrPage)
+      : this.#getSelectedMcpPage();
     const cpuMultiplier = page.cpuThrottlingRate;
     const networkMultiplier = getNetworkMultiplierFromString(
       page.networkConditions,

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -150,7 +150,7 @@ export const cliOptions = {
   experimentalPageIdRouting: {
     type: 'boolean',
     describe:
-      'Whether to expose pageId on page-scoped tools and route requests by page ID.',
+      '(Deprecated, now always enabled) pageId is always exposed on page-scoped tools.',
     hidden: true,
   },
   experimentalDevtools: {

src/bin/cliDefinitions.ts

@@ -47,6 +47,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   close_page: {
@@ -86,6 +93,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   emulate: {
@@ -135,6 +149,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,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   evaluate_script: {
@@ -155,6 +176,13 @@ export const commands: Commands = {
         description: 'An optional list of arguments to pass to the function.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   fill: {
@@ -182,6 +210,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   get_console_message: {
@@ -196,6 +231,13 @@ export const commands: Commands = {
           'The msgid of a console message on the page from the listed console messages',
         required: true,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   get_network_request: {
@@ -224,6 +266,13 @@ export const commands: Commands = {
           'The absolute or relative path to save the response body to. If omitted, the body is returned inline.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   handle_dialog: {
@@ -244,6 +293,13 @@ export const commands: Commands = {
         description: 'Optional prompt text to enter into the dialog.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   hover: {
@@ -264,6 +320,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   lighthouse_audit: {
@@ -294,6 +357,13 @@ export const commands: Commands = {
         description: 'Directory for reports. If omitted, uses temporary files.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   list_console_messages: {
@@ -330,6 +400,13 @@ export const commands: Commands = {
         required: false,
         default: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   list_network_requests: {
@@ -366,12 +443,27 @@ export const commands: Commands = {
         required: false,
         default: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   list_pages: {
     description: 'Get a list of pages  open in the browser.',
     category: 'Navigation automation',
-    args: {},
+    args: {
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
+    },
   },
   navigate_page: {
     description:
@@ -420,6 +512,13 @@ export const commands: Commands = {
           'Maximum wait time in milliseconds. If set to 0, the default timeout will be used.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   new_page: {
@@ -475,6 +574,13 @@ export const commands: Commands = {
           'The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"',
         required: true,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   performance_start_trace: {
@@ -505,6 +611,13 @@ export const commands: Commands = {
           '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,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   performance_stop_trace: {
@@ -519,6 +632,13 @@ export const commands: Commands = {
           '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,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   press_key: {
@@ -540,6 +660,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   resize_page: {
@@ -559,10 +686,18 @@ export const commands: Commands = {
         description: 'Page height',
         required: true,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   select_page: {
-    description: 'Select a page as a context for future tool calls.',
+    description:
+      'Select a page as a context for future tool calls. For multi-agent workflows, prefer passing pageId directly to each tool instead of using select_page.',
     category: 'Navigation automation',
     args: {
       pageId: {
@@ -592,6 +727,13 @@ export const commands: Commands = {
           'A path to a .heapsnapshot file to save the heapsnapshot to.',
         required: true,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   take_screenshot: {
@@ -635,6 +777,13 @@ export const commands: Commands = {
           '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,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   take_snapshot: {
@@ -656,6 +805,13 @@ export const commands: Commands = {
           '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,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   type_text: {
@@ -675,6 +831,13 @@ export const commands: Commands = {
           'Optional key to press after typing. E.g., "Enter", "Tab", "Escape"',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
   upload_file: {
@@ -701,6 +864,13 @@ export const commands: Commands = {
           'Whether to include a snapshot in the response. Default is false.',
         required: false,
       },
+      pageId: {
+        name: 'pageId',
+        type: 'number',
+        description:
+          'Targets a specific page by ID. Use list_pages to get available page IDs. If omitted, operates on the most recently selected page.',
+        required: false,
+      },
     },
   },
 } as const;