chrome-devtools-mcp 0.26.0 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
-# Chrome DevTools for Agents
+# Chrome DevTools for agents
 
 [![npm chrome-devtools-mcp package](https://img.shields.io/npm/v/chrome-devtools-mcp.svg)](https://npmjs.org/package/chrome-devtools-mcp)
 
-Chrome DevTools for Agents (`chrome-devtools-mcp`) lets your coding agent (such as Gemini, Claude, Cursor or Copilot)
+Chrome DevTools for agents (`chrome-devtools-mcp`) lets your coding agent (such as Antigravity, Claude, Cursor or Copilot)
 control and inspect a live Chrome browser. It acts as a Model-Context-Protocol
 (MCP) server, giving your AI coding assistant access to the full power of
 Chrome DevTools for reliable automation, in-depth debugging, and performance analysis.
@@ -61,7 +61,7 @@ You can disable these update checks by setting the `CHROME_DEVTOOLS_MCP_NO_UPDAT
 
 ## Requirements
 
-- [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version.
+- [Node.js](https://nodejs.org/) [LTS](https://github.com/nodejs/Release#release-schedule) version.
 - [Chrome](https://www.google.com/chrome/) current stable version or newer.
 - [npm](https://www.npmjs.com/)
 
@@ -249,7 +249,7 @@ and the expert guidance it needs to use them effectively.
 
 1.  Open the **Command Palette** (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux).
 2.  Search for and run the **Chat: Install Plugin From Source** command.
-3.  Paste in our repository URL: `https://github.com/ChromeDevTools/chrome-devtools-mcp`
+3.  Paste in our repository name: `ChromeDevTools/chrome-devtools-mcp`.
 
 That's it! Your agent is now supercharged with Chrome DevTools capabilities.
 
@@ -514,11 +514,12 @@ 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** (4 tools)
-  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
-  - [`get_memory_snapshot_details`](docs/tool-reference.md#get_memory_snapshot_details)
-  - [`get_nodes_by_class`](docs/tool-reference.md#get_nodes_by_class)
-  - [`load_memory_snapshot`](docs/tool-reference.md#load_memory_snapshot)
+- **Memory** (5 tools)
+  - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
+  - [`get_heapsnapshot_class_nodes`](docs/tool-reference.md#get_heapsnapshot_class_nodes)
+  - [`get_heapsnapshot_details`](docs/tool-reference.md#get_heapsnapshot_details)
+  - [`get_heapsnapshot_retainers`](docs/tool-reference.md#get_heapsnapshot_retainers)
+  - [`get_heapsnapshot_summary`](docs/tool-reference.md#get_heapsnapshot_summary)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)
@@ -595,10 +596,30 @@ The Chrome DevTools MCP server supports the following configuration option:
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
 
+- **`--experimentalPageIdRouting`/ `--experimental-page-id-routing`**
+  Whether to expose pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions).
+  - **Type:** boolean
+
+- **`--experimentalDevtools`/ `--experimental-devtools`**
+  Whether to enable automation over DevTools targets
+  - **Type:** boolean
+
 - **`--experimentalVision`/ `--experimental-vision`**
   Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.
   - **Type:** boolean
 
+- **`--experimentalMemory`/ `--experimental-memory`**
+  Whether to enable experimental memory tools.
+  - **Type:** boolean
+
+- **`--experimentalStructuredContent`/ `--experimental-structured-content`**
+  Whether to output structured formatted content.
+  - **Type:** boolean
+
+- **`--experimentalIncludeAllPages`/ `--experimental-include-all-pages`**
+  Whether to include all kinds of pages such as webviews or background pages as pages.
+  - **Type:** boolean
+
 - **`--experimentalScreencast`/ `--experimental-screencast`**
   Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.
   - **Type:** boolean
@@ -659,7 +680,7 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
 
 - **`--redactNetworkHeaders`/ `--redact-network-headers`**
-  If true, redacts some of the network headers considered senstive before returning to the client.
+  If true, redacts some of the network headers considered sensitive before returning to the client.
   - **Type:** boolean
   - **Default:** `false`
 
@@ -708,6 +729,34 @@ You can also run `npx chrome-devtools-mcp@latest --help` to see all available co
 
 ## Concepts
 
+### Concurrent sessions
+
+Most MCP clients start one Chrome DevTools MCP server per conversation. If your
+client shares a single server instance across concurrent agents or subagents,
+start the server with `--experimentalPageIdRouting`. This exposes `pageId` on
+page-scoped tools so each agent can route tool calls to the tab it is working
+with.
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@latest",
+        "--experimentalPageIdRouting"
+      ]
+    }
+  }
+}
+```
+
+If you run multiple independent MCP client sessions and want each session to
+launch its own temporary Chrome profile, also pass `--isolated`. This avoids
+sharing the default Chrome DevTools MCP user data directory between those
+server instances.
+
 ### User data directory
 
 `chrome-devtools-mcp` starts a Chrome's stable channel instance using the following user

package/build/src/DevtoolsUtils.js

@@ -106,9 +106,10 @@ const DEFAULT_FACTORY = async (page) => {
     const connection = new PuppeteerDevToolsConnection(session);
     const targetManager = universe.context.get(DevTools.TargetManager);
     targetManager.observeModels(DevTools.DebuggerModel, SKIP_ALL_PAUSES);
+    targetManager.observeModels(DevTools.NetworkManager.NetworkManager, DISABLE_NETWORK);
     const target = targetManager.createTarget('main', '', 'frame', // eslint-disable-line @typescript-eslint/no-explicit-any
     /* parentTarget */ null, session.id(), undefined, connection);
-    return { target, universe };
+    return { target, universe, session };
 };
 // We don't want to pause any DevTools universe session ever on the MCP side.
 //
@@ -123,6 +124,18 @@ const SKIP_ALL_PAUSES = {
         // Do nothing.
     },
 };
+// Not recording network requests in the DevTools universe.
+//
+// The network requests are collected through pptr and there isn't a use case for
+// enabling devtools SDK's network domain.
+const DISABLE_NETWORK = {
+    modelAdded(model) {
+        void model.target().networkAgent().invoke_disable();
+    },
+    modelRemoved() {
+        // Do nothing.
+    },
+};
 /**
  * Constructed from Runtime.ExceptionDetails of an uncaught error.
  *

package/build/src/HeapSnapshotManager.js

@@ -5,6 +5,7 @@
  */
 import fsSync from 'node:fs';
 import path from 'node:path';
+import { isNodeLike } from './formatters/HeapSnapshotFormatter.js';
 import { DevTools } from './third_party/index.js';
 import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
 export class HeapSnapshotManager {
@@ -19,8 +20,8 @@ export class HeapSnapshotManager {
         this.#snapshots.set(absolutePath, {
             snapshot,
             worker,
-            uidToClassKey: new Map(),
-            classKeyToUid: new Map(),
+            idToClassKey: new Map(),
+            classKeyToId: new Map(),
             idGenerator: createIdGenerator(),
         });
         return snapshot;
@@ -30,10 +31,10 @@ export class HeapSnapshotManager {
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
         const aggregates = await snapshot.aggregatesWithFilter(filter);
         for (const key of Object.keys(aggregates)) {
-            const uid = await this.getOrCreateUidForClassKey(filePath, key);
+            const id = await this.getOrCreateIdForClassKey(filePath, key);
             const aggregate = aggregates[key];
             if (aggregate) {
-                aggregate[stableIdSymbol] = uid;
+                aggregate[stableIdSymbol] = id;
             }
         }
         return aggregates;
@@ -46,26 +47,49 @@ export class HeapSnapshotManager {
         const snapshot = await this.getSnapshot(filePath);
         return snapshot.staticData;
     }
-    async getOrCreateUidForClassKey(filePath, classKey) {
+    async getOrCreateIdForClassKey(filePath, classKey) {
         const cached = this.#getCachedSnapshot(filePath);
-        let uid = cached.classKeyToUid.get(classKey);
-        if (!uid) {
-            uid = cached.idGenerator();
-            cached.classKeyToUid.set(classKey, uid);
-            cached.uidToClassKey.set(uid, classKey);
+        let id = cached.classKeyToId.get(classKey);
+        if (!id) {
+            id = cached.idGenerator();
+            cached.classKeyToId.set(classKey, id);
+            cached.idToClassKey.set(id, classKey);
         }
-        return uid;
+        return id;
     }
-    async getNodesByUid(filePath, uid) {
+    async getNodesById(filePath, id) {
         const snapshot = await this.getSnapshot(filePath);
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
-        const className = await this.resolveClassKeyFromUid(filePath, uid);
+        const className = await this.resolveClassKeyFromId(filePath, id);
         if (!className) {
-            throw new Error(`Class with UID ${uid} not found in heap snapshot`);
+            throw new Error(`Class with ID ${id} not found in heap snapshot`);
         }
         const provider = snapshot.createNodesProviderForClass(className, filter);
-        const range = await provider.serializeItemsRange(0, 1);
-        return await provider.serializeItemsRange(0, range.totalLength);
+        return await provider.serializeItemsRange(0, Infinity);
+    }
+    async findNodeIndexById(filePath, nodeId) {
+        const snapshot = await this.getSnapshot(filePath);
+        const aggregates = await this.getAggregates(filePath);
+        const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        for (const classKey of Object.keys(aggregates)) {
+            const provider = snapshot.createNodesProviderForClass(classKey, filter);
+            const range = await provider.serializeItemsRange(0, Infinity);
+            for (const item of range.items) {
+                if (isNodeLike(item) && item.id === nodeId) {
+                    return item.nodeIndex;
+                }
+            }
+        }
+        return undefined;
+    }
+    async getRetainers(filePath, nodeId) {
+        const nodeIndex = await this.findNodeIndexById(filePath, nodeId);
+        if (nodeIndex === undefined) {
+            throw new Error(`Node with ID ${nodeId} not found`);
+        }
+        const snapshot = await this.getSnapshot(filePath);
+        const provider = snapshot.createRetainingEdgesProvider(nodeIndex);
+        return await provider.serializeItemsRange(0, Infinity);
     }
     #getCachedSnapshot(filePath) {
         const absolutePath = path.resolve(filePath);
@@ -75,9 +99,9 @@ export class HeapSnapshotManager {
         }
         return cached;
     }
-    async resolveClassKeyFromUid(filePath, uid) {
+    async resolveClassKeyFromId(filePath, id) {
         const cached = this.#getCachedSnapshot(filePath);
-        return cached.uidToClassKey.get(uid);
+        return cached.idToClassKey.get(id);
     }
     async #loadSnapshot(absolutePath) {
         const workerProxy = new DevTools.HeapSnapshotModel.HeapSnapshotProxy.HeapSnapshotWorkerProxy(() => {

package/build/src/McpContext.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import fs from 'node:fs/promises';
+import fsPromises from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -14,7 +15,7 @@ import { NetworkCollector, ConsoleCollector, } from './PageCollector.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 } from './utils/files.js';
+import { ensureExtension, getTempFilePath, resolveCanonicalPath, } from './utils/files.js';
 import { getNetworkMultiplierFromString } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -106,7 +107,7 @@ export class McpContext {
     setRoots(roots) {
         this.#roots = roots;
     }
-    validatePath(filePath) {
+    async validatePath(filePath) {
         if (filePath === undefined) {
             return;
         }
@@ -114,15 +115,36 @@ export class McpContext {
         if (roots === undefined) {
             return;
         }
-        const absolutePath = path.resolve(filePath);
+        let canonicalPath;
+        try {
+            canonicalPath = await resolveCanonicalPath(filePath);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[MCP Context] Error resolving real path for ${filePath}: ${errMsg}`);
+            throw new Error(`Access denied: Cannot resolve base path for ${filePath}.`);
+        }
+        let allowed = false;
         for (const root of roots) {
-            const rootPath = path.resolve(fileURLToPath(root.uri));
-            if (absolutePath === rootPath ||
-                absolutePath.startsWith(rootPath + path.sep)) {
-                return;
+            try {
+                const rootPathUri = root.uri;
+                const rootPath = path.resolve(fileURLToPath(rootPathUri));
+                const canonicalRoot = await fsPromises.realpath(rootPath);
+                if (canonicalPath === canonicalRoot ||
+                    canonicalPath.startsWith(canonicalRoot + path.sep)) {
+                    allowed = true;
+                    break;
+                }
+            }
+            catch (rootErr) {
+                const errMsg = rootErr instanceof Error ? rootErr.message : String(rootErr);
+                console.warn(`[MCP Context] Could not resolve configured root ${root.uri}: ${errMsg}`);
+                // Skip this root if it cannot be resolved.
             }
         }
-        throw new Error(`Access denied: path ${filePath} is not within any of the workspace roots ${JSON.stringify(roots)}.`);
+        if (!allowed) {
+            throw new Error(`Access denied: path ${filePath} (canonical: ${canonicalPath}) is not within any of the configured workspace roots.`);
+        }
     }
     resolveCdpRequestId(page, cdpRequestId) {
         if (!cdpRequestId) {
@@ -213,12 +235,23 @@ export class McpContext {
             await page.emulateNetworkConditions(networkCondition);
             newSettings.networkConditions = options.networkConditions;
         }
+        const secondarySession = this.getDevToolsUniverse(mcpPage)?.session;
         if (!options.cpuThrottlingRate) {
             await page.emulateCPUThrottling(1);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: 1,
+                });
+            }
             delete newSettings.cpuThrottlingRate;
         }
         else {
             await page.emulateCPUThrottling(options.cpuThrottlingRate);
+            if (secondarySession) {
+                await secondarySession.send('Emulation.setCPUThrottlingRate', {
+                    rate: options.cpuThrottlingRate,
+                });
+            }
             newSettings.cpuThrottlingRate = options.cpuThrottlingRate;
         }
         if (!options.geolocation) {
@@ -250,7 +283,6 @@ export class McpContext {
             newSettings.colorScheme = options.colorScheme;
         }
         if (!options.viewport) {
-            await page.setViewport(null);
             delete newSettings.viewport;
         }
         else {
@@ -260,14 +292,22 @@ export class McpContext {
                 hasTouch: false,
                 isLandscape: false,
             };
-            const viewport = { ...defaults, ...options.viewport };
-            await page.setViewport(viewport);
-            newSettings.viewport = viewport;
+            newSettings.viewport = { ...defaults, ...options.viewport };
+        }
+        if (options.extraHttpHeaders !== undefined) {
+            await page.setExtraHTTPHeaders(options.extraHttpHeaders);
+            newSettings.extraHttpHeaders = options.extraHttpHeaders;
+            if (Object.keys(options.extraHttpHeaders).length === 0) {
+                delete newSettings.extraHttpHeaders;
+            }
         }
         mcpPage.emulationSettings = Object.keys(newSettings).length
             ? newSettings
             : {};
         this.#updateSelectedPageTimeouts();
+        // This should happen after updating the page timeouts.
+        // Setting the viewport can trigger a reload which we don't want to timeout.
+        await page.setViewport(newSettings.viewport ?? null);
     }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
@@ -333,9 +373,9 @@ export class McpContext {
         page.pptrPage.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
         // 10sec should be enough for the load event to be emitted during
         // navigations.
-        // Increased in case we throttle the network requests
+        // Increased in case we throttle the network requests or the CPU
         const networkMultiplier = getNetworkMultiplierFromString(page.networkConditions);
-        page.pptrPage.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier);
+        page.pptrPage.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier * cpuMultiplier);
     }
     // Linear scan over per-page snapshots. The page count is small (typically
     // 2-10) so a reverse index isn't worthwhile given the uid-reuse lifecycle
