chrome-devtools-mcp 1.3.0 → 1.5.0

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: {
@@ -193,12 +193,12 @@ export const cliOptions = {
     },
     blockedUrlPattern: {
         type: 'array',
-        describe: 'Restricts network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.',
+        describe: "Restricts browser's network access by blocking specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Silently detaches from targets with blocked URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.",
         conflicts: ['allowedUrlPattern'],
     },
     allowedUrlPattern: {
         type: 'array',
-        describe: 'Restricts network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.',
+        describe: "Restricts browser's network access by allowing only specified URL patterns (uses https://urlpattern.spec.whatwg.org/). Requires Chrome 149+. Silently detaches from targets with unallowed URLs upon connection, and blocks runtime requests (including navigations and subresources). Accepts an array of patterns.",
         conflicts: ['blockedUrlPattern'],
     },
     ignoreDefaultChromeArg: {

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/formatters/NetworkFormatter.js

@@ -226,7 +226,9 @@ function converNetworkRequestDetailedToStringDetailed(data) {
     if (redirectChain?.length) {
         response.push(`### Redirect chain`);
         let indent = 0;
-        for (const request of redirectChain.reverse()) {
+        // `redirectChain` is already ordered by toJSONDetailed(); don't reverse it
+        // again here or the text output contradicts structuredContent (the JSON).
+        for (const request of redirectChain) {
             response.push(`${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)}`);
             indent++;
         }

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

@@ -324,7 +324,7 @@ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH RE
 
 Name: semver
 URL: git+https://github.com/npm/node-semver.git
-Version: 7.8.3
+Version: 7.8.5
 License: ISC
 
 The ISC License
@@ -867,14 +867,14 @@ 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.1.0
+Version: 25.2.1
 License: Apache-2.0
 
 -------------------- DEPENDENCY DIVIDER --------------------
 
 Name: @puppeteer/browsers
 URL: https://github.com/puppeteer/puppeteer/tree/main/packages/browsers
-Version: 3.0.4
+Version: 3.0.5
 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

package/build/src/third_party/bundled-packages.json

@@ -1,12 +1,11 @@
 {
   "@modelcontextprotocol/sdk": "1.29.0",
-  "@toon-format/toon": "^2.2.0",
-  "chrome-devtools-frontend": "1.0.1646286",
+  "chrome-devtools-frontend": "1.0.1652307",
   "core-js": "3.49.0",
   "debug": "4.4.3",
-  "lighthouse": "13.3.0",
+  "lighthouse": "13.4.0",
   "semver": "^7.7.4",
   "urlpattern-polyfill": "^10.1.0",
   "yargs": "18.0.0",
-  "puppeteer-core": "25.1.0"
+  "puppeteer-core": "25.2.1"
 }

package/build/src/third_party/devtools-heap-snapshot-worker.js

@@ -5930,6 +5930,9 @@ class HeapSnapshotProxy extends HeapSnapshotProxyObject {
     aggregatesWithFilter(filter) {
         return this.callMethodPromise('aggregatesWithFilter', filter);
     }
+    getDuplicateStrings() {
+        return this.callMethodPromise('getDuplicateStrings');
+    }
     aggregatesForDiff(interfaceDefinitions) {
         return this.callMethodPromise('aggregatesForDiff', interfaceDefinitions);
     }
@@ -6712,6 +6715,45 @@ class HeapSnapshotNode {
         value |= detachedness;
         this.#setDetachednessAndClassIndex(value);
     }
+    findInternalEdgeTarget(name) {
+        for (let iter = this.edges(); iter.hasNext(); iter.next()) {
+            const edge = iter.edge;
+            if (!edge.isInternal()) {
+                continue;
+            }
+            if (edge.name() === name) {
+                return edge.node();
+            }
+        }
+        return undefined;
+    }
+    nodeValueAsBool() {
+        if (this.rawType() !== this.snapshot.nodeNumberType) {
+            return undefined;
+        }
+        if (this.rawName() !== 'bool') {
+            return undefined;
+        }
+        const valNode = this.findInternalEdgeTarget('value');
+        if (!valNode) {
+            return undefined;
+        }
+        const rawName = valNode.rawName();
+        if (rawName === 'true') {
+            return true;
+        }
+        if (rawName === 'false') {
+            return false;
+        }
+        return undefined;
+    }
+    nodeIsTruncatedString() {
+        const truncNode = this.findInternalEdgeTarget('truncated');
+        if (!truncNode) {
+            return false;
+        }
+        return truncNode.nodeValueAsBool() === true;
+    }
 }
 class HeapSnapshotNodeIterator {
     node;
@@ -6927,6 +6969,7 @@ class HeapSnapshot {
     nodeSyntheticType;
     nodeClosureType;
     nodeRegExpType;
+    nodeNumberType;
     edgeFieldsCount;
     edgeTypeOffset;
     edgeNameOffset;
@@ -7001,6 +7044,7 @@ class HeapSnapshot {
         this.nodeSyntheticType = this.nodeTypes.indexOf('synthetic');
         this.nodeClosureType = this.nodeTypes.indexOf('closure');
         this.nodeRegExpType = this.nodeTypes.indexOf('regexp');
+        this.nodeNumberType = this.nodeTypes.indexOf('number');
         this.edgeFieldsCount = meta.edge_fields.length;
         this.edgeTypeOffset = meta.edge_fields.indexOf('type');
         this.edgeNameOffset = meta.edge_fields.indexOf('name_or_index');
@@ -7280,6 +7324,43 @@ class HeapSnapshot {
         const key = filter ? filter.key : 'allObjects';
         return this.getAggregatesByClassKey(false, key, filter);
     }
+    getDuplicateStrings() {
+        const filter = this.createNamedFilter('duplicatedStrings');
+        const groupsMap = new Map();
+        const node = this.createNode(0);
+        for (let i = 0; i < this.nodeCount; ++i) {
+            node.nodeIndex = i * this.nodeFieldCount;
+            if (filter(node)) {
+                const name = node.name();
+                const truncated = node.nodeIsTruncatedString();
+                let group = groupsMap.get(name);
+                if (!group) {
+                    group = {
+                        value: name,
+                        count: 0,
+                        totalSelfSize: 0,
+                        totalRetainedSize: 0,
+                        nodes: [],
+                        truncated,
+                    };
+                    groupsMap.set(name, group);
+                }
+                else if (truncated) {
+                    group.truncated = true;
+                }
+                group.count++;
+                group.totalSelfSize += node.selfSize();
+                group.totalRetainedSize += node.retainedSize();
+                group.nodes.push({
+                    id: node.id(),
+                    selfSize: node.selfSize(),
+                    retainedSize: node.retainedSize(),
+                    distance: node.distance(),
+                });
+            }
+        }
+        return Array.from(groupsMap.values()).sort((a, b) => b.totalRetainedSize - a.totalRetainedSize);
+    }
     createNodeIdFilter(minNodeId, maxNodeId) {
         function nodeIdFilter(node) {
             const id = node.id();
@@ -7334,6 +7415,12 @@ class HeapSnapshot {
             }
         };
         switch (filterName) {
+            case 'objectsRetainedByContexts':
+                traverse((_node, edge) => {
+                    return !this.isContextObject(edge.node());
+                });
+                markUnreachableNodes();
+                return (node) => !getBit(node);
             case 'objectsRetainedByDetachedDomNodes':
                 traverse((_node, edge) => {
                     return edge.node().detachedness() !== 2 ;
@@ -7477,6 +7564,9 @@ class HeapSnapshot {
     isUserRoot(_node) {
         return true;
     }
+    isContextObject(_node) {
+        return false;
+    }
     calculateShallowSizes() {
     }
     calculateDistances(isForRetainersView, filter) {
@@ -9011,6 +9101,10 @@ class JSHeapSnapshot extends HeapSnapshot {
     isUserRoot(node) {
         return node.isUserRoot() || node.isDocumentDOMTreesRoot();
     }
+    isContextObject(node) {
+        const name = node.rawName();
+        return name === 'system / Context' || name.startsWith('system / Context / ');
+    }
     userObjectsMapAndFlag() {
         return { map: this.flags, flag: this.nodeFlags.pageObject };
     }