opera-devtools-mcp 0.6.0 → 0.7.0

package/build/src/third_party/issue-descriptions/federatedAuthRequestAccountsBlockedByConnectionAllowlist.md

@@ -0,0 +1 @@
+# Fetching the provider's accounts list was blocked by the request's initiator's connection allowlists.

package/build/src/third_party/issue-descriptions/federatedAuthRequestConfigBlockedByConnectionAllowlist.md

@@ -0,0 +1 @@
+# Fetching the provider's FedCM manifest configuration was blocked by the request's initiator's connection allowlists.

package/build/src/third_party/issue-descriptions/federatedAuthRequestIdTokenBlockedByConnectionAllowlist.md

@@ -0,0 +1 @@
+# Fetching the provider's token was blocked by the request's initiator's connection allowlists.

package/build/src/third_party/issue-descriptions/federatedAuthRequestWellKnownBlockedByConnectionAllowlist.md

@@ -0,0 +1 @@
+# Fetching the provider's well-known file was blocked by the request's initiator's connection allowlists.

package/build/src/tools/ToolDefinition.js

@@ -53,6 +53,15 @@ export function viewportTransform(arg) {
     const hasTouch = tags.includes('touch');
     const isLandscape = tags.includes('landscape');
     const [width, height, dpr] = dimensions.split('x').map(Number);
+    if (!Number.isFinite(width) || width <= 0) {
+        throw new Error(`Invalid viewport width "${width}". Expected format '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]' with a positive width.`);
+    }
+    if (!Number.isFinite(height) || height <= 0) {
+        throw new Error(`Invalid viewport height "${height}". Expected format '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]' with a positive height.`);
+    }
+    if (dpr !== undefined && (!Number.isFinite(dpr) || dpr <= 0)) {
+        throw new Error(`Invalid devicePixelRatio "${dpr}". Expected a positive number.`);
+    }
     return {
         width,
         height,
@@ -67,6 +76,12 @@ export function geolocationTransform(arg) {
         return undefined;
     }
     const [latitude, longitude] = arg.split(',').map(Number);
+    if (!Number.isFinite(latitude) || latitude < -90 || latitude > 90) {
+        throw new Error(`Invalid latitude "${latitude}". Latitude must be a number between -90 and 90.`);
+    }
+    if (!Number.isFinite(longitude) || longitude < -180 || longitude > 180) {
+        throw new Error(`Invalid longitude "${longitude}". Longitude must be a number between -180 and 180.`);
+    }
     return {
         latitude,
         longitude,

package/build/src/tools/categories.js

@@ -32,10 +32,4 @@ export const labels = {
     [ToolCategory.OPERA]: 'Opera',
     [ToolCategory.PWA]: 'Progressive Web Apps',
 };
-export const OFF_BY_DEFAULT_CATEGORIES = [
-    ToolCategory.EXTENSIONS,
-    ToolCategory.THIRD_PARTY,
-    ToolCategory.WEBMCP,
-    ToolCategory.PWA,
-];
 //# sourceMappingURL=categories.js.map

package/build/src/tools/comments.js

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+export const openDevtools = definePageTool({
+    name: 'open_devtools',
+    description: 'Open a DevTools window for the selected page.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: [],
+    handler: async () => {
+        throw new Error('Not implemented');
+    },
+});
+export const getDevtoolsComments = definePageTool({
+    name: 'get_devtools_comments',
+    description: 'Retrieve user comments from the DevTools window for the page.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async () => {
+        throw new Error('Not implemented');
+    },
+});
+export const resolveDevtoolsComment = definePageTool({
+    name: 'resolve_devtools_comment',
+    description: 'Append an agent reply to a DevTools comment thread and mark it as resolved.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {
+        threadId: zod
+            .string()
+            .describe('The unique identifier of the comment thread to resolve (e.g. "comment-1").'),
+        replyText: zod
+            .string()
+            .optional()
+            .describe('Optional reply explanation from the AI agent to append to the resolved comment thread.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async () => {
+        throw new Error('Not implemented');
+    },
+});
+export const revealInDevtools = definePageTool({
+    name: 'reveal_in_devtools',
+    description: 'Navigate DevTools to a specified panel and highlight a target DOM node or network request. The parameters uid and reqid are mutually exclusive.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {
+        panelName: zod
+            .string()
+            .optional()
+            .describe('The target DevTools panel (e.g. "elements", "network", "sources", "console").'),
+        uid: zod
+            .string()
+            .optional()
+            .describe('Optional snapshot element UID to reveal in the Elements panel.'),
+        reqid: zod
+            .number()
+            .optional()
+            .describe('Optional network request ID to reveal in the Network panel.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async () => {
+        throw new Error('Not implemented');
+    },
+});
+//# sourceMappingURL=comments.js.map

package/build/src/tools/console.js

@@ -32,7 +32,7 @@ const LIST_CONSOLE_MESSAGES_TOOL_NAME = 'list_console_messages';
 export const listConsoleMessages = definePageTool(cliArgs => {
     return {
         name: LIST_CONSOLE_MESSAGES_TOOL_NAME,
-        description: `List all console messages for the currently selected page since the last navigation.${cliArgs?.categoryExtensions ? ' This includes console messages originating from extensions content scripts.' : ''}`,
+        description: `List all console messages for the target page since the last navigation.${cliArgs?.categoryExtensions ? ' This includes console messages originating from extensions content scripts.' : ''}`,
         annotations: {
             category: ToolCategory.DEBUGGING,
             readOnlyHint: true,

package/build/src/tools/emulation.js

@@ -33,7 +33,7 @@ const throttlingOptions = [
 ];
 export const emulate = definePageTool({
     name: 'emulate',
-    description: `Emulates various features on the selected page.`,
+    description: `Emulates various features on the target page.`,
     annotations: {
         category: ToolCategory.EMULATION,
         readOnlyHint: false,

package/build/src/tools/extensions.js

@@ -20,7 +20,7 @@ export const installExtension = defineTool({
     },
     blockedByDialog: false,
     verifyFilesSchema: {
-        path: true,
+        path: { local: true },
     },
     handler: async (request, response, context) => {
         const { path } = request.params;

package/build/src/tools/memory.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { zod } from '../third_party/index.js';
+import { byteSizeRangeSchema } from '../utils/bytes.js';
 import { ToolCategory } from './categories.js';
 import { definePageTool, defineTool } from './ToolDefinition.js';
 const HEAP_SNAPSHOT_FILTERS = [
@@ -17,7 +18,7 @@ const HEAP_SNAPSHOT_FILTERS = [
 ];
 export const takeHeapSnapshot = definePageTool({
     name: 'take_heapsnapshot',
-    description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
+    description: `Capture a heap snapshot of the target page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
     annotations: {
         category: ToolCategory.MEMORY,
         readOnlyHint: false,
@@ -239,10 +240,7 @@ export const getHeapSnapshotEdges = defineTool({
             .enum(['retainedSize', 'selfSize', 'name'])
             .optional()
             .describe('Sort order for edges. Default is retainedSize.'),
-        minRetainedSize: zod
-            .number()
-            .optional()
-            .describe('Minimum retained size in bytes for target nodes.'),
+        retainedSize: byteSizeRangeSchema('Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.').optional(),
         excludePrimitives: zod
             .boolean()
             .optional()
@@ -253,7 +251,8 @@ export const getHeapSnapshotEdges = defineTool({
     handler: async (request, response, context) => {
         const edges = await context.getHeapSnapshotEdges(request.params.filePath, request.params.nodeId, {
             sortBy: request.params.sortBy ?? 'retainedSize',
-            minRetainedSize: request.params.minRetainedSize,
+            // DevTools currently only supports a lower retained-size bound here.
+            minRetainedSize: request.params.retainedSize?.min,
             excludePrimitives: request.params.excludePrimitives ?? true,
         });
         response.setHeapSnapshotNodes(edges, {
@@ -367,4 +366,59 @@ export const getHeapSnapshotObjectDetails = defineTool({
         response.setHeapSnapshotObjectDetails(objectInfo);
     },
 });
+export const queryHeapSnapshotObjects = defineTool({
+    name: 'query_heapsnapshot_objects',
+    description: 'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy).',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: { filePath: true },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        className: zod
+            .string()
+            .optional()
+            .describe('Optional regex or text matching object class name.'),
+        propertyName: zod
+            .string()
+            .optional()
+            .describe('Optional property name filter for outgoing reference edges.'),
+        nodeType: zod
+            .string()
+            .optional()
+            .describe('Optional V8 node type filter (e.g. object, closure, string, array, code).'),
+        retainedSize: byteSizeRangeSchema('Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.').optional(),
+        selfSize: byteSizeRangeSchema('Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.').optional(),
+        isDetached: zod
+            .boolean()
+            .optional()
+            .describe('Whether to filter for detached DOM nodes.'),
+        sortBy: zod
+            .enum(['retainedSize', 'selfSize', 'id'])
+            .optional()
+            .describe('Sort order for results. Default is retainedSize.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const range = await context.queryHeapSnapshotObjects(request.params.filePath, {
+            className: request.params.className,
+            propertyName: request.params.propertyName,
+            nodeType: request.params.nodeType,
+            minRetainedSize: request.params.retainedSize?.min,
+            maxRetainedSize: request.params.retainedSize?.max,
+            minSelfSize: request.params.selfSize?.min,
+            maxSelfSize: request.params.selfSize?.max,
+            isDetached: request.params.isDetached,
+            sortBy: request.params.sortBy,
+        });
+        response.setHeapSnapshotNodes(range, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+});
 //# sourceMappingURL=memory.js.map

package/build/src/tools/network.js

@@ -29,7 +29,7 @@ const FILTERABLE_RESOURCE_TYPES = [
 ];
 export const listNetworkRequests = definePageTool({
     name: 'list_network_requests',
-    description: `Lists the most recent requests for the currently selected page since the last navigation.`,
+    description: `Lists the most recent requests for the target page since the last navigation.`,
     annotations: {
         category: ToolCategory.NETWORK,
         readOnlyHint: true,
@@ -76,7 +76,7 @@ export const listNetworkRequests = definePageTool({
 });
 export const getNetworkRequest = definePageTool({
     name: 'get_network_request',
-    description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
+    description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel. Useful for inspecting request headers (including 'Cookie') and response headers (including 'Set-Cookie' and directives).`,
     annotations: {
         category: ToolCategory.NETWORK,
         readOnlyHint: false,

package/build/src/tools/pages.js

@@ -5,6 +5,7 @@
  */
 import { zod } from '../third_party/index.js';
 import { logger } from '../utils/logger.js';
+import { validateUrl } from '../utils/url.js';
 import { ToolCategory } from './categories.js';
 import { CLOSE_PAGE_ERROR, definePageTool, defineTool, timeoutSchema, } from './ToolDefinition.js';
 export const listPages = defineTool(args => {
@@ -84,7 +85,7 @@ export const closePage = defineTool({
         response.setListThirdPartyDeveloperTools();
     },
 });
-export const newPage = defineTool(() => {
+export const newPage = defineTool(args => {
     return {
         name: 'new_page',
         description: `Open a new tab and load a URL. Use project URL if not specified otherwise.`,
@@ -103,12 +104,16 @@ export const newPage = defineTool(() => {
                 .optional()
                 .describe('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.'),
+                'Pages in different browser contexts are fully isolated (useful for clean-slate testing of cookies and authentication).'),
             ...timeoutSchema,
         },
         blockedByDialog: false,
         verifyFilesSchema: {},
         handler: async (request, response, context) => {
+            validateUrl(request.params.url, {
+                javascriptEvaluation: args?.javascriptEvaluation,
+                categoryExtensions: args?.categoryExtensions,
+            });
             const page = await context.newPage(request.params.background, request.params.isolatedContext);
             await page.waitForEventsAfterAction(async () => {
                 await page.pptrPage.goto(request.params.url, {
@@ -120,7 +125,7 @@ export const newPage = defineTool(() => {
         },
     };
 });
-export const navigatePage = definePageTool(() => {
+export const navigatePage = definePageTool(args => {
     return {
         name: 'navigate_page',
         description: `Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.`,
@@ -142,10 +147,14 @@ export const navigatePage = definePageTool(() => {
                 .enum(['accept', 'dismiss'])
                 .optional()
                 .describe('Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.'),
-            initScript: zod
-                .string()
-                .optional()
-                .describe('A JavaScript script to be executed on each new document before any other scripts for the next navigation.'),
+            ...(args?.javascriptEvaluation !== false
+                ? {
+                    initScript: zod
+                        .string()
+                        .optional()
+                        .describe('A JavaScript script to be executed on each new document before any other scripts for the next navigation.'),
+                }
+                : {}),
             ...timeoutSchema,
         },
         blockedByDialog: false,
@@ -161,6 +170,12 @@ export const navigatePage = definePageTool(() => {
             if (!request.params.type) {
                 request.params.type = 'url';
             }
+            if (request.params.url) {
+                validateUrl(request.params.url, {
+                    javascriptEvaluation: args?.javascriptEvaluation,
+                    categoryExtensions: args?.categoryExtensions,
+                });
+            }
             let initScriptId;
             if (request.params.initScript) {
                 const { identifier } = await page.pptrPage.evaluateOnNewDocument(request.params.initScript);
@@ -239,7 +254,7 @@ export const navigatePage = definePageTool(() => {
 });
 export const resizePage = definePageTool({
     name: 'resize_page',
-    description: `Resizes the selected page's window so that the page has specified dimension`,
+    description: `Resizes the page's window so that the page has specified dimension`,
     annotations: {
         category: ToolCategory.EMULATION,
         readOnlyHint: false,
@@ -335,15 +350,11 @@ export const getTabId = definePageTool({
         readOnlyHint: true,
         conditions: ['experimentalInteropTools'],
     },
-    schema: {
-        pageId: zod
-            .number()
-            .describe(`The ID of the page to get the tab ID for. Call ${listPages().name} to get available pages.`),
-    },
+    schema: {},
     blockedByDialog: false,
     verifyFilesSchema: {},
-    handler: async (request, response, context) => {
-        const page = context.getPageById(request.params.pageId);
+    handler: async (request, response) => {
+        const page = request.page;
         const tabId = page.pptrPage._tabId;
         response.setTabId(tabId);
         response.appendResponseLine(`Tab ID: ${tabId}`);

package/build/src/tools/performance.js

@@ -15,7 +15,7 @@ const filePathSchema = zod
     .describe('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).');
 export const startTrace = definePageTool({
     name: '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.`,
+    description: `Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.`,
     annotations: {
         category: ToolCategory.PERFORMANCE,
         readOnlyHint: false,
@@ -24,7 +24,7 @@ export const startTrace = definePageTool({
         reload: zod
             .boolean()
             .default(true)
-            .describe('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.'),
+            .describe('Determines if, once tracing has started, the target 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.'),
         autoStop: zod
             .boolean()
             .default(true)
@@ -60,6 +60,7 @@ export const startTrace = definePageTool({
             ];
             await page.pptrPage.tracing.start({
                 categories,
+                bufferSize: 1200 * 1000,
             });
             if (request.params.reload) {
                 await page.pptrPage.goto(pageUrlForTracing, {
@@ -96,7 +97,7 @@ export const startTrace = definePageTool({
 });
 export const stopTrace = definePageTool({
     name: 'performance_stop_trace',
-    description: 'Stop the active performance trace recording on the selected webpage.',
+    description: 'Stop the active performance trace recording on the target webpage.',
     annotations: {
         category: ToolCategory.PERFORMANCE,
         readOnlyHint: false,

package/build/src/tools/screencast.js

@@ -16,7 +16,7 @@ async function generateTempFilePath() {
 const supportedExtensions = ['.webm', '.mp4'];
 export const startScreencast = definePageTool(args => ({
     name: 'screencast_start',
-    description: `Starts recording a screencast (video) of the selected page in specified format.`,
+    description: `Starts recording a screencast (video) of the target page in specified format.`,
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: false,
@@ -62,6 +62,7 @@ export const startScreencast = definePageTool(args => ({
                 path: resolvedPath,
                 format: format,
                 ffmpegPath: args?.experimentalFfmpegPath,
+                fps: args?.experimentalScreencastFps,
             });
         }
         catch (err) {
@@ -91,7 +92,7 @@ export const startScreencast = definePageTool(args => ({
 }));
 export const stopScreencast = definePageTool({
     name: 'screencast_stop',
-    description: 'Stops the active screencast recording on the selected page.',
+    description: 'Stops the active screencast recording on the target page.',
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: false,

package/build/src/tools/screenshot.js

@@ -60,22 +60,41 @@ import { ToolCategory } from './categories.js';
 import { definePageTool } from './ToolDefinition.js';
 async function getSourceBox(page, element, fullPage) {
     if (element) {
-        const box = await element.boundingBox();
-        return box ?? undefined;
+        const viewport = page.viewport();
+        const [box, devicePixelRatio] = await Promise.all([
+            element.boundingBox(),
+            viewport
+                ? (viewport.deviceScaleFactor ?? 1)
+                : page.evaluate(() => window.devicePixelRatio),
+        ]);
+        return box ? { ...box, devicePixelRatio } : undefined;
     }
     if (fullPage) {
         const dims = await page.evaluate(() => ({
             width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
             height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+            devicePixelRatio: window.devicePixelRatio,
         }));
         if (dims.width <= 0 || dims.height <= 0) {
             return undefined;
         }
-        return { x: 0, y: 0, width: dims.width, height: dims.height };
+        return {
+            x: 0,
+            y: 0,
+            width: dims.width,
+            height: dims.height,
+            devicePixelRatio: dims.devicePixelRatio,
+        };
     }
     const viewport = page.viewport();
     if (viewport) {
-        return { x: 0, y: 0, width: viewport.width, height: viewport.height };
+        return {
+            x: 0,
+            y: 0,
+            width: viewport.width,
+            height: viewport.height,
+            devicePixelRatio: viewport.deviceScaleFactor ?? 1,
+        };
     }
     // The browser is launched and connected with `defaultViewport: null`, so
     // `page.viewport()` stays null until something emulates one. Fall back to the
@@ -83,21 +102,33 @@ async function getSourceBox(page, element, fullPage) {
     const dims = await page.evaluate(() => ({
         width: window.innerWidth,
         height: window.innerHeight,
+        devicePixelRatio: window.devicePixelRatio,
     }));
     if (dims.width <= 0 || dims.height <= 0) {
         return undefined;
     }
-    return { x: 0, y: 0, width: dims.width, height: dims.height };
+    return {
+        x: 0,
+        y: 0,
+        width: dims.width,
+        height: dims.height,
+        devicePixelRatio: dims.devicePixelRatio,
+    };
 }
 function computeDownscaleClip(box, maxWidth, maxHeight) {
-    const widthScale = maxWidth !== undefined ? Math.min(1, maxWidth / box.width) : 1;
-    const heightScale = maxHeight !== undefined ? Math.min(1, maxHeight / box.height) : 1;
+    const widthScale = maxWidth !== undefined
+        ? Math.min(1, maxWidth / (box.width * box.devicePixelRatio))
+        : 1;
+    const heightScale = maxHeight !== undefined
+        ? Math.min(1, maxHeight / (box.height * box.devicePixelRatio))
+        : 1;
     const scale = Math.min(widthScale, heightScale);
     if (scale >= 1) {
         return undefined;
     }
     // Skip degenerate sub-pixel results.
-    if (Math.round(box.width * scale) < 1 || Math.round(box.height * scale) < 1) {
+    if (Math.round(box.width * box.devicePixelRatio * scale) < 1 ||
+        Math.round(box.height * box.devicePixelRatio * scale) < 1) {
         return undefined;
     }
     return {

package/build/src/tools/script.js

@@ -61,14 +61,24 @@ import { defineTool, pageIdSchema } from './ToolDefinition.js';
 export const evaluateScript = defineTool(cliArgs => {
     return {
         name: 'evaluate_script',
-        description: `Evaluate a JavaScript function inside the currently selected page${cliArgs?.categoryExtensions ? ' or service worker' : ''}. Returns the response as JSON, so returned values have to be JSON-serializable.`,
+        description: `Evaluate a JavaScript function inside the target page${cliArgs?.categoryExtensions ? ' or service worker' : ''}. Returns the response as JSON, so returned values have to be JSON-serializable.`,
         annotations: {
             category: ToolCategory.DEBUGGING,
             readOnlyHint: false,
+            conditions: ['javascriptEvaluation'],
         },
         schema: {
-            ...(cliArgs?.experimentalPageIdRouting ? pageIdSchema : {}),
-            function: zod.string().describe(`A JavaScript function declaration to be executed by the tool in the currently selected page.
+            ...(cliArgs?.pageIdRouting
+                ? cliArgs.categoryExtensions
+                    ? {
+                        pageId: zod
+                            .number()
+                            .optional()
+                            .describe('Targets a specific page by ID. Required when not evaluating in a service worker.'),
+                    }
+                    : pageIdSchema
+                : {}),
+            function: zod.string().describe(`A JavaScript function declaration to be executed by the tool in the target page.
 Example without arguments: \`() => document.title\` or \`async () => await fetch("example.com")\`.
 Example with arguments: \`(el) => el.innerText\`
 `),
@@ -131,7 +141,10 @@ Example with arguments: \`(el) => el.innerText\`
                     response.attachWaitForResult(result);
                     return;
                 }
-                const mcpPage = cliArgs?.experimentalPageIdRouting
+                if (cliArgs?.categoryExtensions && cliArgs?.pageIdRouting && !pageId) {
+                    throw new Error('specify either a pageId or a serviceWorkerId.');
+                }
+                const mcpPage = cliArgs?.pageIdRouting && request.params.pageId
                     ? context.getPageById(request.params.pageId)
                     : context.getSelectedMcpPage();
                 const page = mcpPage.pptrPage;