@@ -499,7 +539,7 @@ export class McpContext {
     }
     async saveTemporaryFile(data, filename) {
         const filepath = await getTempFilePath(filename);
-        this.validatePath(filepath);
+        await this.validatePath(filepath);
         try {
             await fs.writeFile(filepath, data);
         }
@@ -509,7 +549,7 @@ export class McpContext {
         return { filepath };
     }
     async saveFile(data, clientProvidedFilePath, extension) {
-        this.validatePath(clientProvidedFilePath);
+        await this.validatePath(clientProvidedFilePath);
         try {
             const filePath = ensureExtension(path.resolve(clientProvidedFilePath), extension);
             await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -562,7 +602,6 @@ export class McpContext {
         await this.#networkCollector.init(pages);
     }
     async installExtension(extensionPath) {
-        this.validatePath(extensionPath);
         const id = await this.browser.installExtension(extensionPath);
         return id;
     }
@@ -586,20 +625,19 @@ export class McpContext {
         return pptrExtensions.get(id);
     }
     async getHeapSnapshotAggregates(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getAggregates(filePath);
     }
     async getHeapSnapshotStats(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStats(filePath);
     }
     async getHeapSnapshotStaticData(filePath) {
-        this.validatePath(filePath);
         return await this.#heapSnapshotManager.getStaticData(filePath);
     }
-    async getHeapSnapshotNodesByUid(filePath, uid) {
-        this.validatePath(filePath);
-        return await this.#heapSnapshotManager.getNodesByUid(filePath, uid);
+    async getHeapSnapshotNodesById(filePath, id) {
+        return await this.#heapSnapshotManager.getNodesById(filePath, id);
+    }
+    async getHeapSnapshotRetainers(filePath, nodeId) {
+        return await this.#heapSnapshotManager.getRetainers(filePath, nodeId);
     }
 }
 //# sourceMappingURL=McpContext.js.map

package/build/src/McpResponse.js

@@ -5,7 +5,7 @@
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
 import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
-import { isNodeLike } from './formatters/HeapSnapshotFormatter.js';
+import { isEdgeLike, isNodeLike } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
@@ -99,7 +99,7 @@ async function getToolGroup(page) {
             window.dispatchEvent(event);
             // If the page does not synchronously call `event.respondWith`, return instead of timing out
             setTimeout(() => {
-                resolve(undefined);
+                resolve(null);
             }, 0);
         });
     });
