chrome-devtools-mcp 0.9.0 → 0.10.1

package/build/src/tools/emulation.js

@@ -11,61 +11,54 @@ const throttlingOptions = [
     'Offline',
     ...Object.keys(PredefinedNetworkConditions),
 ];
-export const emulateNetwork = defineTool({
-    name: 'emulate_network',
-    description: `Emulates network conditions such as throttling or offline mode on the selected page.`,
+export const emulate = defineTool({
+    name: 'emulate',
+    description: `Emulates various features on the selected page.`,
     annotations: {
         category: ToolCategory.EMULATION,
         readOnlyHint: false,
     },
     schema: {
-        throttlingOption: zod
+        networkConditions: zod
             .enum(throttlingOptions)
-            .describe(`The network throttling option to emulate. Available throttling options are: ${throttlingOptions.join(', ')}. Set to "No emulation" to disable. Set to "Offline" to simulate offline network conditions.`),
-    },
-    handler: async (request, _response, context) => {
-        const page = context.getSelectedPage();
-        const conditions = request.params.throttlingOption;
-        if (conditions === 'No emulation') {
-            await page.emulateNetworkConditions(null);
-            context.setNetworkConditions(null);
-            return;
-        }
-        if (conditions === 'Offline') {
-            await page.emulateNetworkConditions({
-                offline: true,
-                download: 0,
-                upload: 0,
-                latency: 0,
-            });
-            context.setNetworkConditions('Offline');
-            return;
-        }
-        if (conditions in PredefinedNetworkConditions) {
-            const networkCondition = PredefinedNetworkConditions[conditions];
-            await page.emulateNetworkConditions(networkCondition);
-            context.setNetworkConditions(conditions);
-        }
-    },
-});
-export const emulateCpu = defineTool({
-    name: 'emulate_cpu',
-    description: `Emulates CPU throttling by slowing down the selected page's execution.`,
-    annotations: {
-        category: ToolCategory.EMULATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        throttlingRate: zod
+            .optional()
+            .describe(`Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.`),
+        cpuThrottlingRate: zod
             .number()
             .min(1)
             .max(20)
-            .describe('The CPU throttling rate representing the slowdown factor 1-20x. Set the rate to 1 to disable throttling'),
+            .optional()
+            .describe('Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.'),
     },
     handler: async (request, _response, context) => {
         const page = context.getSelectedPage();
-        const { throttlingRate } = request.params;
-        await page.emulateCPUThrottling(throttlingRate);
-        context.setCpuThrottlingRate(throttlingRate);
+        const networkConditions = request.params.networkConditions;
+        const cpuThrottlingRate = request.params.cpuThrottlingRate;
+        if (networkConditions) {
+            if (networkConditions === 'No emulation') {
+                await page.emulateNetworkConditions(null);
+                context.setNetworkConditions(null);
+                return;
+            }
+            if (networkConditions === 'Offline') {
+                await page.emulateNetworkConditions({
+                    offline: true,
+                    download: 0,
+                    upload: 0,
+                    latency: 0,
+                });
+                context.setNetworkConditions('Offline');
+                return;
+            }
+            if (networkConditions in PredefinedNetworkConditions) {
+                const networkCondition = PredefinedNetworkConditions[networkConditions];
+                await page.emulateNetworkConditions(networkCondition);
+                context.setNetworkConditions(networkConditions);
+            }
+        }
+        if (cpuThrottlingRate) {
+            await page.emulateCPUThrottling(cpuThrottlingRate);
+            context.setCpuThrottlingRate(cpuThrottlingRate);
+        }
     },
 });

package/build/src/tools/input.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { zod } from '../third_party/index.js';
+import { parseKey } from '../utils/keyboard.js';
 import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
 export const click = defineTool({
@@ -34,7 +35,7 @@ export const click = defineTool({
             response.appendResponseLine(request.params.dblClick
                 ? `Successfully double clicked on the element`
                 : `Successfully clicked on the element`);
-            response.setIncludeSnapshot(true);
+            response.includeSnapshot();
         }
         finally {
             void handle.dispose();
@@ -61,7 +62,7 @@ export const hover = defineTool({
                 await handle.asLocator().hover();
             });
             response.appendResponseLine(`Successfully hovered over the element`);
-            response.setIncludeSnapshot(true);
+            response.includeSnapshot();
         }
         finally {
             void handle.dispose();
@@ -135,7 +136,7 @@ export const fill = defineTool({
             await fillFormElement(request.params.uid, request.params.value, context);
         });
         response.appendResponseLine(`Successfully filled out the element`);
-        response.setIncludeSnapshot(true);
+        response.includeSnapshot();
     },
 });
 export const drag = defineTool({
@@ -159,7 +160,7 @@ export const drag = defineTool({
                 await toHandle.drop(fromHandle);
             });
             response.appendResponseLine(`Successfully dragged an element`);
-            response.setIncludeSnapshot(true);
+            response.includeSnapshot();
         }
         finally {
             void fromHandle.dispose();
@@ -189,7 +190,7 @@ export const fillForm = defineTool({
             });
         }
         response.appendResponseLine(`Successfully filled out the form`);
-        response.setIncludeSnapshot(true);
+        response.includeSnapshot();
     },
 });
 export const uploadFile = defineTool({
@@ -228,7 +229,7 @@ export const uploadFile = defineTool({
                     throw new Error(`Failed to upload file. The element could not accept the file directly, and clicking it did not trigger a file chooser.`);
                 }
             }
-            response.setIncludeSnapshot(true);
+            response.includeSnapshot();
             response.appendResponseLine(`File uploaded from ${filePath}.`);
         }
         finally {
@@ -236,3 +237,32 @@ export const uploadFile = defineTool({
         }
     },
 });
+export const pressKey = defineTool({
+    name: 'press_key',
+    description: `Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        key: zod
+            .string()
+            .describe('A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const tokens = parseKey(request.params.key);
+        const [key, ...modifiers] = tokens;
+        await context.waitForEventsAfterAction(async () => {
+            for (const modifier of modifiers) {
+                await page.keyboard.down(modifier);
+            }
+            await page.keyboard.press(key);
+            for (const modifier of modifiers.toReversed()) {
+                await page.keyboard.up(modifier);
+            }
+        });
+        response.appendResponseLine(`Successfully pressed key: ${request.params.key}`);
+        response.includeSnapshot();
+    },
+});

package/build/src/tools/network.js

@@ -57,18 +57,24 @@ export const listNetworkRequests = defineTool({
             .optional()
             .describe('Set to true to return the preserved requests over the last 3 navigations.'),
     },
-    handler: async (request, response) => {
+    handler: async (request, response, context) => {
+        const data = await context.getDevToolsData();
+        response.attachDevToolsData(data);
+        const reqid = data?.cdpRequestId
+            ? context.resolveCdpRequestId(data.cdpRequestId)
+            : undefined;
         response.setIncludeNetworkRequests(true, {
             pageSize: request.params.pageSize,
             pageIdx: request.params.pageIdx,
             resourceTypes: request.params.resourceTypes,
             includePreservedRequests: request.params.includePreservedRequests,
+            networkRequestIdInDevToolsUI: reqid,
         });
     },
 });
 export const getNetworkRequest = defineTool({
     name: 'get_network_request',
-    description: `Gets a network request by URL. You can get all requests by calling ${listNetworkRequests.name}.`,
+    description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
     annotations: {
         category: ToolCategory.NETWORK,
         readOnlyHint: true,
@@ -76,9 +82,25 @@ export const getNetworkRequest = defineTool({
     schema: {
         reqid: zod
             .number()
-            .describe('The reqid of a request on the page from the listed network requests'),
+            .optional()
+            .describe('The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.'),
     },
-    handler: async (request, response, _context) => {
-        response.attachNetworkRequest(request.params.reqid);
+    handler: async (request, response, context) => {
+        if (request.params.reqid) {
+            response.attachNetworkRequest(request.params.reqid);
+        }
+        else {
+            const data = await context.getDevToolsData();
+            response.attachDevToolsData(data);
+            const reqid = data?.cdpRequestId
+                ? context.resolveCdpRequestId(data.cdpRequestId)
+                : undefined;
+            if (reqid) {
+                response.attachNetworkRequest(reqid);
+            }
+            else {
+                response.appendResponseLine(`Nothing is currently selected in the DevTools Network panel.`);
+            }
+        }
     },
 });

package/build/src/tools/pages.js

@@ -34,7 +34,7 @@ export const selectPage = defineTool({
     handler: async (request, response, context) => {
         const page = context.getPageByIdx(request.params.pageIdx);
         await page.bringToFront();
-        context.setSelectedPageIdx(request.params.pageIdx);
+        context.selectPage(page);
         response.setIncludePages(true);
     },
 });
@@ -94,30 +94,15 @@ export const navigatePage = defineTool({
         readOnlyHint: false,
     },
     schema: {
-        url: zod.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: ToolCategory.NAVIGATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        navigate: zod
-            .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);
     },
 });

package/build/src/tools/performance.js

@@ -93,12 +93,15 @@ 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: ToolCategory.PERFORMANCE,
         readOnlyHint: true,
     },
     schema: {
+        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

@@ -11,7 +11,8 @@ export const screenshot = defineTool({
     description: `Take a screenshot of the page or element.`,
     annotations: {
         category: ToolCategory.DEBUGGING,
-        readOnlyHint: true,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
     },
     schema: {
         format: zod

package/build/src/tools/snapshot.js

@@ -9,19 +9,28 @@ import { defineTool, timeoutSchema } from './ToolDefinition.js';
 export const takeSnapshot = defineTool({
     name: 'take_snapshot',
     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.`,
+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: ToolCategory.DEBUGGING,
-        readOnlyHint: true,
+        // 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.'),
     },
     handler: async (request, response) => {
-        response.setIncludeSnapshot(true, request.params.verbose ?? false);
+        response.includeSnapshot({
+            verbose: request.params.verbose ?? false,
+            filePath: request.params.filePath,
+        });
     },
 });
 export const waitFor = defineTool({
@@ -38,6 +47,6 @@ export const waitFor = defineTool({
     handler: async (request, response, context) => {
         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.`,