brave-mcp 0.4.0 → 1.2.0

package/README.md

@@ -38,7 +38,7 @@ You can explicitly enable them with `--usage-statistics` if desired.
 
 ## 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.
 - [Brave Browser](https://brave.com/) current release version or newer.
 - [npm](https://www.npmjs.com/)
 
@@ -96,7 +96,9 @@ If Brave is not detected automatically, set `BRAVE_PATH`:
   "mcpServers": {
     "brave-devtools": {
       "command": "node",
-      "args": ["/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js"],
+      "args": [
+        "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js"
+      ],
       "env": {
         "BRAVE_PATH": "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
       }
@@ -139,7 +141,12 @@ brave-browser --remote-debugging-port=9222
   "mcpServers": {
     "brave-devtools": {
       "command": "npx",
-      "args": ["-y", "brave-mcp@latest", "--browserUrl", "http://localhost:9222"]
+      "args": [
+        "-y",
+        "brave-mcp@latest",
+        "--browserUrl",
+        "http://localhost:9222"
+      ]
     }
   }
 }
@@ -154,7 +161,8 @@ Or if running from source:
       "command": "node",
       "args": [
         "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js",
-        "--browserUrl", "http://localhost:9222"
+        "--browserUrl",
+        "http://localhost:9222"
       ]
     }
   }
@@ -198,7 +206,8 @@ If you are interested in only basic browser tasks, use `--slim` mode:
       "command": "node",
       "args": [
         "/absolute/path/to/brave-devtools-mcp/build/src/bin/brave-devtools-mcp.js",
-        "--slim", "--headless"
+        "--slim",
+        "--headless"
       ]
     }
   }
@@ -270,7 +279,7 @@ To install Chrome DevTools MCP with skills, add the marketplace registry in Clau
 Then, install the plugin:
 
 ```sh
-/plugin install chrome-devtools-mcp
+/plugin install chrome-devtools-mcp@chrome-devtools-plugins
 ```
 
 Restart Claude Code to have the MCP server and skills load (check with `/skills`).
@@ -358,7 +367,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.
 
@@ -623,11 +632,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** (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** (7 tools)
+  - [`take_heapsnapshot`](docs/tool-reference.md#take_heapsnapshot)
+  - [`close_heapsnapshot`](docs/tool-reference.md#close_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_retaining_paths`](docs/tool-reference.md#get_heapsnapshot_retaining_paths)
+  - [`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)
@@ -650,16 +662,16 @@ The Brave DevTools MCP server supports the following configuration options:
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
 - **`--autoConnect`/ `--auto-connect`**
-  If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remote debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
+  If specified, automatically connects to a Brave instance running locally from the user data directory identified by the channel param (default channel is release). Requires the remote debugging server to be started in the Brave instance via brave://inspect/#remote-debugging.
   - **Type:** boolean
   - **Default:** `false`
 
 - **`--browserUrl`/ `--browser-url`, `-u`**
-  Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.
+  Connect to a running, debuggable Brave instance (e.g. `http://127.0.0.1:9222`).
   - **Type:** string
 
 - **`--wsEndpoint`/ `--ws-endpoint`, `-w`**
-  WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.
+  WebSocket endpoint to connect to a running Brave instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.
   - **Type:** string
 
 - **`--wsHeaders`/ `--ws-headers`**
@@ -672,7 +684,7 @@ The Brave DevTools MCP server supports the following configuration options:
   - **Default:** `false`
 
 - **`--executablePath`/ `--executable-path`, `-e`**
-  Path to custom Chrome executable.
+  Path to custom Brave executable. Can also be set via BRAVE_PATH environment variable.
   - **Type:** string
 
 - **`--isolated`**
@@ -680,34 +692,54 @@ The Brave DevTools MCP server supports the following configuration options:
   - **Type:** boolean
 
 - **`--userDataDir`/ `--user-data-dir`**
-  Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE
+  Path to the user data directory for Brave. Default is $HOME/.cache/brave-devtools-mcp/brave-profile$CHANNEL_SUFFIX_IF_NON_RELEASE
   - **Type:** string
 
 - **`--channel`**
-  Specify a different Chrome channel that should be used. The default is the stable channel version.
+  Specify a different Brave channel that should be used. The default is the release channel.
   - **Type:** string
-  - **Choices:** `canary`, `dev`, `beta`, `stable`
+  - **Choices:** `release`, `beta`, `nightly`, `dev`
 
 - **`--logFile`/ `--log-file`**
   Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
   - **Type:** string
 
 - **`--viewport`**
-  Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
+  Initial viewport size for the Brave instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
   - **Type:** string
 
 - **`--proxyServer`/ `--proxy-server`**
-  Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
+  Proxy server configuration for Brave passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
   - **Type:** string
 
 - **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
   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
 
+- **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`**
+  Whether to enable memory debugging 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
@@ -717,15 +749,23 @@ The Brave DevTools MCP server supports the following configuration options:
   - **Type:** string
 
 - **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
-  Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
+  Set to true to enable debugging WebMCP tools. Requires Brave with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
   - **Type:** boolean
 
-- **`--chromeArg`/ `--chrome-arg`**
-  Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+- **`--braveArg`/ `--brave-arg`**
+  Additional arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.
+  - **Type:** array
+
+- **`--blockedUrlPattern`/ `--blocked-url-pattern`**
+  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.
+  - **Type:** array
+
+- **`--allowedUrlPattern`/ `--allowed-url-pattern`**
+  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.
   - **Type:** array
 
-- **`--ignoreDefaultChromeArg`/ `--ignore-default-chrome-arg`**
-  Explicitly disable default arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
+- **`--ignoreDefaultBraveArg`/ `--ignore-default-brave-arg`**
+  Explicitly disable default arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.
   - **Type:** array
 
 - **`--categoryEmulation`/ `--category-emulation`**
@@ -759,16 +799,16 @@ The Brave DevTools MCP server supports the following configuration options:
   - **Default:** `true`
 
 - **`--usageStatistics`/ `--usage-statistics`**
-  Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics. Disabled if `CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS` or `CI` env variables are set.
+  Usage statistics collection (disabled by default in this fork).
   - **Type:** boolean
-  - **Default:** `true`
+  - **Default:** `false`
 
 - **`--slim`**
   Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.
   - **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`
 
@@ -817,6 +857,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
 
 `brave-devtools-mcp` starts a Brave release channel instance using the following user

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,57 @@ 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);
+    }
+    async getRetainingPaths(filePath, nodeId, maxDepth, maxNodes, maxSiblings) {
+        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);
+        return await snapshot.getRetainingPaths(nodeIndex, maxDepth, maxNodes, maxSiblings);
     }
     #getCachedSnapshot(filePath) {
         const absolutePath = path.resolve(filePath);
@@ -75,9 +107,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(() => {
@@ -98,13 +130,18 @@ export class HeapSnapshotManager {
         const snapshot = await snapshotPromise;
         return { snapshot, worker: workerProxy };
     }
+    hasSnapshots() {
+        return this.#snapshots.size > 0;
+    }
     dispose(filePath) {
         const absolutePath = path.resolve(filePath);
         const cached = this.#snapshots.get(absolutePath);
         if (cached) {
             cached.worker.dispose();
             this.#snapshots.delete(absolutePath);
+            return true;
         }
+        return false;
     }
 }
 //# sourceMappingURL=HeapSnapshotManager.js.map