@@ -133,6 +133,7 @@ export class McpResponse {
     #page;
     #redactNetworkHeaders = true;
     #error;
+    #attachedWaitForResult;
     constructor(args) {
         this.#args = args;
     }
@@ -164,9 +165,7 @@ export class McpResponse {
         this.#listExtensions = true;
     }
     setListThirdPartyDeveloperTools() {
-        if (this.#args.categoryExperimentalThirdParty) {
-            this.#listThirdPartyDeveloperTools = true;
-        }
+        this.#listThirdPartyDeveloperTools = true;
     }
     setListWebMcpTools() {
         this.#listWebMcpTools = true;
@@ -265,6 +264,9 @@ export class McpResponse {
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
+    attachWaitForResult(result) {
+        this.#attachedWaitForResult = result;
+    }
     setHeapSnapshotAggregates(aggregates, options) {
         this.#heapSnapshotOptions = {
             ...this.#heapSnapshotOptions,
@@ -381,16 +383,21 @@ export class McpResponse {
         if (this.#listExtensions) {
             extensions = await context.listExtensions();
         }
+        // Null indicates no tools.
         let thirdPartyDeveloperTools;
-        if (this.#listThirdPartyDeveloperTools) {
-            const page = this.#page ?? context.getSelectedMcpPage();
-            thirdPartyDeveloperTools = await getToolGroup(page);
-            page.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
+        if (this.#args.categoryExperimentalThirdParty &&
+            this.#listThirdPartyDeveloperTools &&
+            this.#page) {
+            thirdPartyDeveloperTools = await getToolGroup(this.#page);
+            if (thirdPartyDeveloperTools) {
+                this.#page.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
+            }
         }
         let webmcpTools;
-        if (this.#listWebMcpTools && this.#args.categoryExperimentalWebmcp) {
-            const page = this.#page ?? context.getSelectedMcpPage();
-            webmcpTools = page.getWebMcpTools();
+        if (this.#args.categoryExperimentalWebmcp &&
+            this.#listWebMcpTools &&
+            this.#page) {
+            webmcpTools = this.#page.getWebMcpTools();
         }
         let consoleMessages;
         if (this.#consoleDataOptions?.include) {
@@ -481,6 +488,13 @@ export class McpResponse {
             structuredContent.message = this.#textResponseLines.join('\n');
             response.push(...this.#textResponseLines);
         }
+        if (this.#attachedWaitForResult) {
+            if (this.#attachedWaitForResult.navigatedToUrl) {
+                response.push(`Page navigated to ${this.#attachedWaitForResult.navigatedToUrl}.`);
+                structuredContent.navigatedToUrl =
+                    this.#attachedWaitForResult.navigatedToUrl;
+            }
+        }
         const networkConditions = this.#page?.networkConditions;
         if (networkConditions) {
             const timeout = this.#page.pptrPage.getDefaultNavigationTimeout();
@@ -489,6 +503,11 @@ export class McpResponse {
             structuredContent.networkConditions = networkConditions;
             structuredContent.navigationTimeout = timeout;
         }
+        const geolocation = this.#page?.geolocation;
+        if (geolocation) {
+            response.push(`Emulating geolocation: latitude=${geolocation.latitude}, longitude=${geolocation.longitude}`);
+            structuredContent.geolocation = geolocation;
+        }
         const viewport = this.#page?.viewport;
         if (viewport) {
             response.push(`Emulating viewport: ${JSON.stringify(viewport)}`);
@@ -664,10 +683,19 @@ Call ${handleDialog.name} to handle it before continuing.`);
             }
             const nodes = this.#heapSnapshotOptions.nodes;
             if (nodes) {
-                const sortedItems = nodes.items
-                    .filter(isNodeLike)
-                    .sort((a, b) => b.retainedSize - a.retainedSize);
-                const paginationData = this.#dataWithPagination(sortedItems, this.#heapSnapshotOptions.pagination);
+                let items = Array.from(nodes.items);
+                const firstItem = nodes.items[0];
+                if (firstItem) {
+                    if (isNodeLike(firstItem)) {
+                        items = items
+                            .filter(isNodeLike)
+                            .sort((a, b) => b.retainedSize - a.retainedSize);
+                    }
+                    else if (isEdgeLike(firstItem)) {
+                        items = items.filter(isEdgeLike);
+                    }
+                }
+                const paginationData = this.#dataWithPagination(items, this.#heapSnapshotOptions.pagination);
                 response.push(HeapSnapshotFormatter.formatNodes(paginationData.items));
                 structuredContent.pagination = paginationData.pagination;
                 response.push(...paginationData.info);
@@ -700,12 +728,14 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(extensionsMessage);
             }
         }
-        if (this.#listThirdPartyDeveloperTools) {
-            structuredContent.thirdPartyDeveloperTools =
-                data.thirdPartyDeveloperTools ?? undefined;
+        if (data.thirdPartyDeveloperTools !== undefined) {
+            if (data.thirdPartyDeveloperTools) {
+                structuredContent.thirdPartyDeveloperTools =
+                    data.thirdPartyDeveloperTools;
+            }
             response.push('## Third-party developer tools');
-            if (!data.thirdPartyDeveloperTools ||
-                !data.thirdPartyDeveloperTools.tools) {
+            if (data.thirdPartyDeveloperTools === null ||
+                !data.thirdPartyDeveloperTools?.tools) {
                 response.push('No third-party developer tools available.');
             }
             else {

package/build/src/ToolHandler.js

@@ -7,7 +7,8 @@ import { logger } from './logger.js';
 import { McpResponse } from './McpResponse.js';
 import { SlimMcpResponse } from './SlimMcpResponse.js';
 import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
-import { bucketizeLatency } from './telemetry/metricUtils.js';
+import { bucketizeLatency } from './telemetry/transformation.js';
+import { zod } from './third_party/index.js';
 import { labels, OFF_BY_DEFAULT_CATEGORIES } from './tools/categories.js';
 import { pageIdSchema } from './tools/ToolDefinition.js';
 export function buildFlag(category) {
@@ -70,12 +71,24 @@ function getToolStatusInfo(tool, serverArgs) {
 function isPageScopedTool(tool) {
     return 'pageScoped' in tool && tool.pageScoped === true;
 }
+function formatArgumentNames(names) {
+    return names.map(name => `"${name}"`).join(', ');
+}
+function buildUnknownArgumentsMessage(toolName, unknownArgumentNames, expectedArgumentNames) {
+    const unknownLabel = unknownArgumentNames.length === 1 ? 'argument' : 'arguments';
+    const expectedArguments = expectedArgumentNames.length
+        ? `Expected arguments: ${formatArgumentNames(expectedArgumentNames)}.`
+        : 'This tool does not accept any arguments.';
+    const correction = unknownArgumentNames.length === 1 ? 'Remove it' : 'Remove them';
+    return `Unknown ${unknownLabel} for tool "${toolName}": ${formatArgumentNames(unknownArgumentNames)}. ${expectedArguments} ${correction} and retry.`;
+}
 export class ToolHandler {
     tool;
     serverArgs;
     getContext;
     toolMutex;
     inputSchema;
+    registeredInputSchema;
     shouldRegister;
     disabledReason;
     constructor(tool, serverArgs, getContext, toolMutex) {
@@ -93,6 +106,10 @@ export class ToolHandler {
                 !serverArgs.slim
                 ? { ...tool.schema, ...pageIdSchema }
                 : tool.schema;
+        this.registeredInputSchema = zod.object(this.inputSchema).passthrough();
+    }
+    unknownArgumentNames(params) {
+        return Object.keys(params).filter(key => !Object.hasOwn(this.inputSchema, key));
     }
     async handle(params) {
         if (this.disabledReason) {
@@ -106,6 +123,18 @@ export class ToolHandler {
                 isError: true,
             };
         }
+        const unknownArgumentNames = this.unknownArgumentNames(params);
+        if (unknownArgumentNames.length) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: buildUnknownArgumentsMessage(this.tool.name, unknownArgumentNames, Object.keys(this.inputSchema)),
+                    },
+                ],
+                isError: true,
+            };
+        }
         const guard = await this.toolMutex.acquire();
         const startTime = Date.now();
         let success = false;