@mcp-b/chrome-devtools-mcp 2.3.0 → 2.3.1-beta.20260528050333

package/build/src/tools/pages.js

@@ -1,319 +0,0 @@
-/**
- * @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, definePageTool, defineTool, timeoutSchema } from './ToolDefinition.js';
-export const listPages = definePageTool((args) => {
-    return {
-        name: 'list_pages',
-        description: `Get a list of pages ${args?.categoryExtensions ? 'including extension service workers' : ''} 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: {
-        pageId: zod
-            .number()
-            .describe(`The ID of the page to select. Call ${listPages().name} to get available pages.`),
-        bringToFront: zod
-            .boolean()
-            .optional()
-            .describe('Whether to focus the page and bring it to the top.'),
-    },
-    handler: async (request, response, context) => {
-        const page = context.getPageById(request.params.pageId);
-        context.selectPage(page);
-        response.setIncludePages(true);
-        if (request.params.bringToFront) {
-            await page.pptrPage.bringToFront();
-        }
-    },
-});
-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: {
-        pageId: zod.number().describe('The ID of the page to close. Call list_pages to list pages.'),
-    },
-    handler: async (request, response, context) => {
-        try {
-            await context.closePage(request.params.pageId);
-        }
-        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: `Open a new tab and load a URL. Use project URL if not specified otherwise.`,
-    annotations: {
-        category: ToolCategory.NAVIGATION,
-        readOnlyHint: false,
-    },
-    schema: {
-        url: zod.string().describe('URL to load in a new page.'),
-        background: zod
-            .boolean()
-            .optional()
-            .describe('Whether to open the page in the background without bringing it to the front. Default is false (foreground).'),
-        isolatedContext: zod
-            .string()
-            .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.'),
-        ...timeoutSchema,
-    },
-    handler: async (request, response, context) => {
-        const page = await context.newPage(request.params.background, request.params.isolatedContext);
-        await context.waitForEventsAfterAction(async () => {
-            await page.pptrPage.goto(request.params.url, {
-                timeout: request.params.timeout,
-            });
-        }, { timeout: request.params.timeout });
-        response.setIncludePages(true);
-    },
-});
-export const navigatePage = definePageTool({
-    name: 'navigate_page',
-    description: `Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.`,
-    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.'),
-        handleBeforeUnload: zod
-            .enum(['accept', 'decline'])
-            .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.'),
-        ...timeoutSchema,
-    },
-    handler: async (request, response, context) => {
-        const page = request.page;
-        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';
-        }
-        const handleBeforeUnload = request.params.handleBeforeUnload ?? 'accept';
-        const dialogHandler = (dialog) => {
-            if (dialog.type() === 'beforeunload') {
-                if (handleBeforeUnload === 'accept') {
-                    response.appendResponseLine(`Accepted a beforeunload dialog.`);
-                    void dialog.accept();
-                }
-                else {
-                    response.appendResponseLine(`Declined a beforeunload dialog.`);
-                    void dialog.dismiss();
-                }
-                // We are not going to report the dialog like regular dialogs.
-                page.clearDialog();
-            }
-        };
-        let initScriptId;
-        if (request.params.initScript) {
-            const { identifier } = await page.pptrPage.evaluateOnNewDocument(request.params.initScript);
-            initScriptId = identifier;
-        }
-        page.pptrPage.on('dialog', dialogHandler);
-        try {
-            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.pptrPage.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.pptrPage.goBack(options);
-                            response.appendResponseLine(`Successfully navigated back to ${page.pptrPage.url()}.`);
-                        }
-                        catch (error) {
-                            response.appendResponseLine(`Unable to navigate back in the selected page: ${error.message}.`);
-                        }
-                        break;
-                    case 'forward':
-                        try {
-                            await page.pptrPage.goForward(options);
-                            response.appendResponseLine(`Successfully navigated forward to ${page.pptrPage.url()}.`);
-                        }
-                        catch (error) {
-                            response.appendResponseLine(`Unable to navigate forward in the selected page: ${error.message}.`);
-                        }
-                        break;
-                    case 'reload':
-                        try {
-                            await page.pptrPage.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;
-                }
-            }, { timeout: request.params.timeout });
-        }
-        finally {
-            page.pptrPage.off('dialog', dialogHandler);
-            if (initScriptId) {
-                await page.pptrPage.removeScriptToEvaluateOnNewDocument(initScriptId).catch((error) => {
-                    logger(`Failed to remove init script`, error);
-                });
-            }
-        }
-        response.setIncludePages(true);
-    },
-});
-export const resizePage = definePageTool({
-    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 = request.page;
-        try {
-            const browser = page.pptrPage.browser();
-            const windowId = await page.pptrPage.windowId();
-            const bounds = await browser.getWindowBounds(windowId);
-            if (bounds.windowState === 'fullscreen') {
-                // Have to call this twice on Ubuntu when the window is in fullscreen mode.
-                await browser.setWindowBounds(windowId, { windowState: 'normal' });
-                await browser.setWindowBounds(windowId, { windowState: 'normal' });
-            }
-            else if (bounds.windowState !== 'normal') {
-                await browser.setWindowBounds(windowId, { windowState: 'normal' });
-            }
-        }
-        catch {
-            // Window APIs are not supported on all platforms
-        }
-        await page.pptrPage.resize({
-            contentWidth: request.params.width,
-            contentHeight: request.params.height,
-        });
-        response.setIncludePages(true);
-    },
-});
-export const handleDialog = definePageTool({
-    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 page = request.page;
-        const dialog = page.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;
-            }
-        }
-        page.clearDialog();
-        response.setIncludePages(true);
-    },
-});
-export const getTabId = definePageTool({
-    name: 'get_tab_id',
-    description: `Get the tab ID of the page`,
-    annotations: {
-        category: ToolCategory.NAVIGATION,
-        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.`),
-    },
-    handler: async (request, response, context) => {
-        const page = context.getPageById(request.params.pageId);
-        const tabId = page.pptrPage._tabId;
-        response.setTabId(tabId);
-    },
-});

package/build/src/tools/performance.js

@@ -1,190 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import zlib from 'node:zlib';
-import { logger } from '../logger.js';
-import { zod, DevTools } from '../third_party/index.js';
-import { parseRawTraceBuffer, traceResultIsSuccess } from '../trace-processing/parse.js';
-import { ToolCategory } from './categories.js';
-import { definePageTool } from './ToolDefinition.js';
-const filePathSchema = zod
-    .string()
-    .optional()
-    .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.`,
-    annotations: {
-        category: ToolCategory.PERFORMANCE,
-        readOnlyHint: false,
-    },
-    schema: {
-        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.'),
-        autoStop: zod
-            .boolean()
-            .default(true)
-            .describe('Determines if the trace recording should be automatically stopped.'),
-        filePath: filePathSchema,
-    },
-    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 = request.page;
-        const pageUrlForTracing = page.pptrPage.url();
-        if (request.params.reload) {
-            // Before starting the recording, navigate to about:blank to clear out any state.
-            await page.pptrPage.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.pptrPage.tracing.start({
-            categories,
-        });
-        if (request.params.reload) {
-            await page.pptrPage.goto(pageUrlForTracing, {
-                waitUntil: ['load'],
-            });
-        }
-        if (request.params.autoStop) {
-            await new Promise((resolve) => setTimeout(resolve, 5_000));
-            await stopTracingAndAppendOutput(page.pptrPage, response, context, request.params.filePath);
-        }
-        else {
-            response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
-        }
-    },
-});
-export const stopTrace = definePageTool({
-    name: 'performance_stop_trace',
-    description: 'Stop the active performance trace recording on the selected webpage.',
-    annotations: {
-        category: ToolCategory.PERFORMANCE,
-        readOnlyHint: false,
-    },
-    schema: {
-        filePath: filePathSchema,
-    },
-    handler: async (request, response, context) => {
-        if (!context.isRunningPerformanceTrace()) {
-            return;
-        }
-        const page = request.page;
-        await stopTracingAndAppendOutput(page.pptrPage, response, context, request.params.filePath);
-    },
-});
-export const analyzeInsight = definePageTool({
-    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;
-        }
-        response.attachTraceInsight(lastRecording, request.params.insightSetId, request.params.insightName);
-    },
-});
-async function stopTracingAndAppendOutput(page, response, context, filePath) {
-    try {
-        const traceEventsBuffer = await page.tracing.stop();
-        if (filePath && traceEventsBuffer) {
-            let dataToWrite = traceEventsBuffer;
-            if (filePath.endsWith('.gz')) {
-                dataToWrite = await new Promise((resolve, reject) => {
-                    zlib.gzip(traceEventsBuffer, (error, result) => {
-                        if (error) {
-                            reject(error);
-                        }
-                        else {
-                            resolve(result);
-                        }
-                    });
-                });
-            }
-            const file = await context.saveFile(dataToWrite, filePath);
-            response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
-        }
-        const result = await parseRawTraceBuffer(traceEventsBuffer);
-        response.appendResponseLine('The performance trace has been stopped.');
-        if (traceResultIsSuccess(result)) {
-            if (context.isCruxEnabled()) {
-                await populateCruxData(result);
-            }
-            context.storeTraceRecording(result);
-            response.attachTraceSummary(result);
-        }
-        else {
-            throw new Error(`There was an unexpected error parsing the trace: ${result.error}`);
-        }
-    }
-    finally {
-        context.setIsRunningPerformanceTrace(false);
-    }
-}
-/** We tell CrUXManager to fetch data so it's available when DevTools.PerformanceTraceFormatter is invoked */
-async function populateCruxData(result) {
-    logger('populateCruxData called');
-    const cruxManager = DevTools.CrUXManager.instance();
-    // go/jtfbx. Yes, we're aware this API key is public. ;)
-    cruxManager.setEndpointForTesting('https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=AIzaSyBn5gimNjhiEyA_euicSKko6IlD3HdgUfk');
-    const cruxSetting = DevTools.Common.Settings.Settings.instance().createSetting('field-data', {
-        enabled: true,
-    });
-    cruxSetting.set({ enabled: true });
-    // Gather URLs to fetch CrUX data for
-    const urls = [...(result.parsedTrace.insights?.values() ?? [])].map((c) => c.url.toString());
-    urls.push(result.parsedTrace.data.Meta.mainFrameURL);
-    const urlSet = new Set(urls);
-    if (urlSet.size === 0) {
-        logger('No URLs found for CrUX data');
-        return;
-    }
-    logger(`Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`);
-    const cruxData = await Promise.all(Array.from(urlSet).map(async (url) => {
-        const data = await cruxManager.getFieldDataForPage(url);
-        logger(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
-        return data;
-    }));
-    result.parsedTrace.metadata.cruxFieldData = cruxData;
-}

package/build/src/tools/screencast.js

@@ -1,79 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { zod } from '../third_party/index.js';
-import { ToolCategory } from './categories.js';
-import { definePageTool } from './ToolDefinition.js';
-async function generateTempFilePath() {
-    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
-    return path.join(dir, `screencast.mp4`);
-}
-export const startScreencast = definePageTool({
-    name: 'screencast_start',
-    description: 'Starts recording a screencast (video) of the selected page in mp4 format.',
-    annotations: {
-        category: ToolCategory.DEBUGGING,
-        readOnlyHint: false,
-        conditions: ['screencast'],
-    },
-    schema: {
-        path: zod
-            .string()
-            .optional()
-            .describe('Output path. Uses mkdtemp to generate a unique path if not provided.'),
-    },
-    handler: async (request, response, context) => {
-        if (context.getScreenRecorder() !== null) {
-            response.appendResponseLine('Error: a screencast recording is already in progress. Use screencast_stop to stop it before starting a new one.');
-            return;
-        }
-        const filePath = request.params.path ?? (await generateTempFilePath());
-        const resolvedPath = path.resolve(filePath);
-        const page = request.page;
-        let recorder;
-        try {
-            recorder = await page.pptrPage.screencast({
-                path: resolvedPath,
-                format: 'mp4',
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (message.includes('ENOENT') && message.includes('ffmpeg')) {
-                throw new Error('ffmpeg is required for screencast recording but was not found. ' +
-                    'Install ffmpeg (https://ffmpeg.org/) and ensure it is available in your PATH.');
-            }
-            throw err;
-        }
-        context.setScreenRecorder({ recorder, filePath: resolvedPath });
-        response.appendResponseLine(`Screencast recording started. The recording will be saved to ${resolvedPath}. Use ${stopScreencast.name} to stop recording.`);
-    },
-});
-export const stopScreencast = definePageTool({
-    name: 'screencast_stop',
-    description: 'Stops the active screencast recording on the selected page.',
-    annotations: {
-        category: ToolCategory.DEBUGGING,
-        readOnlyHint: false,
-        conditions: ['screencast'],
-    },
-    schema: {},
-    handler: async (_request, response, context) => {
-        const data = context.getScreenRecorder();
-        if (!data) {
-            return;
-        }
-        try {
-            await data.recorder.stop();
-            response.appendResponseLine(`The screencast recording has been stopped and saved to ${data.filePath}.`);
-        }
-        finally {
-            context.setScreenRecorder(null);
-        }
-    },
-});

package/build/src/tools/screenshot.js

@@ -1,84 +0,0 @@
-/**
- * @license
- * Copyright 2025 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 screenshot = definePageTool({
-    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 request.page.getElementByUid(request.params.uid);
-        }
-        else {
-            pageOrHandle = request.page.pptrPage;
-        }
-        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 { filepath } = await context.saveTemporaryFile(screenshot, `screenshot.${request.params.format}`);
-            response.appendResponseLine(`Saved screenshot to ${filepath}.`);
-        }
-        else {
-            response.attachImage({
-                mimeType: `image/${request.params.format}`,
-                data: Buffer.from(screenshot).toString('base64'),
-            });
-        }
-    },
-});