Add extension-backed unique page tools

README.md

@@ -487,12 +487,14 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`press_key`](docs/tool-reference.md#press_key)
   - [`type_text`](docs/tool-reference.md#type_text)
   - [`upload_file`](docs/tool-reference.md#upload_file)
-- **Navigation automation** (6 tools)
+- **Navigation automation** (8 tools)
   - [`close_page`](docs/tool-reference.md#close_page)
   - [`list_pages`](docs/tool-reference.md#list_pages)
+  - [`list_unique_pages`](docs/tool-reference.md#list_unique_pages)
   - [`navigate_page`](docs/tool-reference.md#navigate_page)
   - [`new_page`](docs/tool-reference.md#new_page)
   - [`select_page`](docs/tool-reference.md#select_page)
+  - [`select_unique_page`](docs/tool-reference.md#select_unique_page)
   - [`wait_for`](docs/tool-reference.md#wait_for)
 - **Emulation** (2 tools)
   - [`emulate`](docs/tool-reference.md#emulate)

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
-# Chrome DevTools MCP Tool Reference (~7005 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~7304 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
@@ -12,12 +12,14 @@
   - [`press_key`](#press_key)
   - [`type_text`](#type_text)
   - [`upload_file`](#upload_file)
-- **[Navigation automation](#navigation-automation)** (6 tools)
+- **[Navigation automation](#navigation-automation)** (8 tools)
   - [`close_page`](#close_page)
   - [`list_pages`](#list_pages)
+  - [`list_unique_pages`](#list_unique_pages)
   - [`navigate_page`](#navigate_page)
   - [`new_page`](#new_page)
   - [`select_page`](#select_page)
+  - [`select_unique_page`](#select_unique_page)
   - [`wait_for`](#wait_for)
 - **[Emulation](#emulation)** (2 tools)
   - [`emulate`](#emulate)
@@ -164,6 +166,14 @@
 
 ---
 
+### `list_unique_pages`
+
+**Description:** Get a list of pages open in the browser enriched with Chrome tabId identity from the tab-ID extension when available.
+
+**Parameters:** None
+
+---
+
 ### `navigate_page`
 
 **Description:** Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.
@@ -203,6 +213,17 @@
 
 ---
 
+### `select_unique_page`
+
+**Description:** Select a page using its Chrome tabId as reported by the tab-ID extension.
+
+**Parameters:**
+
+- **tabId** (number) **(required)**: The Chrome tabId to select. Call [`list_unique_pages`](#list_unique_pages) to find available tab IDs.
+- **bringToFront** (boolean) _(optional)_: Whether to focus the page and bring it to the top.
+
+---
+
 ### `wait_for`
 
 **Description:** Wait for the specified text to appear on the selected page.

src/McpResponse.ts

@@ -33,6 +33,7 @@ import type {
   LighthouseData,
   Response,
   SnapshotParams,
+  UniquePageData,
 } from './tools/ToolDefinition.js';
 import type {InsightName, TraceResult} from './trace-processing/parse.js';
 import {getInsightOutput, getTraceSummary} from './trace-processing/parse.js';
@@ -197,6 +198,7 @@ export class McpResponse implements Response {
   #listWebMcpTools?: boolean;
   #devToolsData?: DevToolsData;
   #tabId?: string;
+  #uniquePages?: UniquePageData[];
   #args: ParsedArguments;
   #page?: McpPage;
   #redactNetworkHeaders = true;
@@ -221,6 +223,10 @@ export class McpResponse implements Response {
     this.#tabId = tabId;
   }
 
+  setUniquePages(uniquePages: UniquePageData[]): void {
+    this.#uniquePages = uniquePages;
+  }
+
   setIncludePages(value: boolean): void {
     this.#includePages = value;
 
@@ -698,6 +704,7 @@ export class McpResponse implements Response {
         defaultValue?: string;
       };
       pages?: object[];
+      uniquePages?: object[];
       pagination?: object;
       heapSnapshot?: {
         stats?: object;
@@ -838,6 +845,30 @@ Call ${handleDialog.name} to handle it before continuing.`);
       structuredContent.tabId = this.#tabId;
     }
 
+    if (this.#uniquePages) {
+      if (this.#uniquePages.length) {
+        response.push('## Unique Pages');
+        for (const page of this.#uniquePages) {
+          const parts = [
+            `${page.pageId}:`,
+            `status=${page.identityStatus}`,
+            `tabId=${page.tabId ?? 'null'}`,
+            page.url,
+          ];
+          if (page.selected) {
+            parts.push('[selected]');
+          }
+          if (page.error) {
+            parts.push(`error="${page.error}"`);
+          }
+          response.push(parts.join(' '));
+        }
+      } else {
+        response.push('No pages found.');
+      }
+      structuredContent.uniquePages = this.#uniquePages;
+    }
+
     if (data.traceSummary) {
       const summary = getTraceSummary(data.traceSummary);
       response.push(summary);

src/bin/cliDefinitions.ts

@@ -380,6 +380,12 @@ export const commands: Commands = {
     category: 'Navigation automation',
     args: {},
   },
+  list_unique_pages: {
+    description:
+      'Get a list of pages open in the browser enriched with Chrome tabId identity from the tab-ID extension when available.',
+    category: 'Navigation automation',
+    args: {},
+  },
   navigate_page: {
     description:
       'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
@@ -587,6 +593,26 @@ export const commands: Commands = {
       },
     },
   },
+  select_unique_page: {
+    description:
+      'Select a page using its Chrome tabId as reported by the tab-ID extension.',
+    category: 'Navigation automation',
+    args: {
+      tabId: {
+        name: 'tabId',
+        type: 'number',
+        description:
+          'The Chrome tabId to select. Call list_unique_pages to find available tab IDs.',
+        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 heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.',

src/telemetry/tool_call_metrics.json

@@ -586,5 +586,22 @@
         "argType": "number"
       }
     ]
+  },
+  {
+    "name": "list_unique_pages",
+    "args": []
+  },
+  {
+    "name": "select_unique_page",
+    "args": [
+      {
+        "name": "tab_id",
+        "argType": "number"
+      },
+      {
+        "name": "bring_to_front",
+        "argType": "boolean"
+      }
+    ]
   }
 ]

src/tools/ToolDefinition.ts

@@ -99,6 +99,27 @@ export interface DevToolsData {
   cdpBackendNodeId?: number;
 }
 
+export type UniquePageIdentityStatus =
+  | 'resolved'
+  | 'extension_unavailable'
+  | 'unsupported_page'
+  | 'script_failed'
+  | 'no_tab_context';
+
+export interface UniquePageData {
+  pageId: number;
+  tabId: number | null;
+  selected: boolean;
+  url: string;
+  title: string;
+  identityStatus: UniquePageIdentityStatus;
+  uid?: string;
+  windowId?: number;
+  tabIndex?: number;
+  tabNumber?: number;
+  error?: string;
+}
+
 export interface Response {
   appendResponseLine(value: string): void;
   setHeapSnapshotAggregates(
@@ -138,6 +159,7 @@ export interface Response {
   // Allows re-using DevTools data queried by some tools.
   attachDevToolsData(data: DevToolsData): void;
   setTabId(tabId: string): void;
+  setUniquePages(uniquePages: UniquePageData[]): void;
   attachTraceSummary(trace: TraceResult): void;
   attachTraceInsight(
     trace: TraceResult,
@@ -222,6 +244,11 @@ export type Context = Readonly<{
   listExtensions(): Promise<Map<string, Extension>>;
   getExtension(id: string): Promise<Extension | undefined>;
   getSelectedMcpPage(): McpPage;
+  createPagesSnapshot(): Promise<Page[]>;
+  getPages(): Page[];
+  getPageId(page: Page): number | undefined;
+  isPageSelected(page: Page): boolean;
+  getIsolatedContextName(page: Page): string | undefined;
   getExtensionServiceWorkers(): ExtensionServiceWorker[];
   getExtensionServiceWorkerId(
     extensionServiceWorker: ExtensionServiceWorker,