chrome-devtools-mcp 1.2.0 → 1.3.0

package/build/src/tools/memory.js

@@ -148,4 +148,80 @@ export const closeHeapSnapshot = defineTool({
         response.appendResponseLine(`Closed heap snapshot: ${request.params.filePath}`);
     },
 });
+export const getHeapSnapshotRetainingPaths = defineTool({
+    name: 'get_heapsnapshot_retaining_paths',
+    description: 'Loads a memory heapsnapshot and returns retaining paths for a specific node ID. This helps to understand why a node is not being garbage collected.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    verifyFilesSchema: ['filePath'],
+    blockedByDialog: false,
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get retaining paths for.'),
+        maxDepth: zod
+            .number()
+            .optional()
+            .describe('The maximum depth to search for retaining paths.'),
+        maxNodes: zod
+            .number()
+            .optional()
+            .describe('The maximum number of nodes to return.'),
+        maxSiblings: zod
+            .number()
+            .optional()
+            .describe('The maximum number of siblings to return.'),
+    },
+    handler: async (request, response, context) => {
+        const retainingPaths = await context.getHeapSnapshotRetainingPaths(request.params.filePath, request.params.nodeId, request.params.maxDepth, request.params.maxNodes, request.params.maxSiblings);
+        response.setHeapSnapshotRetainingPaths(retainingPaths);
+    },
+});
+export const getHeapSnapshotEdges = defineTool({
+    name: 'get_heapsnapshot_edges',
+    description: 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: ['filePath'],
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get outgoing edges for.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const edges = await context.getHeapSnapshotEdges(request.params.filePath, request.params.nodeId);
+        response.setHeapSnapshotNodes(edges, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+});
+export const getHeapSnapshotDominators = defineTool({
+    name: 'get_heapsnapshot_dominators',
+    description: 'Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: ['filePath'],
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod
+            .number()
+            .describe('The node ID to get the dominator chain for.'),
+    },
+    handler: async (request, response, context) => {
+        const dominators = await context.getHeapSnapshotDominators(request.params.filePath, request.params.nodeId);
+        response.setHeapSnapshotDominators(dominators);
+    },
+});
 //# sourceMappingURL=memory.js.map

package/build/src/tools/screencast.js

