chrome-devtools-mcp 0.21.0 → 0.23.0

package/build/src/tools/pages.js

@@ -7,10 +7,55 @@ 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';
+async function navigateWithInterception(page, action, allowListString, timeout) {
+    const allowList = allowListString
+        ? allowListString.split(',').map((p) => new URLPattern(p.trim()))
+        : undefined;
+    const requestHandler = (interceptedRequest) => {
+        if (!interceptedRequest.isNavigationRequest()) {
+            void interceptedRequest.continue();
+            return;
+        }
+        const requestUrl = interceptedRequest.url();
+        const isAllowed = allowList.some((pattern) => pattern.test(requestUrl));
+        if (isAllowed) {
+            void interceptedRequest.continue();
+        }
+        else {
+            logger(`Blocking request to: ${requestUrl}`);
+            void interceptedRequest.abort('blockedbyclient');
+        }
+    };
+    const cleanupInterception = async () => {
+        if (allowList) {
+            page.pptrPage.off('request', requestHandler);
+            await page.pptrPage.setRequestInterception(false).catch(error => {
+                logger(`Failed to disable request interception`, error);
+            });
+        }
+    };
+    if (allowList) {
+        await page.pptrPage.setRequestInterception(true);
+        page.pptrPage.on('request', requestHandler);
+    }
+    try {
+        await page.waitForEventsAfterAction(async () => {
+            try {
+                await action();
+            }
+            finally {
+                await cleanupInterception();
+            }
+        }, { timeout });
+    }
+    finally {
+        await cleanupInterception();
+    }
+}
 export const listPages = defineTool(args => {
     return {
         name: 'list_pages',
-        description: `Get a list of pages ${args?.categoryExtensions ? 'including extension service workers' : ''} open in the browser.`,
+        description: `Get a list of pages${args?.categoryExtensions ? ' including extension service workers' : ''} open in the browser.`,
         annotations: {
             category: ToolCategory.NAVIGATION,
             readOnlyHint: true,
@@ -19,6 +64,7 @@ export const listPages = defineTool(args => {
         handler: async (_request, response) => {
             response.setIncludePages(true);
             response.setListInPageTools();
+            response.setListWebMcpTools();
         },
     };
 });
@@ -43,6 +89,7 @@ export const selectPage = defineTool({
         context.selectPage(page);
         response.setIncludePages(true);
         response.setListInPageTools();
+        response.setListWebMcpTools();
         if (request.params.bringToFront) {
             await page.pptrPage.bringToFront();
         }
@@ -76,158 +123,177 @@ export const closePage = defineTool({
         response.setListInPageTools();
     },
 });
-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, {
+export const newPage = defineTool(args => {
+    return {
+        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.'),
+            ...(args?.experimentalNavigationAllowlist
+                ? {
+                    allowList: zod
+                        .string()
+                        .optional()
+                        .describe('Optional comma-separated list of URL patterns to allow. If provided, all other navigations will be blocked.'),
+                }
+                : {}),
+            ...timeoutSchema,
+        },
+        handler: async (request, response, context) => {
+            const page = await context.newPage(request.params.background, request.params.isolatedContext);
+            await navigateWithInterception(page, () => page.pptrPage.goto(request.params.url, {
                 timeout: request.params.timeout,
-            });
-        }, { timeout: request.params.timeout });
-        response.setIncludePages(true);
-        response.setListInPageTools();
-    },
+            }), request.params.allowList, request.params.timeout);
+            response.setIncludePages(true);
+            response.setListInPageTools();
+        },
+    };
 });
-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();
+export const navigatePage = definePageTool(args => {
+    return {
+        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.'),
+            ...(args?.experimentalNavigationAllowlist
+                ? {
+                    allowList: zod
+                        .string()
+                        .optional()
+                        .describe('Optional comma-separated list of URL patterns to allow. If provided, all other navigations will be blocked.'),
                 }
-                else {
-                    response.appendResponseLine(`Declined a beforeunload dialog.`);
-                    void dialog.dismiss();
+                : {}),
+            ...timeoutSchema,
+        },
+        handler: async (request, response) => {
+            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();
                 }
-                // 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;
             }
-        };
-        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;
+            page.pptrPage.on('dialog', dialogHandler);
+            try {
+                await navigateWithInterception(page, 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;
+                    }
+                }, request.params.allowList, 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);
+                    });
                 }
