@mcp-b/chrome-devtools-mcp 2.0.13 → 2.2.0

package/build/src/tools/lighthouse.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import { snapshot, navigation, generateReport, zod, } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { startTrace } from './performance.js';
+import { definePageTool } from './ToolDefinition.js';
+export const lighthouseAudit = definePageTool({
+    name: 'lighthouse_audit',
+    description: `Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run ${startTrace.name}`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        mode: zod
+            .enum(['navigation', 'snapshot'])
+            .default('navigation')
+            .describe('"navigation" reloads & audits. "snapshot" analyzes current state.'),
+        device: zod
+            .enum(['desktop', 'mobile'])
+            .default('desktop')
+            .describe('Device to emulate.'),
+        outputDirPath: zod
+            .string()
+            .optional()
+            .describe('Directory for reports. If omitted, uses temporary files.'),
+    },
+    handler: async (request, response, context) => {
+        const page = request.page;
+        const categories = ['accessibility', 'seo', 'best-practices'];
+        const formats = ['json', 'html'];
+        const { mode = 'navigation', device = 'desktop', outputDirPath, } = request.params;
+        const flags = {
+            onlyCategories: categories,
+            output: formats,
+            // Default 30 second timeout for page load.
+            maxWaitForLoad: 30_000,
+        };
+        if (device === 'desktop') {
+            flags.formFactor = 'desktop';
+            flags.screenEmulation = {
+                mobile: false,
+                width: 1350,
+                height: 940,
+                deviceScaleFactor: 1,
+                disabled: false,
+            };
+        }
+        else {
+            flags.formFactor = 'mobile';
+            flags.screenEmulation = {
+                mobile: true,
+                width: 412,
+                height: 823,
+                deviceScaleFactor: 1.75,
+                disabled: false,
+            };
+        }
+        let result;
+        try {
+            if (mode === 'navigation') {
+                result = await navigation(page.pptrPage, page.pptrPage.url(), {
+                    flags,
+                });
+            }
+            else {
+                result = await snapshot(page.pptrPage, {
+                    flags,
+                });
+            }
+            if (!result) {
+                throw new Error('Lighthouse audit failed.');
+            }
+        }
+        finally {
+            await context.restoreEmulation(page);
+        }
+        const lhr = result.lhr;
+        const reportPaths = [];
+        const encoder = new TextEncoder();
+        for (const format of formats) {
+            const report = generateReport(lhr, format);
+            const data = encoder.encode(report);
+            if (outputDirPath) {
+                const reportPath = path.join(outputDirPath, `report.${format}`);
+                const { filename } = await context.saveFile(data, reportPath);
+                reportPaths.push(filename);
+            }
+            else {
+                const { filepath } = await context.saveTemporaryFile(data, `report.${format}`);
+                reportPaths.push(filepath);
+            }
+        }
+        const categoryScores = Object.values(lhr.categories).map(c => ({
+            id: c.id,
+            title: c.title,
+            score: c.score,
+        }));
+        const failedAudits = Object.values(lhr.audits).filter(a => a.score !== null && a.score < 1).length;
+        const passedAudits = Object.values(lhr.audits).filter(a => a.score === 1).length;
+        const output = {
+            summary: {
+                mode,
+                device,
+                url: lhr.mainDocumentUrl,
+                scores: categoryScores,
+                audits: {
+                    failed: failedAudits,
+                    passed: passedAudits,
+                },
+                timing: {
+                    total: lhr.timing.total,
+                },
+            },
+            reports: reportPaths,
+        };
+        response.attachLighthouseResult(output);
+    },
+});

package/build/src/tools/memory.js

@@ -0,0 +1,28 @@
+/**
+ * @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 takeMemorySnapshot = definePageTool({
+    name: 'take_memory_snapshot',
+    description: `Capture a memory heapsnapshot of the currently selected page to memory leak debugging`,
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        filePath: zod
+            .string()
+            .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),
+    },
+    handler: async (request, response, _context) => {
+        const page = request.page;
+        await page.pptrPage.captureHeapSnapshot({
+            path: request.params.filePath,
+        });
+        response.appendResponseLine(`Heap snapshot saved to ${request.params.filePath}`);
+    },
+});

package/build/src/tools/network.js

@@ -5,7 +5,7 @@
  */
 import { zod } from '../third_party/index.js';
 import { ToolCategory } from './categories.js';
