opera-devtools-mcp 0.2.3 → 0.3.0

package/build/src/tools/pages.js

@@ -3,55 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { logger } from '../logger.js';
 import { zod } from '../third_party/index.js';
+import { logger } from '../utils/logger.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',
@@ -62,6 +17,7 @@ export const listPages = defineTool(args => {
         },
         schema: {},
         blockedByDialog: false,
+        verifyFilesSchema: {},
         handler: async (_request, response) => {
             response.setIncludePages(true);
             response.setListThirdPartyDeveloperTools();
@@ -86,6 +42,7 @@ export const selectPage = defineTool({
             .describe('Whether to focus the page and bring it to the top.'),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (request, response, context) => {
         const page = context.getPageById(request.params.pageId);
         context.selectPage(page);
@@ -110,6 +67,7 @@ export const closePage = defineTool({
             .describe('The ID of the page to close. Call list_pages to list pages.'),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (request, response, context) => {
         try {
             await context.closePage(request.params.pageId);
@@ -126,7 +84,7 @@ export const closePage = defineTool({
         response.setListThirdPartyDeveloperTools();
     },
 });
-export const newPage = defineTool(args => {
+export const newPage = defineTool(() => {
     return {
         name: 'new_page',
         description: `Open a new tab and load a URL. Use project URL if not specified otherwise.`,
@@ -146,28 +104,23 @@ export const newPage = defineTool(args => {
                 .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,
         },
         blockedByDialog: false,
+        verifyFilesSchema: {},
         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,
-            }), request.params.allowList, request.params.timeout);
+            await page.waitForEventsAfterAction(async () => {
+                await page.pptrPage.goto(request.params.url, {
+                    timeout: request.params.timeout,
+                });
+            }, { timeout: request.params.timeout });
             response.setIncludePages(true);
             response.setListThirdPartyDeveloperTools();
         },
     };
 });
-export const navigatePage = definePageTool(args => {
+export const navigatePage = definePageTool(() => {
     return {
         name: 'navigate_page',
         description: `Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.`,
@@ -186,24 +139,17 @@ export const navigatePage = definePageTool(args => {
                 .optional()
                 .describe('Whether to ignore cache on reload.'),
             handleBeforeUnload: zod
-                .enum(['accept', 'decline'])
+                .enum(['accept', 'dismiss'])
                 .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.'),
-                }
-                : {}),
             ...timeoutSchema,
         },
         blockedByDialog: false,
+        verifyFilesSchema: {},
         handler: async (request, response) => {
             const page = request.page;
             const options = {
@@ -215,29 +161,14 @@ export const navigatePage = definePageTool(args => {
             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 navigateWithInterception(page, async () => {
+                const action = request.params.handleBeforeUnload ?? 'accept';
+                const result = await page.waitForEventsAfterAction(async () => {
                     switch (request.params.type) {
                         case 'url':
                             if (!request.params.url) {
@@ -282,15 +213,21 @@ export const navigatePage = definePageTool(args => {
                             }
                             break;
                     }
-                }, request.params.allowList, request.params.timeout);
+                }, {
+                    timeout: request.params.timeout,
+                    handleDialog: { beforeunload: action },
+                });
+                if (result.dialogHandled) {
+                    response.appendResponseLine(`${action === 'dismiss' ? 'Dismissed' : 'Accepted'} a beforeunload dialog.`);
+                    page.clearDialog();
+                }
             }
             finally {
-                page.pptrPage.off('dialog', dialogHandler);
                 if (initScriptId) {
                     await page.pptrPage
                         .removeScriptToEvaluateOnNewDocument(initScriptId)
                         .catch(error => {
-                        logger(`Failed to remove init script`, error);
+                        logger?.(`Failed to remove init script`, error);
                     });
                 }
             }
@@ -312,7 +249,8 @@ export const resizePage = definePageTool({
         height: zod.number().describe('Page height'),
     },
     blockedByDialog: false,
-    handler: async (request, response, _context) => {
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
         const page = request.page;
         try {
             const browser = page.pptrPage.browser();
@@ -354,7 +292,8 @@ export const handleDialog = definePageTool({
             .describe('Optional prompt text to enter into the dialog.'),
     },
     blockedByDialog: false,
-    handler: async (request, response, _context) => {
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
         const page = request.page;
         const dialog = page.getDialog();
         if (!dialog) {
@@ -367,7 +306,7 @@ export const handleDialog = definePageTool({
                 }
                 catch (err) {
                     // Likely already handled by the user outside of MCP.
-                    logger(err);
+                    logger?.(err);
                 }
                 response.appendResponseLine('Successfully accepted the dialog');
                 break;
@@ -378,7 +317,7 @@ export const handleDialog = definePageTool({
                 }
                 catch (err) {
                     // Likely already handled.
-                    logger(err);
+                    logger?.(err);
                 }
                 response.appendResponseLine('Successfully dismissed the dialog');
                 break;
@@ -402,10 +341,12 @@ export const getTabId = definePageTool({
             .describe(`The ID of the page to get the tab ID for. Call ${listPages().name} to get available pages.`),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (request, response, context) => {
         const page = context.getPageById(request.params.pageId);
         const tabId = page.pptrPage._tabId;
         response.setTabId(tabId);
+        response.appendResponseLine(`Tab ID: ${tabId}`);
     },
 });
 //# sourceMappingURL=pages.js.map

package/build/src/tools/performance.js

@@ -4,9 +4,9 @@
  * 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 { parseRawTraceBuffer, traceResultIsSuccess, } from '../processors/PerformanceTrace.js';
+import { logger } from '../utils/logger.js';
 import { ToolCategory } from './categories.js';
 import { definePageTool } from './ToolDefinition.js';
 const filePathSchema = zod
@@ -32,8 +32,10 @@ export const startTrace = definePageTool({
         filePath: filePathSchema,
     },
     blockedByDialog: true,
+    verifyFilesSchema: {
+        filePath: true,
+    },
     handler: async (request, response, context) => {
-        context.validatePath(request.params.filePath);
         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;
@@ -41,47 +43,54 @@ export const startTrace = definePageTool({
         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'],
+        try {
+            if (request.params.reload) {
+                // Before starting the recording, navigate to about:blank to clear out any state.
+                // We use `load` because `networkidle0` is known to be flaky for about:blank in Puppeteer.
+                await page.pptrPage.goto('about:blank', {
+                    waitUntil: 'load',
+                });
+            }
+            const categories = [
+                '-*',
+                ...DevTools.TracingDefaultCategories,
+                // These categories are optional in DevTools, but enabled by default in the DevTools UI, so we enable them here too.
+                ...DevTools.TracingOptionalCategories.JsSampling,
+                ...DevTools.TracingOptionalCategories.Screenshot,
+            ];
+            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, response, context, request.params.filePath);
+            }
+            else {
+                response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
+            }
         }
-        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.`);
+        catch (error) {
+            // If a setup step (navigation, tracing.start) throws before
+            // stopTracingAndAppendOutput runs, the running flag would otherwise stay
+            // stuck `true` for the rest of the session, blocking all future traces.
+            // Unwind here: stop tracing if it was started and clear the flag. When
+            // autoStop already ran stopTracingAndAppendOutput the flag is already
+            // false and this is a no-op.
+            if (context.isRunningPerformanceTrace()) {
+                try {
+                    await page.pptrPage.tracing.stop();
+                }
+                catch {
+                    // Tracing may not have started yet; ignore.
+                }
+                context.setIsRunningPerformanceTrace(false);
+            }
+            throw error;
         }
     },
 });
@@ -96,13 +105,15 @@ export const stopTrace = definePageTool({
         filePath: filePathSchema,
     },
     blockedByDialog: true,
+    verifyFilesSchema: {
+        filePath: true,
+    },
     handler: async (request, response, context) => {
-        context.validatePath(request.params.filePath);
         if (!context.isRunningPerformanceTrace()) {
             return;
         }
         const page = request.page;
-        await stopTracingAndAppendOutput(page.pptrPage, response, context, request.params.filePath);
+        await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
     },
 });
 export const analyzeInsight = definePageTool({
@@ -121,6 +132,7 @@ export const analyzeInsight = definePageTool({
             .describe('The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"'),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (request, response, context) => {
         const lastRecording = context.recordedTraces().at(-1);
         if (!lastRecording) {
@@ -132,7 +144,7 @@ export const analyzeInsight = definePageTool({
 });
 async function stopTracingAndAppendOutput(page, response, context, filePath) {
     try {
-        const traceEventsBuffer = await page.tracing.stop();
+        const traceEventsBuffer = await page.pptrPage.tracing.stop();
         if (filePath && traceEventsBuffer) {
             let dataToWrite = traceEventsBuffer;
             if (filePath.endsWith('.gz')) {
@@ -147,10 +159,13 @@ async function stopTracingAndAppendOutput(page, response, context, filePath) {
                     });
                 });
             }
-            const file = await context.saveFile(dataToWrite, filePath, filePath.endsWith('.gz') ? '.json.gz' : '.json');
+            const file = await context.saveFile(dataToWrite, filePath, filePath.endsWith('.gz') ? '.gz' : '.json');
             response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
         }
-        const result = await parseRawTraceBuffer(traceEventsBuffer);
+        const result = await parseRawTraceBuffer(traceEventsBuffer, {
+            cpuThrottling: page.cpuThrottlingRate,
+            networkThrottling: page.networkConditions ?? undefined,
+        });
         response.appendResponseLine('The performance trace has been stopped.');
         if (traceResultIsSuccess(result)) {
             if (context.isCruxEnabled()) {
@@ -169,8 +184,8 @@ async function stopTracingAndAppendOutput(page, response, context, filePath) {
 }
 /** 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();
+    logger?.('populateCruxData called');
+    const cruxManager = DevTools.CrUXManager.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', {
@@ -182,13 +197,13 @@ async function populateCruxData(result) {
     urls.push(result.parsedTrace.data.Meta.mainFrameURL);
     const urlSet = new Set(urls);
     if (urlSet.size === 0) {
-        logger('No URLs found for CrUX data');
+        logger?.('No URLs found for CrUX data');
         return;
     }
-    logger(`Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`);
+    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'}`);
+        logger?.(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
         return data;
     }));
     result.parsedTrace.metadata.cruxFieldData = cruxData;

package/build/src/tools/pwa.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2026 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 manifestIdSchema = zod
+    .string()
+    .describe('The manifest ID of the web app: the resolved `id` member of its manifest. ' +
+    'If `id` is omitted, it defaults to the resolved `start_url` ' +
+    '(e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.');
+const displayModeSchema = zod
+    .enum(['standalone', 'browser'])
+    .optional()
+    .describe('Optional user display mode preference applied after install. ' +
+    '"standalone" opens the app in its own window; "browser" opens it as a ' +
+    'tab. Installs via the PWA CDP domain default to "browser" because they ' +
+    'do not simulate the install dialog, so pass "standalone" to get an ' +
+    'app-window experience.');
+export const installPwa = defineTool({
+    name: 'install_pwa',
+    description: 'Installs a Progressive Web App (PWA) identified by its manifest ID. ' +
+        'This installs through the PWA CDP domain without a user gesture or install ' +
+        'dialog. DevTools installs default to browser display mode.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+        installUrlOrBundleUrl: zod
+            .string()
+            .describe('The location of the app or bundle. For a normal site this is the page ' +
+            'URL; for an Isolated Web App it can be a file:// or http(s):// ' +
+            'signed web bundle.'),
+        displayMode: displayModeSchema,
+    },
+    blockedByDialog: false,
+    // We do not validate file paths for remote browser instances
+    // because they are on the remote host and not accessed by the MCP server.
+    verifyFilesSchema: {
+        installUrlOrBundleUrl: {
+            local: true,
+            remote: false,
+        },
+    },
+    handler: async (request, response, context) => {
+        const { manifestId, installUrlOrBundleUrl, displayMode } = request.params;
+        await context.installPWA({
+            manifestId,
+            installUrlOrBundleUrl,
+            displayMode,
+        });
+        response.appendResponseLine(`Installed PWA with manifest ID: ${manifestId}`);
+        if (displayMode) {
+            response.appendResponseLine(`Display mode set to: ${displayMode}`);
+        }
+    },
+});
+export const uninstallPwa = defineTool({
+    name: 'uninstall_pwa',
+    description: 'Uninstalls a Progressive Web App identified by its manifest ID and ' +
+        'closes any open app windows.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId } = request.params;
+        await context.uninstallPWA({ manifestId });
+        response.appendResponseLine(`Uninstalled PWA with manifest ID: ${manifestId}`);
+        response.setIncludePages(true);
+    },
+});
+export const launchPwa = defineTool({
+    name: 'launch_pwa',
+    description: 'Launches an installed Progressive Web App using its saved display mode. ' +
+        'Optionally opens a specific URL within the same app instead of the default ' +
+        'start URL.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+        url: zod
+            .string()
+            .optional()
+            .describe('Optional URL within the app to open instead of the default start URL.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId, url } = request.params;
+        const page = await context.launchPWA({ manifestId, url });
+        response.appendResponseLine(`Launched PWA with manifest ID: ${manifestId} (${page.url()})`);
+        response.setIncludePages(true);
+    },
+});
+export const getOsAppState = defineTool({
+    name: 'get_os_app_state',
+    description: 'Returns the OS integration state (badge count and registered file ' +
+        'handlers) for an installed web app, identified by its manifest ID.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: true,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId } = request.params;
+        const state = await context.getPWAState({ manifestId });
+        response.appendResponseLine(`OS app state for manifest ID: ${manifestId}`);
+        response.appendResponseLine(`Badge count: ${state.badgeCount}`);
+        response.appendResponseLine(`File handlers: ${JSON.stringify(state.fileHandlers)}`);
+    },
+});
+//# sourceMappingURL=pwa.js.map

package/build/src/tools/screencast.js

@@ -7,7 +7,6 @@ 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() {
@@ -30,23 +29,32 @@ export const startScreencast = definePageTool(args => ({
             .describe(`Output file path (${supportedExtensions.join(',')} are supported). Uses mkdtemp to generate a unique path if not provided.`),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
     handler: async (request, response, context) => {
-        context.validatePath(request.params.filePath);
         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.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 requestedFilePath = request.params.filePath;
+        const filePath = requestedFilePath ?? (await generateTempFilePath());
+        // Match the extension case-insensitively so e.g. `.WEBM` is recognized as
+        // WebM. An explicitly requested but unsupported extension is rejected
+        // rather than being silently rewritten to `.mp4` (which would change both
+        // the format and the output path from what was requested). A missing
+        // extension falls back to `.mp4`. The matched extension is normalized to
+        // lower case.
+        const requestedExtension = path.extname(filePath);
+        const matchedExtension = supportedExtensions.find(supportedExtension => supportedExtension === requestedExtension.toLowerCase());
+        if (!matchedExtension && requestedExtension !== '') {
+            throw new Error(`Unsupported screencast file extension "${requestedExtension}". ` +
+                `Supported formats: ${supportedExtensions.join(', ')} (case-insensitive).`);
         }
-        const resolvedPath = ensureExtension(path.resolve(filePath), enforcedExtension);
+        const enforcedExtension = matchedExtension ?? '.mp4';
+        const format = (matchedExtension?.substring(1) ??
+            'mp4');
+        const resolvedPath = await context.ensureExtension(filePath, enforcedExtension);
         const page = request.page;
         let recorder;
         try {
@@ -57,6 +65,19 @@ export const startScreencast = definePageTool(args => ({
             });
         }
         catch (err) {
+            // If we generated a temporary directory for this recording, remove it so
+            // a failed start (e.g. ffmpeg missing) does not leak an empty directory.
+            if (requestedFilePath === undefined) {
+                try {
+                    await fs.rm(path.dirname(resolvedPath), {
+                        recursive: true,
+                        force: true,
+                    });
+                }
+                catch {
+                    // no-op
+                }
+            }
             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. ' +
@@ -78,9 +99,11 @@ export const stopScreencast = definePageTool({
     },
     schema: {},
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (_request, response, context) => {
         const data = context.getScreenRecorder();
         if (!data) {
+            response.appendResponseLine('Error: no active screencast recording to stop.');
             return;
         }
         try {