chrome-devtools-mcp 0.8.1 → 0.10.0

package/build/src/tools/pages.js

@@ -3,15 +3,15 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import z from 'zod';
 import { logger } from '../logger.js';
-import { ToolCategories } from './categories.js';
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
 import { CLOSE_PAGE_ERROR, defineTool, timeoutSchema } from './ToolDefinition.js';
 export const listPages = defineTool({
     name: 'list_pages',
     description: `Get a list of pages open in the browser.`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: true,
     },
     schema: {},
@@ -23,11 +23,11 @@ export const selectPage = defineTool({
     name: 'select_page',
     description: `Select a page as a context for future tool calls.`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: true,
     },
     schema: {
-        pageIdx: z
+        pageIdx: zod
             .number()
             .describe('The index of the page to select. Call list_pages to list pages.'),
     },
@@ -42,11 +42,11 @@ export const closePage = defineTool({
     name: 'close_page',
     description: `Closes the page by its index. The last open page cannot be closed.`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: false,
     },
     schema: {
-        pageIdx: z
+        pageIdx: zod
             .number()
             .describe('The index of the page to close. Call list_pages to list pages.'),
     },
@@ -69,11 +69,11 @@ export const newPage = defineTool({
     name: 'new_page',
     description: `Creates a new page`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: false,
     },
     schema: {
-        url: z.string().describe('URL to load in a new page.'),
+        url: zod.string().describe('URL to load in a new page.'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
@@ -90,34 +90,19 @@ export const navigatePage = defineTool({
     name: 'navigate_page',
     description: `Navigates the currently selected page to a URL.`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: false,
     },
     schema: {
-        url: z.string().describe('URL to navigate the page to'),
-        ...timeoutSchema,
-    },
-    handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
-        await context.waitForEventsAfterAction(async () => {
-            await page.goto(request.params.url, {
-                timeout: request.params.timeout,
-            });
-        });
-        response.setIncludePages(true);
-    },
-});
-export const navigatePageHistory = defineTool({
-    name: 'navigate_page_history',
-    description: `Navigates the currently selected page.`,
-    annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        navigate: z
-            .enum(['back', 'forward'])
-            .describe('Whether to navigate back or navigate forward in the selected pages history'),
+        type: zod
+            .enum(['url', 'back', 'forward', 'reload'])
+            .optional()
+            .describe('Navigate the page by URL, back or forward in history, or reload.'),
+        url: zod.string().optional().describe('Target URL (only type=url)'),
+        ignoreCache: zod
+            .boolean()
+            .optional()
+            .describe('Whether to ignore cache on reload.'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
@@ -125,17 +110,58 @@ export const navigatePageHistory = defineTool({
         const options = {
             timeout: request.params.timeout,
         };
-        try {
-            if (request.params.navigate === 'back') {
-                await page.goBack(options);
-            }
-            else {
-                await page.goForward(options);
-            }
+        if (!request.params.type && !request.params.url) {
+            throw new Error('Either URL or a type is required.');
         }
-        catch (error) {
-            response.appendResponseLine(`Unable to navigate ${request.params.navigate} in currently selected page. ${error.message}`);
+        if (!request.params.type) {
+            request.params.type = 'url';
         }
+        await context.waitForEventsAfterAction(async () => {
+            switch (request.params.type) {
+                case 'url':
+                    if (!request.params.url) {
+                        throw new Error('A URL is required for navigation of type=url.');
+                    }
+                    try {
+                        await page.goto(request.params.url, options);
+                        response.appendResponseLine(`Successfully navigated to ${request.params.url}.`);
+                    }
+                    catch (error) {
+                        response.appendResponseLine(`Unable to navigate in the  selected page: ${error.message}.`);
+                    }
+                    break;
+                case 'back':
+                    try {
+                        await page.goBack(options);
+                        response.appendResponseLine(`Successfully navigated back to ${page.url()}.`);
+                    }
+                    catch (error) {
+                        response.appendResponseLine(`Unable to navigate back in the selected page: ${error.message}.`);
+                    }
+                    break;
+                case 'forward':
+                    try {
+                        await page.goForward(options);
+                        response.appendResponseLine(`Successfully navigated forward to ${page.url()}.`);
+                    }
+                    catch (error) {
+                        response.appendResponseLine(`Unable to navigate forward in the selected page: ${error.message}.`);
+                    }
+                    break;
+                case 'reload':
+                    try {
+                        await page.reload({
+                            ...options,
+                            ignoreCache: request.params.ignoreCache,
+                        });
+                        response.appendResponseLine(`Successfully reloaded the page.`);
+                    }
+                    catch (error) {
+                        response.appendResponseLine(`Unable to reload the selected page: ${error.message}.`);
+                    }
+                    break;
+            }
+        });
         response.setIncludePages(true);
     },
 });
@@ -143,12 +169,12 @@ export const resizePage = defineTool({
     name: 'resize_page',
     description: `Resizes the selected page's window so that the page has specified dimension`,
     annotations: {
-        category: ToolCategories.EMULATION,
+        category: ToolCategory.EMULATION,
         readOnlyHint: false,
     },
     schema: {
-        width: z.number().describe('Page width'),
-        height: z.number().describe('Page height'),
+        width: zod.number().describe('Page width'),
+        height: zod.number().describe('Page height'),
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
@@ -164,14 +190,14 @@ export const handleDialog = defineTool({
     name: 'handle_dialog',
     description: `If a browser dialog was opened, use this command to handle it`,
     annotations: {
-        category: ToolCategories.INPUT_AUTOMATION,
+        category: ToolCategory.INPUT,
         readOnlyHint: false,
     },
     schema: {
-        action: z
+        action: zod
             .enum(['accept', 'dismiss'])
             .describe('Whether to dismiss or accept the dialog'),
-        promptText: z
+        promptText: zod
             .string()
             .optional()
             .describe('Optional prompt text to enter into the dialog.'),

package/build/src/tools/performance.js

@@ -3,23 +3,23 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import z from 'zod';
 import { logger } from '../logger.js';
+import { zod } from '../third_party/index.js';
 import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
-import { ToolCategories } from './categories.js';
+import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 export const startTrace = defineTool({
     name: 'performance_start_trace',
     description: 'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',
     annotations: {
-        category: ToolCategories.PERFORMANCE,
+        category: ToolCategory.PERFORMANCE,
         readOnlyHint: true,
     },
     schema: {
-        reload: z
+        reload: zod
             .boolean()
             .describe('Determines if, once tracing has started, the page should be automatically reloaded.'),
-        autoStop: z
+        autoStop: zod
             .boolean()
             .describe('Determines if the trace recording should be automatically stopped.'),
     },
@@ -79,7 +79,7 @@ export const stopTrace = defineTool({
     name: 'performance_stop_trace',
     description: 'Stops the active performance trace recording on the selected page.',
     annotations: {
-        category: ToolCategories.PERFORMANCE,
+        category: ToolCategory.PERFORMANCE,
         readOnlyHint: true,
     },
     schema: {},
@@ -93,13 +93,16 @@ export const stopTrace = defineTool({
 });
 export const analyzeInsight = defineTool({
     name: 'performance_analyze_insight',
-    description: 'Provides more detailed information on a specific Performance Insight that was highlighted in the results of a trace recording.',
+    description: 'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
     annotations: {
-        category: ToolCategories.PERFORMANCE,
+        category: ToolCategory.PERFORMANCE,
         readOnlyHint: true,
     },
     schema: {
-        insightName: z
+        insightSetId: zod
+            .string()
+            .describe('The id for the specific insight set. Only use the ids given in the "Available insight sets" list.'),
+        insightName: zod
             .string()
             .describe('The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"'),
     },
@@ -109,7 +112,7 @@ export const analyzeInsight = defineTool({
             response.appendResponseLine('No recorded traces found. Record a performance trace so you have Insights to analyze.');
             return;
         }
-        const insightOutput = getInsightOutput(lastRecording, request.params.insightName);
+        const insightOutput = getInsightOutput(lastRecording, request.params.insightSetId, request.params.insightName);
         if ('error' in insightOutput) {
             response.appendResponseLine(insightOutput.error);
             return;

package/build/src/tools/screenshot.js

@@ -3,36 +3,37 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import z from 'zod';
-import { ToolCategories } from './categories.js';
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 export const screenshot = defineTool({
     name: 'take_screenshot',
     description: `Take a screenshot of the page or element.`,
     annotations: {
-        category: ToolCategories.DEBUGGING,
-        readOnlyHint: true,
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
     },
     schema: {
-        format: z
+        format: zod
             .enum(['png', 'jpeg', 'webp'])
             .default('png')
             .describe('Type of format to save the screenshot as. Default is "png"'),
-        quality: z
+        quality: zod
             .number()
             .min(0)
             .max(100)
             .optional()
             .describe('Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.'),
-        uid: z
+        uid: zod
             .string()
             .optional()
             .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
-        fullPage: z
+        fullPage: zod
             .boolean()
             .optional()
             .describe('If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.'),
-        filePath: z
+        filePath: zod
             .string()
             .optional()
             .describe('The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.'),

package/build/src/tools/script.js

@@ -1,16 +1,21 @@
-import z from 'zod';
-import { ToolCategories } from './categories.js';
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 export const evaluateScript = defineTool({
     name: 'evaluate_script',
     description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON
 so returned values have to JSON-serializable.`,
     annotations: {
-        category: ToolCategories.DEBUGGING,
+        category: ToolCategory.DEBUGGING,
         readOnlyHint: false,
     },
     schema: {
-        function: z.string().describe(`A JavaScript function to run in the currently selected page.
+        function: zod.string().describe(`A JavaScript function declaration to be executed by the tool in the currently selected page.
 Example without arguments: \`() => {
   return document.title
 }\` or \`async () => {
@@ -20,9 +25,9 @@ Example with arguments: \`(el) => {
   return el.innerText;
 }\`
 `),
-        args: z
-            .array(z.object({
-            uid: z
+        args: zod
+            .array(zod.object({
+            uid: zod
                 .string()
                 .describe('The uid of an element on the page from the page content snapshot'),
         }))
@@ -30,15 +35,26 @@ Example with arguments: \`(el) => {
             .describe(`An optional list of arguments to pass to the function.`),
     },
     handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
-        const fn = await page.evaluateHandle(`(${request.params.function})`);
-        const args = [fn];
+        const args = [];
         try {
+            const frames = new Set();
             for (const el of request.params.args ?? []) {
-                args.push(await context.getElementByUid(el.uid));
+                const handle = await context.getElementByUid(el.uid);
+                frames.add(handle.frame);
+                args.push(handle);
             }
+            let pageOrFrame;
+            // We can't evaluate the element handle across frames
+            if (frames.size > 1) {
+                throw new Error("Elements from different frames can't be evaluated together.");
+            }
+            else {
+                pageOrFrame = [...frames.values()][0] ?? context.getSelectedPage();
+            }
+            const fn = await pageOrFrame.evaluateHandle(`(${request.params.function})`);
+            args.unshift(fn);
             await context.waitForEventsAfterAction(async () => {
-                const result = await page.evaluate(async (fn, ...args) => {
+                const result = await pageOrFrame.evaluate(async (fn, ...args) => {
                     // @ts-expect-error no types.
                     return JSON.stringify(await fn(...args));
                 }, ...args);
@@ -49,9 +65,7 @@ Example with arguments: \`(el) => {
             });
         }
         finally {
-            Promise.allSettled(args.map(arg => arg.dispose())).catch(() => {
-                // Ignore errors
-            });
+            void Promise.allSettled(args.map(arg => arg.dispose()));
         }
     },
 });

package/build/src/tools/snapshot.js

@@ -3,46 +3,50 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Locator } from 'puppeteer-core';
-import z from 'zod';
-import { ToolCategories } from './categories.js';
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
 import { defineTool, timeoutSchema } from './ToolDefinition.js';
 export const takeSnapshot = defineTool({
     name: 'take_snapshot',
-    description: `Take a text snapshot of the currently selected page. The snapshot lists page elements along with a unique
-identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot.`,
+    description: `Take a text snapshot of the currently selected page based on the a11y tree. The snapshot lists page elements along with a unique
+identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
+in the DevTools Elements panel (if any).`,
     annotations: {
-        category: ToolCategories.DEBUGGING,
-        readOnlyHint: true,
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
+    },
+    schema: {
+        verbose: zod
+            .boolean()
+            .optional()
+            .describe('Whether to include all possible information available in the full a11y tree. Default is false.'),
+        filePath: zod
+            .string()
+            .optional()
+            .describe('The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.'),
     },
-    schema: {},
-    handler: async (_request, response) => {
-        response.setIncludeSnapshot(true);
+    handler: async (request, response) => {
+        response.includeSnapshot({
+            verbose: request.params.verbose ?? false,
+            filePath: request.params.filePath,
+        });
     },
 });
 export const waitFor = defineTool({
     name: 'wait_for',
     description: `Wait for the specified text to appear on the selected page.`,
     annotations: {
-        category: ToolCategories.NAVIGATION_AUTOMATION,
+        category: ToolCategory.NAVIGATION,
         readOnlyHint: true,
     },
     schema: {
-        text: z.string().describe('Text to appear on the page'),
+        text: zod.string().describe('Text to appear on the page'),
         ...timeoutSchema,
     },
     handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
-        const frames = page.frames();
-        const locator = Locator.race(frames.flatMap(frame => [
-            frame.locator(`aria/${request.params.text}`),
-            frame.locator(`text/${request.params.text}`),
-        ]));
-        if (request.params.timeout) {
-            locator.setTimeout(request.params.timeout);
-        }
-        await locator.wait();
+        await context.waitForTextOnPage(request.params);
         response.appendResponseLine(`Element with text "${request.params.text}" found.`);
-        response.setIncludeSnapshot(true);
+        response.includeSnapshot();
     },
 });

package/build/src/trace-processing/parse.js

@@ -3,10 +3,7 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { PerformanceInsightFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
-import { PerformanceTraceFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
-import { AgentFocus } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
-import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
+import { AgentFocus, TraceEngine, PerformanceTraceFormatter, PerformanceInsightFormatter, } from '../../node_modules/chrome-devtools-frontend/mcp/mcp.js';
 import { logger } from '../logger.js';
 const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
 export function traceResultIsSuccess(x) {
@@ -64,26 +61,19 @@ ${summaryText}
 ## Details on call tree & network request formats:
 ${extraFormatDescriptions}`;
 }
-export function getInsightOutput(result, insightName) {
+export function getInsightOutput(result, insightSetId, insightName) {
     if (!result.insights) {
         return {
             error: 'No Performance insights are available for this trace.',
         };
     }
-    // Currently, we do not support inspecting traces with multiple navigations. We either:
-    // 1. Find Insights from the first navigation (common case: user records a trace with a page reload to test load performance)
-    // 2. Fall back to finding Insights not associated with a navigation (common case: user tests an interaction without a page load).
-    const mainNavigationId = result.parsedTrace.data.Meta.mainFrameNavigations.at(0)?.args.data
-        ?.navigationId;
-    const insightsForNav = result.insights.get(mainNavigationId ?? TraceEngine.Types.Events.NO_NAVIGATION);
-    if (!insightsForNav) {
+    const insightSet = result.insights.get(insightSetId);
+    if (!insightSet) {
         return {
-            error: 'No Performance Insights for this trace.',
+            error: 'No Performance Insights for the given insight set id. Only use ids given in the "Available insight sets" list.',
         };
     }
-    const matchingInsight = insightName in insightsForNav.model
-        ? insightsForNav.model[insightName]
-        : null;
+    const matchingInsight = insightName in insightSet.model ? insightSet.model[insightName] : null;
     if (!matchingInsight) {
         return {
             error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,