-import { defineTool } from './ToolDefinition.js';
+import { definePageTool } from './ToolDefinition.js';
 const FILTERABLE_RESOURCE_TYPES = [
     'document',
     'stylesheet',
@@ -27,7 +27,7 @@ const FILTERABLE_RESOURCE_TYPES = [
     'fedcm',
     'other',
 ];
-export const listNetworkRequests = defineTool({
+export const listNetworkRequests = definePageTool({
     name: 'list_network_requests',
     description: `List all requests for the currently selected page since the last navigation.`,
     annotations: {
@@ -58,10 +58,10 @@ export const listNetworkRequests = defineTool({
             .describe('Set to true to return the preserved requests over the last 3 navigations.'),
     },
     handler: async (request, response, context) => {
-        const data = await context.getDevToolsData();
+        const data = await context.getDevToolsData(request.page);
         response.attachDevToolsData(data);
         const reqid = data?.cdpRequestId
-            ? context.resolveCdpRequestId(data.cdpRequestId)
+            ? context.resolveCdpRequestId(request.page, data.cdpRequestId)
             : undefined;
         response.setIncludeNetworkRequests(true, {
             pageSize: request.params.pageSize,
@@ -72,31 +72,45 @@ export const listNetworkRequests = defineTool({
         });
     },
 });
-export const getNetworkRequest = defineTool({
+export const getNetworkRequest = definePageTool({
     name: 'get_network_request',
     description: `Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel.`,
     annotations: {
         category: ToolCategory.NETWORK,
-        readOnlyHint: true,
+        readOnlyHint: false,
     },
     schema: {
         reqid: zod
             .number()
             .optional()
             .describe('The reqid of the network request. If omitted returns the currently selected request in the DevTools Network panel.'),
+        requestFilePath: zod
+            .string()
+            .optional()
+            .describe('The absolute or relative path to save the request body to. If omitted, the body is returned inline.'),
+        responseFilePath: zod
+            .string()
+            .optional()
+            .describe('The absolute or relative path to save the response body to. If omitted, the body is returned inline.'),
     },
     handler: async (request, response, context) => {
         if (request.params.reqid) {
-            response.attachNetworkRequest(request.params.reqid);
+            response.attachNetworkRequest(request.params.reqid, {
+                requestFilePath: request.params.requestFilePath,
+                responseFilePath: request.params.responseFilePath,
+            });
         }
         else {
-            const data = await context.getDevToolsData();
+            const data = await context.getDevToolsData(request.page);
             response.attachDevToolsData(data);
             const reqid = data?.cdpRequestId
-                ? context.resolveCdpRequestId(data.cdpRequestId)
+                ? context.resolveCdpRequestId(request.page, data.cdpRequestId)
                 : undefined;
             if (reqid) {
-                response.attachNetworkRequest(reqid);
+                response.attachNetworkRequest(reqid, {
+                    requestFilePath: request.params.requestFilePath,
+                    responseFilePath: request.params.responseFilePath,
+                });
             }
             else {
                 response.appendResponseLine(`Nothing is currently selected in the DevTools Network panel.`);

package/build/src/tools/pages.js

@@ -6,18 +6,20 @@
 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);
-    },
+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',
@@ -27,22 +29,21 @@ export const selectPage = defineTool({
         readOnlyHint: true,
     },
     schema: {
-        pageIdx: zod
+        pageId: zod
             .number()
-            .describe(`The index of the page to select. Call ${listPages.name} to get available pages.`),
+            .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.getPageByIdx(request.params.pageIdx);
-        // Mark as explicitly selected so this session stays on this page
-        context.selectPage(page, true);
+        const page = context.getPageById(request.params.pageId);
+        context.selectPage(page);
+        response.setIncludePages(true);
         if (request.params.bringToFront) {
-            await page.bringToFront();
+            await page.pptrPage.bringToFront();
         }
-        response.setIncludePages(true);
     },
 });
 export const closePage = defineTool({
@@ -53,13 +54,13 @@ export const closePage = defineTool({
         readOnlyHint: false,
     },
     schema: {
-        pageIdx: zod
+        pageId: zod
             .number()
-            .describe('The index of the page to close. Call list_pages to list pages.'),
+            .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.pageIdx);
+            await context.closePage(request.params.pageId);
         }
         catch (err) {
             if (err.message === CLOSE_PAGE_ERROR) {
@@ -74,28 +75,38 @@ export const closePage = defineTool({
 });
 export const newPage = defineTool({
     name: 'new_page',
-    description: `Creates a 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();
+        const page = await context.newPage(request.params.background, request.params.isolatedContext);
         await context.waitForEventsAfterAction(async () => {
-            await page.goto(request.params.url, {
+            await page.pptrPage.goto(request.params.url, {
                 timeout: request.params.timeout,
             });
-        });
+        }, { timeout: request.params.timeout });
         response.setIncludePages(true);
     },
 });
-export const navigatePage = defineTool({
+export const navigatePage = definePageTool({
     name: 'navigate_page',
-    description: `Navigates the currently selected page to a URL.`,
+    description: `Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.`,
     annotations: {
         category: ToolCategory.NAVIGATION,
         readOnlyHint: false,
@@ -110,76 +121,110 @@ export const navigatePage = defineTool({
             .boolean()
             .optional()
             .describe('Whether to ignore cache on reload.'),
-        bypassCSP: zod
-            .boolean()
+        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('Bypass Content-Security-Policy on the page. Useful for injecting scripts into third-party sites during development.'),
+            .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 = context.getSelectedPage();
+        const page = request.page;
         const options = {
             timeout: request.params.timeout,
         };
-        if (request.params.bypassCSP !== undefined) {
-            await context.setBypassCSP(request.params.bypassCSP);
-        }
         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;
+        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 = defineTool({
+export const resizePage = definePageTool({
     name: 'resize_page',
     description: `Resizes the selected page's window so that the page has specified dimension`,
     annotations: {
@@ -190,16 +235,32 @@ export const resizePage = defineTool({
         width: zod.number().describe('Page width'),
         height: zod.number().describe('Page height'),
     },
-    handler: async (request, response, context) => {
-        const page = context.getSelectedPage();
-        await page.resize({
+    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 = defineTool({
+export const handleDialog = definePageTool({
     name: 'handle_dialog',
     description: `If a browser dialog was opened, use this command to handle it`,
     annotations: {
@@ -215,8 +276,9 @@ export const handleDialog = defineTool({
             .optional()
             .describe('Optional prompt text to enter into the dialog.'),
     },
-    handler: async (request, response, context) => {
-        const dialog = context.getDialog();
+    handler: async (request, response, _context) => {
+        const page = request.page;
+        const dialog = page.getDialog();
         if (!dialog) {
             throw new Error('No open dialog found');
         }
@@ -244,7 +306,26 @@ export const handleDialog = defineTool({
                 break;
             }
         }
-        context.clearDialog();
+        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);
+    },
+});