ideamans-chrome-devtools-mcp 0.11.2

package/build/src/tools/network.js

@@ -0,0 +1,106 @@
+/**
+ * @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';
+const FILTERABLE_RESOURCE_TYPES = [
+    'document',
+    'stylesheet',
+    'image',
+    'media',
+    'font',
+    'script',
+    'texttrack',
+    'xhr',
+    'fetch',
+    'prefetch',
+    'eventsource',
+    'websocket',
+    'manifest',
+    'signedexchange',
+    'ping',
+    'cspviolationreport',
+    'preflight',
+    'fedcm',
+    'other',
+];
+export const listNetworkRequests = defineTool({
+    name: 'list_network_requests',
+    description: `List all requests for the currently selected page since the last navigation.`,
+    annotations: {
+        category: ToolCategory.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        pageSize: zod
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum number of requests to return. When omitted, returns all requests.'),
+        pageIdx: zod
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Page number to return (0-based). When omitted, returns the first page.'),
+        resourceTypes: zod
+            .array(zod.enum(FILTERABLE_RESOURCE_TYPES))
+            .optional()
+            .describe('Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.'),
+        includePreservedRequests: zod
+            .boolean()
+            .default(false)
+            .optional()
+            .describe('Set to true to return the preserved requests over the last 3 navigations.'),
+    },
+    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 an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
+    annotations: {
+        category: ToolCategory.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        reqid: zod
+            .number()
+            .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) => {
+        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

@@ -0,0 +1,237 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from '../logger.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: ToolCategory.NAVIGATION,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludePages(true);
+    },
+});
+export const selectPage = defineTool({
+    name: 'select_page',
+    description: `Select a page as a context for future tool calls.`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        pageIdx: zod
+            .number()
+            .describe('The index of the page to select. Call list_pages to list pages.'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getPageByIdx(request.params.pageIdx);
+        await page.bringToFront();
+        context.selectPage(page);
+        response.setIncludePages(true);
+    },
+});
+export const closePage = defineTool({
+    name: 'close_page',
+    description: `Closes the page by its index. The last open page cannot be closed.`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        pageIdx: zod
+            .number()
+            .describe('The index of the page to close. Call list_pages to list pages.'),
+    },
+    handler: async (request, response, context) => {
+        try {
+            await context.closePage(request.params.pageIdx);
+        }
+        catch (err) {
+            if (err.message === CLOSE_PAGE_ERROR) {
+                response.appendResponseLine(err.message);
+            }
+            else {
+                throw err;
+            }
+        }
+        response.setIncludePages(true);
+    },
+});
+export const newPage = defineTool({
+    name: 'new_page',
+    description: `Creates a new page`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        url: zod.string().describe('URL to load in a new page.'),
+        ...timeoutSchema,
+    },
+    handler: async (request, response, context) => {
+        const page = await context.newPage();
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(request.params.url, {
+                timeout: request.params.timeout,
+            });
+        });
+        response.setIncludePages(true);
+    },
+});
+export const navigatePage = defineTool({
+    name: 'navigate_page',
+    description: `Navigates the currently selected page to a URL.`,
+    annotations: {
+        category: ToolCategory.NAVIGATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        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) => {
+        const page = context.getSelectedPage();
+        const options = {
+            timeout: request.params.timeout,
+        };
+        if (!request.params.type && !request.params.url) {
+            throw new Error('Either URL or a type is required.');
+        }
+        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);
+    },
+});
+export const resizePage = defineTool({
+    name: 'resize_page',
+    description: `Resizes the selected page's window so that the page has specified dimension`,
+    annotations: {
+        category: ToolCategory.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        width: zod.number().describe('Page width'),
+        height: zod.number().describe('Page height'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        // @ts-expect-error internal API for now.
+        await page.resize({
+            contentWidth: request.params.width,
+            contentHeight: request.params.height,
+        });
+        response.setIncludePages(true);
+    },
+});
+export const handleDialog = defineTool({
+    name: 'handle_dialog',
+    description: `If a browser dialog was opened, use this command to handle it`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        action: zod
+            .enum(['accept', 'dismiss'])
+            .describe('Whether to dismiss or accept the dialog'),
+        promptText: zod
+            .string()
+            .optional()
+            .describe('Optional prompt text to enter into the dialog.'),
+    },
+    handler: async (request, response, context) => {
+        const dialog = context.getDialog();
+        if (!dialog) {
+            throw new Error('No open dialog found');
+        }
+        switch (request.params.action) {
+            case 'accept': {
+                try {
+                    await dialog.accept(request.params.promptText);
+                }
+                catch (err) {
+                    // Likely already handled by the user outside of MCP.
+                    logger(err);
+                }
+                response.appendResponseLine('Successfully accepted the dialog');
+                break;
+            }
+            case 'dismiss': {
+                try {
+                    await dialog.dismiss();
+                }
+                catch (err) {
+                    // Likely already handled.
+                    logger(err);
+                }
+                response.appendResponseLine('Successfully dismissed the dialog');
+                break;
+            }
+        }
+        context.clearDialog();
+        response.setIncludePages(true);
+    },
+});

package/build/src/tools/performance.js

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import { logger } from '../logger.js';
+import { zod } from '../third_party/index.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.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: ToolCategory.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        reload: zod
+            .boolean()
+            .describe('Determines if, once tracing has started, the page should be automatically reloaded.'),
+        autoStop: zod
+            .boolean()
+            .describe('Determines if the trace recording should be automatically stopped.'),
+    },
+    handler: async (request, response, context) => {
+        if (context.isRunningPerformanceTrace()) {
+            response.appendResponseLine('Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.');
+            return;
+        }
+        context.setIsRunningPerformanceTrace(true);
+        const page = context.getSelectedPage();
+        const pageUrlForTracing = page.url();
+        if (request.params.reload) {
+            // Before starting the recording, navigate to about:blank to clear out any state.
+            await page.goto('about:blank', {
+                waitUntil: ['networkidle0'],
+            });
+        }
+        // Keep in sync with the categories arrays in:
+        // https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineController.ts
+        // https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/gather/gatherers/trace.js
+        const categories = [
+            '-*',
+            'blink.console',
+            'blink.user_timing',
+            'devtools.timeline',
+            'disabled-by-default-devtools.screenshot',
+            'disabled-by-default-devtools.timeline',
+            'disabled-by-default-devtools.timeline.invalidationTracking',
+            'disabled-by-default-devtools.timeline.frame',
+            'disabled-by-default-devtools.timeline.stack',
+            'disabled-by-default-v8.cpu_profiler',
+            'disabled-by-default-v8.cpu_profiler.hires',
+            'latencyInfo',
+            'loading',
+            'disabled-by-default-lighthouse',
+            'v8.execute',
+            'v8',
+        ];
+        await page.tracing.start({
+            categories,
+        });
+        if (request.params.reload) {
+            await page.goto(pageUrlForTracing, {
+                waitUntil: ['load'],
+            });
+        }
+        if (request.params.autoStop) {
+            await new Promise(resolve => setTimeout(resolve, 5_000));
+            await stopTracingAndAppendOutput(page, response, context);
+        }
+        else {
+            response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
+        }
+    },
+});
+export const stopTrace = defineTool({
+    name: 'performance_stop_trace',
+    description: 'Stops the active performance trace recording on the selected page.',
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        if (!context.isRunningPerformanceTrace()) {
+            return;
+        }
+        const page = context.getSelectedPage();
+        await stopTracingAndAppendOutput(page, response, context);
+    },
+});
+export const analyzeInsight = defineTool({
+    name: 'performance_analyze_insight',
+    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"'),
+    },
+    handler: async (request, response, context) => {
+        const lastRecording = context.recordedTraces().at(-1);
+        if (!lastRecording) {
+            response.appendResponseLine('No recorded traces found. Record a performance trace so you have Insights to analyze.');
+            return;
+        }
+        const insightOutput = getInsightOutput(lastRecording, request.params.insightSetId, request.params.insightName);
+        if ('error' in insightOutput) {
+            response.appendResponseLine(insightOutput.error);
+            return;
+        }
+        response.appendResponseLine(insightOutput.output);
+    },
+});
+export const analyzeFile = defineTool({
+    name: 'performance_analyze_file',
+    description: 'Analyzes a performance trace file from the local filesystem. This can be used to analyze traces exported from Chrome DevTools, Lighthouse, or other tools that generate Chrome trace format files.',
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        filePath: zod
+            .string()
+            .describe('The absolute path to the trace file to analyze. Supports JSON trace files in Chrome trace format (e.g., trace.json, lighthouse-0.trace.json).'),
+    },
+    handler: async (request, response, context) => {
+        const { filePath } = request.params;
+        try {
+            const buffer = await fs.readFile(filePath);
+            const result = await parseRawTraceBuffer(new Uint8Array(buffer));
+            if (traceResultIsSuccess(result)) {
+                context.storeTraceRecording(result);
+                const traceSummaryText = getTraceSummary(result);
+                response.appendResponseLine(`Successfully analyzed trace file: ${filePath}`);
+                response.appendResponseLine(traceSummaryText);
+            }
+            else {
+                response.appendResponseLine('There was an error parsing the trace file:');
+                response.appendResponseLine(result.error);
+            }
+        }
+        catch (e) {
+            const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+            logger(`Error reading trace file: ${errorText}`);
+            response.appendResponseLine('An error occurred reading the trace file:');
+            response.appendResponseLine(errorText);
+        }
+    },
+});
+async function stopTracingAndAppendOutput(page, response, context) {
+    try {
+        const traceEventsBuffer = await page.tracing.stop();
+        const result = await parseRawTraceBuffer(traceEventsBuffer);
+        response.appendResponseLine('The performance trace has been stopped.');
+        if (traceResultIsSuccess(result)) {
+            context.storeTraceRecording(result);
+            const traceSummaryText = getTraceSummary(result);
+            response.appendResponseLine(traceSummaryText);
+        }
+        else {
+            response.appendResponseLine('There was an unexpected error parsing the trace:');
+            response.appendResponseLine(result.error);
+        }
+    }
+    catch (e) {
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Error stopping performance trace: ${errorText}`);
+        response.appendResponseLine('An error occurred generating the response for this trace:');
+        response.appendResponseLine(errorText);
+    }
+    finally {
+        context.setIsRunningPerformanceTrace(false);
+    }
+}

package/build/src/tools/screenshot.js

@@ -0,0 +1,84 @@
+/**
+ * @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 screenshot = defineTool({
+    name: 'take_screenshot',
+    description: `Take a screenshot of the page or element.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        // Not read-only due to filePath param.
+        readOnlyHint: false,
+    },
+    schema: {
+        format: zod
+            .enum(['png', 'jpeg', 'webp'])
+            .default('png')
+            .describe('Type of format to save the screenshot as. Default is "png"'),
+        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: zod
+            .string()
+            .optional()
+            .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
+        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: 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.'),
+    },
+    handler: async (request, response, context) => {
+        if (request.params.uid && request.params.fullPage) {
+            throw new Error('Providing both "uid" and "fullPage" is not allowed.');
+        }
+        let pageOrHandle;
+        if (request.params.uid) {
+            pageOrHandle = await context.getElementByUid(request.params.uid);
+        }
+        else {
+            pageOrHandle = context.getSelectedPage();
+        }
+        const format = request.params.format;
+        const quality = format === 'png' ? undefined : request.params.quality;
+        const screenshot = await pageOrHandle.screenshot({
+            type: format,
+            fullPage: request.params.fullPage,
+            quality,
+            optimizeForSpeed: true, // Bonus: optimize encoding for speed
+        });
+        if (request.params.uid) {
+            response.appendResponseLine(`Took a screenshot of node with uid "${request.params.uid}".`);
+        }
+        else if (request.params.fullPage) {
+            response.appendResponseLine('Took a screenshot of the full current page.');
+        }
+        else {
+            response.appendResponseLine("Took a screenshot of the current page's viewport.");
+        }
+        if (request.params.filePath) {
+            const file = await context.saveFile(screenshot, request.params.filePath);
+            response.appendResponseLine(`Saved screenshot to ${file.filename}.`);
+        }
+        else if (screenshot.length >= 2_000_000) {
+            const { filename } = await context.saveTemporaryFile(screenshot, `image/${request.params.format}`);
+            response.appendResponseLine(`Saved screenshot to ${filename}.`);
+        }
+        else {
+            response.attachImage({
+                mimeType: `image/${request.params.format}`,
+                data: Buffer.from(screenshot).toString('base64'),
+            });
+        }
+    },
+});

package/build/src/tools/script.js

@@ -0,0 +1,71 @@
+/**
+ * @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: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        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 () => {
+  return await fetch("example.com")
+}\`.
+Example with arguments: \`(el) => {
+  return el.innerText;
+}\`
+`),
+        args: zod
+            .array(zod.object({
+            uid: zod
+                .string()
+                .describe('The uid of an element on the page from the page content snapshot'),
+        }))
+            .optional()
+            .describe(`An optional list of arguments to pass to the function.`),
+    },
+    handler: async (request, response, context) => {
+        const args = [];
+        try {
+            const frames = new Set();
+            for (const el of request.params.args ?? []) {
+                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 pageOrFrame.evaluate(async (fn, ...args) => {
+                    // @ts-expect-error no types.
+                    return JSON.stringify(await fn(...args));
+                }, ...args);
+                response.appendResponseLine('Script ran on page and returned:');
+                response.appendResponseLine('```json');
+                response.appendResponseLine(`${result}`);
+                response.appendResponseLine('```');
+            });
+        }
+        finally {
+            void Promise.allSettled(args.map(arg => arg.dispose()));
+        }
+    },
+});