-            }, { 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);
-        response.setListInPageTools();
-    },
+            response.setIncludePages(true);
+            response.setListInPageTools();
+            response.setListWebMcpTools();
+        },
+    };
 });
 export const resizePage = definePageTool({
     name: 'resize_page',

package/build/src/tools/performance.js

@@ -142,7 +142,7 @@ async function stopTracingAndAppendOutput(page, response, context, filePath) {
                     });
                 });
             }
-            const file = await context.saveFile(dataToWrite, filePath);
+            const file = await context.saveFile(dataToWrite, filePath, filePath.endsWith('.gz') ? '.json.gz' : '.json');
             response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
         }
         const result = await parseRawTraceBuffer(traceEventsBuffer);

package/build/src/tools/screencast.js

@@ -7,39 +7,51 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { zod } from '../third_party/index.js';
+import { ensureExtension } from '../utils/files.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({
+const supportedExtensions = ['.webm', '.mp4'];
+export const startScreencast = definePageTool(args => ({
     name: 'screencast_start',
-    description: 'Starts recording a screencast (video) of the selected page in mp4 format.',
+    description: `Starts recording a screencast (video) of the selected page in specified format.`,
     annotations: {
         category: ToolCategory.DEBUGGING,
         readOnlyHint: false,
         conditions: ['screencast'],
     },
     schema: {
-        path: zod
+        filePath: zod
             .string()
             .optional()
-            .describe('Output path. Uses mkdtemp to generate a unique path if not provided.'),
+            .describe(`Output file path (${supportedExtensions.join(',')} are supported). 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 filePath = request.params.filePath ?? (await generateTempFilePath());
+        let enforcedExtension = '.mp4';
+        let format = 'mp4';
+        for (const supportedExtension of supportedExtensions) {
+            if (filePath.endsWith(supportedExtension)) {
+                enforcedExtension = supportedExtension;
+                format = supportedExtension.substring(1);
+                break;
+            }
+        }
+        const resolvedPath = ensureExtension(path.resolve(filePath), enforcedExtension);
         const page = request.page;
         let recorder;
         try {
             recorder = await page.pptrPage.screencast({
                 path: resolvedPath,
-                format: 'mp4',
+                format: format,
+                ffmpegPath: args?.experimentalFfmpegPath,
             });
         }
         catch (err) {
@@ -53,7 +65,7 @@ export const startScreencast = definePageTool({
         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.',

package/build/src/tools/screenshot.js

@@ -28,7 +28,7 @@ export const screenshot = definePageTool({
         uid: zod
             .string()
             .optional()
-            .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
+            .describe('The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.'),
         fullPage: zod
             .boolean()
             .optional()
@@ -67,8 +67,8 @@ export const screenshot = definePageTool({
             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}.`);
+            const result = await context.saveFile(screenshot, request.params.filePath, `.${format}`);
+            response.appendResponseLine(`Saved screenshot to ${result.filename}.`);
         }
         else if (screenshot.length >= 2_000_000) {
             const { filepath } = await context.saveTemporaryFile(screenshot, `screenshot.${request.params.format}`);

package/build/src/tools/script.js

@@ -9,7 +9,7 @@ import { defineTool, pageIdSchema } from './ToolDefinition.js';
 export const evaluateScript = defineTool(cliArgs => {
     return {
         name: 'evaluate_script',
-        description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,
+        description: `Evaluate a JavaScript function inside the currently selected page${cliArgs?.categoryExtensions ? ' or service worker' : ''}. Returns the response as JSON,
 so returned values have to be JSON-serializable.`,
         annotations: {
             category: ToolCategory.DEBUGGING,
@@ -32,18 +32,22 @@ Example with arguments: \`(el) => {
                 .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.`),
+            dialogAction: zod
+                .string()
+                .optional()
+                .describe('Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.'),
             ...(cliArgs?.experimentalPageIdRouting ? pageIdSchema : {}),
             ...(cliArgs?.categoryExtensions
                 ? {
                     serviceWorkerId: zod
                         .string()
                         .optional()
-                        .describe(`An optional service worker id to evaluate the script in.`),
+                        .describe(`The optional service worker id to evaluate the script in. If provided, 'pageId' should be omitted. Note: 'args' (element UIDs) cannot be used when evaluating in a service worker.`),
                 }
                 : {}),
         },
         handler: async (request, response, context) => {
-            const { serviceWorkerId, args: uidArgs, function: fnString, pageId, } = request.params;
+            const { serviceWorkerId, args: uidArgs, function: fnString, pageId, dialogAction, } = request.params;
             if (cliArgs?.categoryExtensions && serviceWorkerId) {
                 if (uidArgs && uidArgs.length > 0) {
                     throw new Error('args (element uids) cannot be used when evaluating in a service worker.');
@@ -52,7 +56,9 @@ Example with arguments: \`(el) => {
                     throw new Error('specify either a pageId or a serviceWorkerId.');
                 }
                 const worker = await getWebWorker(context, serviceWorkerId);
-                await performEvaluation(worker, fnString, [], response, context);
+                await context.getSelectedMcpPage().waitForEventsAfterAction(async () => {
+                    await performEvaluation(worker, fnString, [], response);
+                }, { handleDialog: dialogAction ?? 'accept' });
                 return;
             }
             const mcpPage = cliArgs?.experimentalPageIdRouting
@@ -68,7 +74,9 @@ Example with arguments: \`(el) => {
                     args.push(handle);
                 }
                 const evaluatable = await getPageOrFrame(page, frames);
-                await performEvaluation(evaluatable, fnString, args, response, context);
+                await mcpPage.waitForEventsAfterAction(async () => {
+                    await performEvaluation(evaluatable, fnString, args, response);
+                }, { handleDialog: dialogAction ?? 'accept' });
             }
             finally {
                 void Promise.allSettled(args.map(arg => arg.dispose()));
@@ -76,19 +84,17 @@ Example with arguments: \`(el) => {
         },
     };
 });
-const performEvaluation = async (evaluatable, fnString, args, response, context) => {
+const performEvaluation = async (evaluatable, fnString, args, response) => {
     const fn = await evaluatable.evaluateHandle(`(${fnString})`);
     try {
-        await context.waitForEventsAfterAction(async () => {
-            const result = await evaluatable.evaluate(async (fn, ...args) => {
-                // @ts-expect-error no types for function fn
-                return JSON.stringify(await fn(...args));
-            }, fn, ...args);
-            response.appendResponseLine('Script ran on page and returned:');
-            response.appendResponseLine('```json');
-            response.appendResponseLine(`${result}`);
-            response.appendResponseLine('```');
-        });
+        const result = await evaluatable.evaluate(async (fn, ...args) => {
+            // @ts-expect-error no types for function fn
+            return JSON.stringify(await fn(...args));
+        }, fn, ...args);
+        response.appendResponseLine('Script ran on page and returned:');
+        response.appendResponseLine('```json');
+        response.appendResponseLine(`${result}`);
+        response.appendResponseLine('```');
     }
     finally {
         void fn.dispose();

package/build/src/tools/tools.js

@@ -18,6 +18,7 @@ import * as screenshotTools from './screenshot.js';
 import * as scriptTools from './script.js';
 import * as slimTools from './slim/tools.js';
 import * as snapshotTools from './snapshot.js';
+import * as webmcpTools from './webmcp.js';
 export const createTools = (args) => {
     const rawTools = args.slim
         ? Object.values(slimTools)
@@ -36,6 +37,7 @@ export const createTools = (args) => {
             ...Object.values(screenshotTools),
             ...Object.values(scriptTools),
             ...Object.values(snapshotTools),
+            ...Object.values(webmcpTools),
         ];
     const tools = [];
     for (const tool of rawTools) {