chrome-devtools-mcp 1.4.0 → 1.5.0

package/README.md

@@ -121,9 +121,9 @@ To use the Chrome DevTools MCP server follow the instructions from <a href="http
     "chrome-devtools": {
       "command": "npx",
       "args": [
+        "-y",
         "chrome-devtools-mcp@latest",
-        "--browser-url=http://127.0.0.1:9222",
-        "-y"
+        "--browser-url=http://127.0.0.1:9222"
       ]
     }
   }
@@ -514,12 +514,14 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`take_snapshot`](docs/tool-reference.md#take_snapshot)
   - [`screencast_start`](docs/tool-reference.md#screencast_start)
   - [`screencast_stop`](docs/tool-reference.md#screencast_stop)
-- **Memory** (9 tools)
+- **Memory** (11 tools)
   - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
   - [`close_heapsnapshot`](docs/tool-reference.md#close_heapsnapshot)
+  - [`compare_heapsnapshots`](docs/tool-reference.md#compare_heapsnapshots)
   - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
   - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
   - [`get_heapsnapshot_dominators`](docs/tool-reference.md#get_heapsnapshot_dominators)
+  - [`get_heapsnapshot_duplicate_strings`](docs/tool-reference.md#get_heapsnapshot_duplicate_strings)
   - [`get_heapsnapshot_edges`](docs/tool-reference.md#get_heapsnapshot_edges)
   - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
   - [`get_heapsnapshot_retaining_paths`](docs/tool-reference.md#get_heapsnapshot_retaining_paths)

package/build/src/HeapSnapshotManager.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { DevTools } from './third_party/index.js';
 import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
 export class HeapSnapshotManager {
+    #snapshotIdGenerator = createIdGenerator();
     #snapshots = new Map();
     async getSnapshot(filePath) {
         const absolutePath = path.resolve(filePath);
@@ -15,7 +16,8 @@ export class HeapSnapshotManager {
         if (cached) {
             return cached.snapshot;
         }
-        const { snapshot, worker } = await this.#loadSnapshot(absolutePath);
+        const uid = this.#snapshotIdGenerator();
+        const { snapshot, worker } = await this.#loadSnapshot(absolutePath, uid);
         this.#snapshots.set(absolutePath, {
             snapshot,
             worker,
@@ -100,6 +102,38 @@ export class HeapSnapshotManager {
         const provider = snapshot.createEdgesProvider(nodeIndex);
         return await provider.serializeItemsRange(0, Infinity);
     }
+    async getClassDiffs(baseFilePath, currentFilePath) {
+        const rawDiffs = await this.#getSortedRawClassDiffs(baseFilePath, currentFilePath);
+        return rawDiffs.map(rawDiff => ({
+            className: rawDiff.name,
+            addedCount: rawDiff.addedCount,
+            removedCount: rawDiff.removedCount,
+            countDelta: rawDiff.countDelta,
+            addedSize: rawDiff.addedSize,
+            removedSize: rawDiff.removedSize,
+            sizeDelta: rawDiff.sizeDelta,
+        }));
+    }
+    async getDetailedClassDiff(baseFilePath, currentFilePath, classIndex) {
+        const classDiffs = await this.#getSortedRawClassDiffs(baseFilePath, currentFilePath);
+        const rawDiff = classDiffs[classIndex];
+        if (!rawDiff) {
+            throw new Error(`Invalid classIndex: ${classIndex}. Total classes with changes: ${classDiffs.length}`);
+        }
+        return {
+            className: rawDiff.name,
+            addedCount: rawDiff.addedCount,
+            removedCount: rawDiff.removedCount,
+            countDelta: rawDiff.countDelta,
+            addedSize: rawDiff.addedSize,
+            removedSize: rawDiff.removedSize,
+            sizeDelta: rawDiff.sizeDelta,
+            addedIds: rawDiff.addedIds ?? [],
+            addedSelfSizes: rawDiff.addedSelfSizes ?? [],
+            deletedIds: rawDiff.deletedIds ?? [],
+            deletedSelfSizes: rawDiff.deletedSelfSizes ?? [],
+        };
+    }
     #getCachedSnapshot(filePath) {
         const absolutePath = path.resolve(filePath);
         const cached = this.#snapshots.get(absolutePath);
@@ -108,16 +142,35 @@ export class HeapSnapshotManager {
         }
         return cached;
     }
+    async #getSortedRawClassDiffs(baseFilePath, currentFilePath) {
+        const baseSnapshot = await this.getSnapshot(baseFilePath);
+        const currentSnapshot = await this.getSnapshot(currentFilePath);
+        const interfaceDefinitions = await currentSnapshot.interfaceDefinitions();
+        const aggregatesForDiff = await baseSnapshot.aggregatesForDiff(interfaceDefinitions);
+        const baseSnapshotId = baseSnapshot.uid;
+        if (baseSnapshotId === undefined) {
+            throw new Error('Base snapshot UID is undefined');
+        }
+        // DevTools calculateSnapshotDiff uses the first parameter (baseSnapshotId)
+        // as a cache key. We pass the unique UID of the base snapshot.
+        const rawDiffs = await currentSnapshot.calculateSnapshotDiff(baseSnapshotId, aggregatesForDiff);
+        // Return a filtered and sorted array here to ensure that
+        // compare_heapsnapshot_summary and compare_heapsnapshot_details agree
+        // on indices.
+        return Object.values(rawDiffs)
+            .filter(diff => diff.addedCount > 0 || diff.removedCount > 0)
+            .sort((a, b) => b.sizeDelta - a.sizeDelta);
+    }
     async resolveClassKeyFromId(filePath, id) {
         const cached = this.#getCachedSnapshot(filePath);
         return cached.idToClassKey.get(id);
     }
-    async #loadSnapshot(absolutePath) {
+    async #loadSnapshot(absolutePath, uid) {
         const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {
             /* noop */
         }, import.meta.resolve('./third_party/devtools-heap-snapshot-worker.js'));
         const { promise: snapshotPromise, resolve: resolveSnapshot } = Promise.withResolvers();
-        const loaderProxy = workerProxy.createLoader(1, snapshotProxy => {
+        const loaderProxy = workerProxy.createLoader(uid, snapshotProxy => {
             resolveSnapshot(snapshotProxy);
         });
         const fileStream = fsSync.createReadStream(absolutePath, {
@@ -131,6 +184,10 @@ export class HeapSnapshotManager {
         const snapshot = await snapshotPromise;
         return { snapshot, worker: workerProxy };
     }
+    async getDuplicateStrings(filePath) {
+        const snapshot = await this.getSnapshot(filePath);
+        return await snapshot.getDuplicateStrings();
+    }
     hasSnapshots() {
         return this.#snapshots.size > 0;
     }

package/build/src/McpContext.js

@@ -16,7 +16,7 @@ import { ServiceWorkerConsoleCollector } from './ServiceWorkerCollector.js';
 import { Locator, PredefinedNetworkConditions, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
-import { ensureExtension, getTempFilePath, resolveCanonicalPath, } from './utils/files.js';
+import { getTempFilePath, resolveCanonicalPath } from './utils/files.js';
 import { getNetworkMultiplierFromString } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -156,6 +156,13 @@ export class McpContext {
             throw new Error(`Access denied: path ${filePath} (canonical: ${canonicalPath}) is not within any of the configured workspace roots.`);
         }
     }
+    async ensureExtension(filePath, extension) {
+        const resolvedPath = path.resolve(filePath);
+        const currentExtension = path.extname(resolvedPath);
+        const outputPath = `${resolvedPath.slice(0, resolvedPath.length - currentExtension.length)}${extension}`;
+        await this.validatePath(outputPath);
+        return outputPath;
+    }
     resolveCdpRequestId(page, cdpRequestId) {
         if (!cdpRequestId) {
             this.logger?.('no network request');
@@ -223,12 +230,15 @@ export class McpContext {
         const currentSetting = page.emulationSettings;
         await this.emulate(currentSetting, page.pptrPage);
     }
+    get #hasNetworkBlockOrAllowlist() {
+        return !!(this.#options.allowList || this.#options.blocklist);
+    }
     async emulate(options, targetPage) {
         const page = targetPage ?? this.getSelectedPptrPage();
         const mcpPage = this.#getMcpPage(page);
         const newSettings = { ...mcpPage.emulationSettings };
         // Skip network emulation if blocklist/allowlist is configured, as it conflicts with blocking rules in Puppeteer.
-        if (this.#options.hasNetworkBlockOrAllowlist) {
+        if (this.#hasNetworkBlockOrAllowlist) {
             if (options.networkConditions !== undefined) {
                 throw new Error('Network throttling is not supported when network blocking (allowlist/blocklist) is configured.');
             }
@@ -568,9 +578,8 @@ export class McpContext {
         return { filepath };
     }
     async saveFile(data, clientProvidedFilePath, extension) {
-        await this.validatePath(clientProvidedFilePath);
+        const filePath = await this.ensureExtension(clientProvidedFilePath, extension);
         try {
-            const filePath = ensureExtension(path.resolve(clientProvidedFilePath), extension);
             await fs.mkdir(path.dirname(filePath), { recursive: true });
             await fs.writeFile(filePath, data);
             return { filename: filePath };
@@ -646,6 +655,9 @@ export class McpContext {
     async getHeapSnapshotAggregates(filePath) {
         return await this.#heapSnapshotManager.getAggregates(filePath);
     }
+    async getHeapSnapshotDuplicateStrings(filePath) {
+        return await this.#heapSnapshotManager.getDuplicateStrings(filePath);
+    }
     async getHeapSnapshotStats(filePath) {
         return await this.#heapSnapshotManager.getStats(filePath);
     }
@@ -670,12 +682,36 @@ export class McpContext {
     async getHeapSnapshotDominators(filePath, nodeId) {
         return await this.#heapSnapshotManager.getDominatorsOf(filePath, nodeId);
     }
+    #validateUrlNotBlocked(url) {
+        if (!this.#options.blocklist) {
+            return;
+        }
+        for (const block of this.#options.blocklist) {
+            const pattern = new URLPattern(block);
+            if (pattern.test(url)) {
+                throw new Error(`Blocked by blocklist: ${url}`);
+            }
+        }
+    }
+    #validateUrlAllowed(url) {
+        if (!this.#options.allowList) {
+            return;
+        }
+        for (const allow of this.#options.allowList) {
+            const pattern = new URLPattern(allow);
+            if (pattern.test(url)) {
+                return;
+            }
+        }
+        throw new Error(`Not allowed by allowlist: ${url}`);
+    }
     async loadResource(path) {
         const url = new URL(path);
+        this.#validateUrlNotBlocked(url);
         switch (url.protocol) {
             case 'https:':
             case 'http:': {
-                // TODO: Verify allow/block list
+                this.#validateUrlAllowed(url);
                 const response = await fetch(url);
                 if (!response.ok) {
                     throw new Error(`Failed to load resource: ${url}`);
@@ -693,5 +729,11 @@ export class McpContext {
     async getHeapSnapshotEdges(filePath, nodeId) {
         return await this.#heapSnapshotManager.getEdges(filePath, nodeId);
     }
+    async getHeapSnapshotClassDiffs(baseFilePath, currentFilePath) {
+        return await this.#heapSnapshotManager.getClassDiffs(baseFilePath, currentFilePath);
+    }
+    async getHeapSnapshotDetailedClassDiff(baseFilePath, currentFilePath, classIndex) {
+        return await this.#heapSnapshotManager.getDetailedClassDiff(baseFilePath, currentFilePath, classIndex);
+    }
 }
 //# sourceMappingURL=McpContext.js.map

package/build/src/McpResponse.js

@@ -4,14 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
-import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
-import { isEdgeLike, isNodeLike } from './formatters/HeapSnapshotFormatter.js';
+import { HeapSnapshotFormatter, isEdgeLike, isNodeLike, } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
 import { UncaughtError } from './PageCollector.js';
 import { TextSnapshot } from './TextSnapshot.js';
-import { DevTools, toonEncode } from './third_party/index.js';
+import { DevTools, getToonEncode } from './third_party/index.js';
 import { handleDialog } from './tools/pages.js';
 import { getInsightOutput, getTraceSummary } from './trace-processing/parse.js';
 import { paginate } from './utils/pagination.js';
@@ -334,6 +333,14 @@ export class McpResponse {
             pagination: options,
         };
     }
+    setHeapSnapshotDuplicateStrings(duplicateStrings, options) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            duplicateStrings,
+            pagination: options,
+        };
+    }
     setHeapSnapshotRetainingPaths(retainingPaths) {
         this.#heapSnapshotOptions = {
             ...this.#heapSnapshotOptions,
@@ -348,6 +355,20 @@ export class McpResponse {
             dominators,
         };
     }
+    setHeapSnapshotClassDiffs(classDiffs) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            classDiffs,
+        };
+    }
+    setHeapSnapshotDetailedClassDiff(detailedClassDiff) {
+        this.#heapSnapshotOptions = {
+            ...this.#heapSnapshotOptions,
+            include: true,
+            detailedClassDiff,
+        };
+    }
     attachImage(value) {
         this.#images.push(value);
     }
@@ -548,6 +569,18 @@ export class McpResponse {
     }
     async format(toolName, context, data, useToon) {
         const structuredContent = {};
+        let toonEncode;
+        if (useToon) {
+            try {
+                toonEncode = await getToonEncode();
+            }
+            catch {
+                throw new Error('The `@toon-format/toon` package is required to use the experimental TOON format. ' +
+                    'Make sure the peer dependency is installed:\n' +
+                    '- For npx: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalToonFormat\n' +
+                    '- For npm: npm install @toon-format/toon (add -g if installed globally)');
+            }
+        }
         const response = [];
         if (this.#textResponseLines.length) {
             structuredContent.message = this.#textResponseLines.join('\n');
@@ -726,7 +759,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
             else {
                 structuredContent.snapshot = data.snapshot.toJSON();
                 response.push('## Latest page snapshot');
-                response.push(useToon
+                response.push(useToon && toonEncode
                     ? toonEncode(structuredContent.snapshot)
                     : data.snapshot.toString());
             }
@@ -754,7 +787,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 const paginatedRecord = Object.fromEntries(paginationData.items);
                 const formatter = new HeapSnapshotFormatter(paginatedRecord);
                 structuredContent.heapSnapshotData = formatter.toJSON();
-                response.push(useToon
+                response.push(useToon && toonEncode
                     ? toonEncode(structuredContent.heapSnapshotData)
                     : formatter.toString());
             }
@@ -808,6 +841,32 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 }
                 structuredContent.heapSnapshotDominators = dominators;
             }
+            const classDiffs = this.#heapSnapshotOptions.classDiffs;
+            if (classDiffs) {
+                response.push('### Heap Snapshot Diff');
+                response.push(useToon && toonEncode
+                    ? toonEncode(classDiffs)
+                    : HeapSnapshotFormatter.formatDiffSummary(classDiffs));
+                structuredContent.heapSnapshotClassDiffs = classDiffs;
+            }
+            const detailedClassDiff = this.#heapSnapshotOptions.detailedClassDiff;
+            if (detailedClassDiff) {
+                response.push('### Heap Snapshot Detailed Diff');
+                response.push(useToon && toonEncode
+                    ? toonEncode(detailedClassDiff)
+                    : HeapSnapshotFormatter.formatDiffDetails(detailedClassDiff));
+                structuredContent.heapSnapshotDetailedClassDiff = detailedClassDiff;
+            }
+            const duplicateStrings = this.#heapSnapshotOptions.duplicateStrings;
+            if (duplicateStrings) {
+                response.push('### Duplicate Strings');
+                const paginationData = this.#dataWithPagination(duplicateStrings, this.#heapSnapshotOptions.pagination);
+                structuredContent.pagination = paginationData.pagination;
+                response.push(...paginationData.info);
+                const formatted = HeapSnapshotFormatter.formatDuplicateStrings(paginationData.items);
+                response.push(formatted);
+                structuredContent.heapSnapshotDuplicateStrings = paginationData.items;
+            }
         }
         if (data.detailedNetworkRequest) {
             response.push(data.detailedNetworkRequest.toStringDetailed());
@@ -879,7 +938,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(...paginationData.info);
                 if (data.networkRequests) {
                     structuredContent.networkRequests = paginationData.items.map(i => i.toJSON());
-                    response.push(...(useToon
+                    response.push(...(useToon && toonEncode
                         ? [toonEncode(structuredContent.networkRequests)]
                         : paginationData.items.map(i => i.toString())));
                 }
@@ -897,7 +956,7 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 structuredContent.pagination = paginationData.pagination;
                 structuredContent.consoleMessages = paginationData.items.map(item => item.toJSON());
                 response.push(...paginationData.info);
-                if (useToon) {
+                if (useToon && toonEncode) {
                     response.push(toonEncode(structuredContent.consoleMessages));
                 }
                 else {

package/build/src/bin/chrome-devtools-cli-options.js

@@ -82,6 +82,30 @@ export const commands = {
             },
         },
     },
+    compare_heapsnapshots: {
+        description: 'Loads two memory heapsnapshots and returns the comparison. If classIndex is provided, returns detailed diff for that class, otherwise returns summary diff. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            baseFilePath: {
+                name: 'baseFilePath',
+                type: 'string',
+                description: 'A path to the base .heapsnapshot file (earlier snapshot).',
+                required: true,
+            },
+            currentFilePath: {
+                name: 'currentFilePath',
+                type: 'string',
+                description: 'A path to the current .heapsnapshot file (later snapshot).',
+                required: true,
+            },
+            classIndex: {
+                name: 'classIndex',
+                type: 'number',
+                description: 'Optional 0-based index of the class in the summary list to filter results, showing individual objects.',
+                required: false,
+            },
+        },
+    },
     drag: {
         description: 'Drag an element onto another element',
         category: 'Input automation',
@@ -157,13 +181,13 @@ export const commands = {
         },
     },
     evaluate_script: {
-        description: 'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON,\nso returned values have to be JSON-serializable.',
+        description: 'Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON, so returned values have to be JSON-serializable.',
         category: 'Debugging',
         args: {
             function: {
                 name: 'function',
                 type: 'string',
-                description: 'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => {\n  return document.title\n}` or `async () => {\n  return await fetch("example.com")\n}`.\nExample with arguments: `(el) => {\n  return el.innerText;\n}`\n',
+                description: 'A JavaScript function declaration to be executed by the tool in the currently selected page.\nExample without arguments: `() => document.title` or `async () => await fetch("example.com")`.\nExample with arguments: `(el) => el.innerText`\n',
                 required: true,
             },
             args: {
@@ -330,6 +354,30 @@ export const commands = {
             },
         },
     },
+    get_heapsnapshot_duplicate_strings: {
+        description: 'Loads a memory heapsnapshot and returns duplicate strings grouped by their value. (requires flag: --memoryDebugging=true)',
+        category: 'Memory',
+        args: {
+            filePath: {
+                name: 'filePath',
+                type: 'string',
+                description: 'A path to a .heapsnapshot file to read.',
+                required: true,
+            },
+            pageIdx: {
+                name: 'pageIdx',
+                type: 'number',
+                description: 'The page index for pagination.',
+                required: false,
+            },
+            pageSize: {
+                name: 'pageSize',
+                type: 'number',
+                description: 'The page size for pagination.',
+                required: false,
+            },
+        },
+    },
     get_heapsnapshot_edges: {
         description: 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID. (requires flag: --memoryDebugging=true)',
         category: 'Memory',
@@ -540,7 +588,7 @@ export const commands = {
         },
     },
     list_3p_developer_tools: {
-        description: "Lists all third-party developer tools the page exposes for providing runtime information.\n  Third-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.\n  Alternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the\n  following command to the script:\n  'window.__dtmcp.executeTool(toolName, params)'\n  This might be helpful when the third-party developer tools return non-serializable values or when composing\n  third-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)",
+        description: "Lists all third-party developer tools the page exposes for providing runtime information.\nThird-party developer tools can be called via the 'execute_3p_developer_tool()' MCP tool.\nAlternatively, third-party developer tools can be executed by calling 'evaluate_script' and adding the\nfollowing command to the script:\n`window.__dtmcp.executeTool(toolName, params)`\nThis might be helpful when the third-party developer tools return non-serializable values or when composing\nthird-party developer tools with additional functionality. (requires flag: --categoryExperimentalThirdParty=true)",
         category: 'Third-party',
         args: {},
     },

package/build/src/bin/chrome-devtools-mcp-cli-options.js

@@ -157,7 +157,7 @@ export const cliOptions = {
     },
     experimentalToonFormat: {
         type: 'boolean',
-        describe: 'Whether to format structured data in text response using Token-Oriented Object Notation. Defaults to false which represents the embedded content as formatted JSON instead.',
+        describe: 'Whether to format structured data in text response using Token-Oriented Object Notation (requires @toon-format/toon). If running via npx, use: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalToonFormat',
         hidden: true,
     },
     experimentalIncludeAllPages: {

package/build/src/bin/chrome-devtools.js

@@ -41,6 +41,7 @@ startCliOptions.isolated.description =
     'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to true unless userDataDir is provided.';
 startCliOptions.categoryExtensions.default = true;
 const y = yargs(hideBin(process.argv))
+    .locale('en') // Force English to ensure error string matching works in .fail, all custom messages we output are in English anyways
     .scriptName('chrome-devtools')
     .showHelpOnFail(true)
     .usage('chrome-devtools <command> [...args] --flags')
@@ -55,7 +56,30 @@ const y = yargs(hideBin(process.argv))
     .version(VERSION)
     .strict()
     .help(true)
-    .wrap(120);
+    .wrap(120)
+    .fail((msg, err) => {
+    if (msg) {
+        console.error('Error:', msg);
+        if (msg.includes('Not enough non-option arguments') ||
+            msg.includes('Unknown argument') ||
+            msg.includes('Unknown arguments')) {
+            console.error('\n=========================================');
+            console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
+            console.error('In the `chrome-devtools` CLI:');
+            console.error('1. Required parameters MUST be passed as positional arguments (without flags).');
+            console.error('   - INCORRECT: chrome-devtools evaluate_script --expression "() => document.title"');
+            console.error('   - CORRECT:   chrome-devtools evaluate_script "() => document.title"');
+            console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --pageId 1).');
+            console.error('3. Make sure to escape quotes properly for your shell environment.');
+            console.error('Run `chrome-devtools <command> --help` to see exact positional and optional parameters.');
+            console.error('=========================================');
+        }
+    }
+    else if (err) {
+        console.error(err);
+    }
+    process.exit(1);
+});
 y.command('start', 'Start or restart chrome-devtools-mcp', y => y
     .options(startCliOptions)
     .example('$0 start --browserUrl http://localhost:9222', 'Start the server connecting to an existing browser')

package/build/src/daemon/daemon.js

@@ -23,7 +23,7 @@ const pidFilePath = getPidFilePath(sessionId);
 const pidDir = path.dirname(pidFilePath);
 const currentUserUid = os.userInfo().uid;
 try {
-    fs.mkdirSync(pidDir, { recursive: true });
+    fs.mkdirSync(pidDir, { recursive: true, mode: 0o700 });
     if (os.platform() !== 'win32') {
         // POSIX specific checks
         try {

package/build/src/formatters/HeapSnapshotFormatter.js

@@ -67,6 +67,16 @@ export class HeapSnapshotFormatter {
         }
         return lines.join('\n');
     }
+    static formatDuplicateStrings(groups) {
+        const lines = [];
+        lines.push('value,count,totalSelfSize,totalRetainedSize,truncated,nodeIds');
+        for (const group of groups) {
+            const nodeIds = group.nodes.map(n => `@${n.id}`).join(' ');
+            const truncated = group.truncated ?? false;
+            lines.push(`${JSON.stringify(group.value)},${group.count},${DevTools.I18n.ByteUtilities.formatBytesToKb(group.totalSelfSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(group.totalRetainedSize)},${truncated},${nodeIds}`);
+        }
+        return lines.join('\n');
+    }
     #getSortedAggregates() {
         return Object.values(this.#aggregates).sort((a, b) => b.maxRet - a.maxRet);
     }
@@ -93,5 +103,38 @@ export class HeapSnapshotFormatter {
     static sort(aggregates) {
         return Object.entries(aggregates).sort((a, b) => b[1].maxRet - a[1].maxRet);
     }
+    static formatDiffSummary(diffs) {
+        const lines = [];
+        lines.push('index,className,addedCount,removedCount,countDelta,addedSize,removedSize,sizeDelta');
+        let index = 0;
+        for (const diff of diffs) {
+            lines.push(`${index},${diff.className},${diff.addedCount},${diff.removedCount},${diff.countDelta},${DevTools.I18n.ByteUtilities.formatBytesToKb(diff.addedSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(diff.removedSize)},${DevTools.I18n.ByteUtilities.formatBytesToKb(diff.sizeDelta)}`);
+            index++;
+        }
+        return lines.join('\n');
+    }
+    static formatDiffDetails(diff) {
+        const lines = [];
+        lines.push(`${diff.className}: # new: ${diff.addedCount}, # deleted: ${diff.removedCount}, # delta: ${formatSignedCount(diff.countDelta)}, alloc size: ${formatSignedSize(diff.addedSize)}, freed size: ${formatSignedSize(diff.removedSize)}, size delta: ${formatSignedSize(diff.sizeDelta)}`);
+        const addedIds = diff.addedIds;
+        const addedSelfSizes = diff.addedSelfSizes;
+        const deletedIds = diff.deletedIds;
+        const deletedSelfSizes = diff.deletedSelfSizes;
+        lines.push(`Objects:`);
+        for (let i = 0; i < addedIds.length; i++) {
+            lines.push(`  + @${addedIds[i]} (self_size: ${DevTools.I18n.ByteUtilities.formatBytesToKb(addedSelfSizes[i])})`);
+        }
+        for (let i = 0; i < deletedIds.length; i++) {
+            lines.push(`  - @${deletedIds[i]} (self_size: ${DevTools.I18n.ByteUtilities.formatBytesToKb(deletedSelfSizes[i])})`);
+        }
+        return lines.join('\n');
+    }
+}
+function formatSignedCount(n) {
+    return n > 0 ? `+${n}` : `${n}`;
+}
+function formatSignedSize(bytes) {
+    const formatted = DevTools.I18n.ByteUtilities.formatBytesToKb(bytes);
+    return bytes > 0 ? `+${formatted}` : formatted;
 }
 //# sourceMappingURL=HeapSnapshotFormatter.js.map

package/build/src/index.js

@@ -108,8 +108,8 @@ export async function createMcpServer(serverArgs, options) {
                 experimentalDevToolsDebugging: devtools,
                 experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
                 performanceCrux: serverArgs.performanceCrux,
-                hasNetworkBlockOrAllowlist: Boolean((blocklist && blocklist.length > 0) ||
-                    (allowlist && allowlist.length > 0)),
+                allowList: allowlist,
+                blocklist: blocklist,
             });
             await updateRoots();
         }

package/build/src/issue-descriptions.js

@@ -16,11 +16,13 @@ export async function loadIssueDescriptions() {
     }
     const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
     const descriptions = {};
-    for (const file of files) {
-        if (!file.endsWith('.md')) {
-            continue;
-        }
+    const results = await Promise.all(files
+        .filter(file => file.endsWith('.md'))
+        .map(async (file) => {
         const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        return { file, content };
+    }));
+    for (const { file, content } of results) {
         descriptions[file] = content;
     }
     issueDescriptions = descriptions;

package/build/src/third_party/THIRD_PARTY_NOTICES

@@ -867,7 +867,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 Name: puppeteer-core
 URL: https://github.com/puppeteer/puppeteer/tree/main/packages/puppeteer-core
-Version: 25.2.0
+Version: 25.2.1
 License: Apache-2.0
 
 -------------------- DEPENDENCY DIVIDER --------------------
@@ -906,36 +906,6 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 
--------------------- DEPENDENCY DIVIDER --------------------
-
-Name: @toon-format/toon
-URL: https://toonformat.dev
-Version: 2.3.0
-License: MIT
-
-MIT License
-
-Copyright (c) 2025-PRESENT Johann Schopplich
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-
 -------------------- DEPENDENCY DIVIDER --------------------
 
 Name: chrome-devtools-frontend