@@ -36,16 +36,23 @@ export const startScreencast = definePageTool(args => ({
             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 enforcedExtension = matchedExtension ?? '.mp4';
+        const format = (matchedExtension?.substring(1) ??
+            'mp4');
         const resolvedPath = ensureExtension(path.resolve(filePath), enforcedExtension);
         const page = request.page;
         let recorder;
@@ -57,6 +64,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. ' +
@@ -82,6 +102,7 @@ export const stopScreencast = definePageTool({
     handler: async (_request, response, context) => {
         const data = context.getScreenRecorder();
         if (!data) {
+            response.appendResponseLine('Error: no active screencast recording to stop.');
             return;
         }
         try {

package/build/src/tools/screenshot.js

@@ -6,82 +6,164 @@
 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 page 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.'),
-    },
-    blockedByDialog: true,
-    verifyFilesSchema: ['filePath'],
-    handler: async (request, response, context) => {
-        if (request.params.uid && request.params.fullPage) {
-            throw new Error('Providing both "uid" and "fullPage" is not allowed.');
+async function getSourceBox(page, element, fullPage) {
+    if (element) {
+        const box = await element.boundingBox();
+        return box ?? undefined;
+    }
+    if (fullPage) {
+        const dims = await page.evaluate(() => ({
+            width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+            height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+        }));
+        if (dims.width <= 0 || dims.height <= 0) {
+            return undefined;
         }
-        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 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}`);
-            response.appendResponseLine(`Saved screenshot to ${filepath}.`);
-        }
-        else {
-            response.attachImage({
-                mimeType: `image/${request.params.format}`,
-                data: Buffer.from(screenshot).toString('base64'),
-            });
-        }
-    },
+        return { x: 0, y: 0, width: dims.width, height: dims.height };
+    }
+    const viewport = page.viewport();
+    if (!viewport) {
+        return undefined;
+    }
+    return { x: 0, y: 0, width: viewport.width, height: viewport.height };
+}
+function computeDownscaleClip(box, maxWidth, maxHeight) {
+    const widthScale = maxWidth !== undefined ? Math.min(1, maxWidth / box.width) : 1;
+    const heightScale = maxHeight !== undefined ? Math.min(1, maxHeight / box.height) : 1;
+    const scale = Math.min(widthScale, heightScale);
+    if (scale >= 1) {
+        return undefined;
+    }
+    // Skip degenerate sub-pixel results.
+    if (Math.round(box.width * scale) < 1 || Math.round(box.height * scale) < 1) {
+        return undefined;
+    }
+    return {
+        x: box.x,
+        y: box.y,
+        width: box.width,
+        height: box.height,
+        scale,
+    };
+}
+export const screenshot = definePageTool(args => {
+    const { screenshotFormat, screenshotQuality, screenshotMaxWidth, screenshotMaxHeight, } = args ?? {};
+    const defaultFormat = screenshotFormat ?? 'png';
+    return {
+        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(defaultFormat)
+                .describe(`Type of format to save the screenshot as. Default is "${defaultFormat}"`),
+            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 page 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.'),
+        },
+        blockedByDialog: true,
+        verifyFilesSchema: ['filePath'],
+        handler: async (request, response, context) => {
+            if (request.params.uid && request.params.fullPage) {
+                throw new Error('Providing both "uid" and "fullPage" is not allowed.');
+            }
+            const page = request.page.pptrPage;
+            const element = request.params.uid
+                ? await request.page.getElementByUid(request.params.uid)
+                : undefined;
+            const format = request.params.format;
+            const quality = format === 'png'
+                ? undefined
+                : (request.params.quality ?? screenshotQuality);
+            const fullPage = request.params.fullPage ?? false;
+            // Compute a downscale clip when --screenshot-max-width or
+            // --screenshot-max-height is set and the source exceeds either bound.
+            // The smaller scale factor wins so both bounds are respected while
+            // preserving aspect ratio.
+            let clip;
+            if (screenshotMaxWidth !== undefined ||
+                screenshotMaxHeight !== undefined) {
+                const box = await getSourceBox(page, element, fullPage);
+                if (box) {
+                    clip = computeDownscaleClip(box, screenshotMaxWidth, screenshotMaxHeight);
+                }
+            }
+            let screenshot;
+            if (clip) {
+                // page.screenshot with clip lets the CDP scale param downscale the
+                // capture for viewport, full-page and element shots alike. We rely on
+                // Puppeteer's default of captureBeyondViewport=true when a clip is
+                // present so element/full-page captures below the fold still work.
+                screenshot = await page.screenshot({
+                    type: format,
+                    quality,
+                    optimizeForSpeed: true,
+                    clip,
+                });
+            }
+            else if (element) {
+                screenshot = await element.screenshot({
+                    type: format,
+                    quality,
+                    optimizeForSpeed: true,
+                });
+            }
+            else {
+                screenshot = await page.screenshot({
+                    type: format,
+                    fullPage,
+                    quality,
+                    optimizeForSpeed: true,
+                });
+            }
+            if (request.params.uid) {
+                response.appendResponseLine(`Took a screenshot of node with uid "${request.params.uid}".`);
+            }
+            else if (fullPage) {
+                response.appendResponseLine('Took a screenshot of the full current page.');
+            }
+            else {
+                response.appendResponseLine("Took a screenshot of the current page's viewport.");
+            }
+            // Narrow `format` at the point of use: in the factory form of
+            // definePageTool TS widens the Schema generic, which loses the literal
+            // union from zod.enum on request.params.format.
+            const extension = format === 'jpeg' ? '.jpeg' : format === 'webp' ? '.webp' : '.png';
+            if (request.params.filePath) {
+                const result = await context.saveFile(screenshot, request.params.filePath, extension);
+                response.appendResponseLine(`Saved screenshot to ${result.filename}.`);
+            }
+            else if (screenshot.length >= 2_000_000) {
+                const { filepath } = await context.saveTemporaryFile(screenshot, `screenshot${extension}`);
+                response.appendResponseLine(`Saved screenshot to ${filepath}.`);
+            }
+            else {
+                response.attachImage({
+                    mimeType: `image/${format}`,
+                    data: Buffer.from(screenshot).toString('base64'),
+                });
+            }
+        },
+    };
 });
 //# sourceMappingURL=screenshot.js.map

package/build/src/version.js

@@ -5,6 +5,6 @@
  */
 // If moved update release-please config
 // x-release-please-start-version
-export const VERSION = '1.2.0';
+export const VERSION = '1.3.0';
 // x-release-please-end
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": {
@@ -63,7 +63,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1641723",
+    "chrome-devtools-frontend": "1.0.1646286",
     "core-js": "3.49.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
@@ -73,7 +73,7 @@
     "lighthouse": "13.3.0",
     "prettier": "^3.6.2",
     "puppeteer": "25.1.0",
-    "rollup": "4.61.0",
+    "rollup": "4.61.1",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
     "semver": "^7.7.4",