brave-mcp 1.3.0 → 1.6.0

package/README.md

@@ -239,9 +239,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"
       ]
     }
   }
@@ -451,6 +451,16 @@ Alternatively, follow the <a href="https://github.com/google-gemini/gemini-cli/b
   using the standard config from above.
 </details>
 
+<details>
+  <summary>Grok Build CLI</summary>
+
+```bash
+grok mcp add chrome-devtools npx chrome-devtools-mcp@latest
+```
+
+See the <a href="https://docs.x.ai/build/features/skills-plugins-marketplaces">docs</a> for more options
+</details>
+
 <details>
   <summary>JetBrains AI Assistant & Junie</summary>
 
@@ -632,12 +642,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)
@@ -671,14 +683,17 @@ The Brave DevTools MCP server supports the following configuration options:
 - **`--browserUrl`/ `--browser-url`, `-u`**
   Connect to a running, debuggable Brave instance (e.g. `http://127.0.0.1:9222`).
   - **Type:** string
+  - **Default:** `false`
 
 - **`--wsEndpoint`/ `--ws-endpoint`, `-w`**
   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
+  - **Default:** `false`
 
 - **`--wsHeaders`/ `--ws-headers`**
   Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint.
   - **Type:** string
+  - **Default:** `false`
 
 - **`--headless`**
   Whether to run in headless (no UI) mode.
@@ -688,87 +703,108 @@ The Brave DevTools MCP server supports the following configuration options:
 - **`--executablePath`/ `--executable-path`, `-e`**
   Path to custom Brave executable. Can also be set via BRAVE_PATH environment variable.
   - **Type:** string
+  - **Default:** `false`
 
 - **`--isolated`**
   If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--userDataDir`/ `--user-data-dir`**
   Path to the user data directory for Brave. Default is $HOME/.cache/brave-devtools-mcp/brave-profile$CHANNEL_SUFFIX_IF_NON_RELEASE
   - **Type:** string
+  - **Default:** `false`
 
 - **`--channel`**
   Specify a different Brave channel that should be used. The default is the release channel.
   - **Type:** string
   - **Choices:** `release`, `beta`, `nightly`, `dev`
+  - **Default:** `false`
 
 - **`--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
+  - **Default:** `false`
 
 - **`--viewport`**
   Initial viewport size for the Brave instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
   - **Type:** string
+  - **Default:** `false`
 
 - **`--proxyServer`/ `--proxy-server`**
   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
+  - **Default:** `false`
 
 - **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--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
+  - **Default:** `false`
 
 - **`--experimentalDevtools`/ `--experimental-devtools`**
   Whether to enable automation over DevTools targets
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--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
+  - **Default:** `false`
 
 - **`--memoryDebugging`/ `--memory-debugging`, `-experimentalMemory`**
   Whether to enable memory debugging tools.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--experimentalStructuredContent`/ `--experimental-structured-content`**
   Whether to output structured formatted content.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--experimentalIncludeAllPages`/ `--experimental-include-all-pages`**
   Whether to include all kinds of pages such as webviews or background pages as pages.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--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
+  - **Default:** `false`
 
 - **`--experimentalFfmpegPath`/ `--experimental-ffmpeg-path`**
   Path to ffmpeg executable for screencast recording.
   - **Type:** string
+  - **Default:** `false`
 
 - **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
   Set to true to enable debugging WebMCP tools. Requires Brave with the following flags: `--enable-features=WebMCP,DevToolsWebMCPSupport`
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--braveArg`/ `--brave-arg`**
   Additional arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.
   - **Type:** array
+  - **Default:** `false`
 
 - **`--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.
+  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.
   - **Type:** array
+  - **Default:** `false`
 
 - **`--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.
+  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.
   - **Type:** array
+  - **Default:** `false`
 
 - **`--ignoreDefaultBraveArg`/ `--ignore-default-brave-arg`**
   Explicitly disable default arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.
   - **Type:** array
+  - **Default:** `false`
 
 - **`--categoryEmulation`/ `--category-emulation`**
   Set to false to exclude tools related to emulation.
@@ -809,28 +845,38 @@ The Brave DevTools MCP server supports the following configuration options:
   Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").
   - **Type:** string
   - **Choices:** `jpeg`, `png`, `webp`
+  - **Default:** `false`
 
 - **`--screenshotQuality`/ `--screenshot-quality`**
   Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.
   - **Type:** number
+  - **Default:** `false`
 
 - **`--screenshotMaxWidth`/ `--screenshot-max-width`**
   Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.
   - **Type:** number
+  - **Default:** `false`
 
 - **`--screenshotMaxHeight`/ `--screenshot-max-height`**
   Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.
   - **Type:** number
+  - **Default:** `false`
 
 - **`--slim`**
   Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.
   - **Type:** boolean
+  - **Default:** `false`
 
 - **`--redactNetworkHeaders`/ `--redact-network-headers`**
   If true, redacts some of the network headers considered sensitive before returning to the client.
   - **Type:** boolean
   - **Default:** `false`
 
+- **`--allowUnrestrictedPaths`/ `--allow-unrestricted-paths`**
+  If set, disables the default path restriction that applies when the MCP client does not negotiate the roots capability. By default, file-writing tools are restricted to the OS temp directory when no roots are configured. Use this only when connecting a trusted local client that does not implement MCP roots and requires access to paths outside the temp directory.
+  - **Type:** boolean
+  - **Default:** `false`
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:
@@ -930,3 +976,9 @@ Please consult [these instructions](./docs/debugging-android.md) (originally wri
 ## Known limitations
 
 See [Troubleshooting](./docs/troubleshooting.md).
+
+## Integrating as a browser subagent
+
+If you are developing agentic tooling and want to provide an integrated browser subagent as part of your product, we recommend building on top of Chrome DevTools for agents.
+
+For a reference implementation, see the [Gemini CLI browser agent documentation](https://geminicli.com/docs/core/subagents/#browser-agent).

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,28 +16,36 @@ 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,
-            idToClassKey: new Map(),
+            idToClassKey: [''],
             classKeyToId: new Map(),
-            idGenerator: createIdGenerator(),
         });
         return snapshot;
     }
-    async getAggregates(filePath) {
+    async getAggregates(filePath, filterName) {
         const snapshot = await this.getSnapshot(filePath);
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        if (filterName) {
+            filter.filterName = filterName;
+        }
         const aggregates = await snapshot.aggregatesWithFilter(filter);
-        for (const key of Object.keys(aggregates)) {
+        let objectCount = 0;
+        let totalSelfSize = 0;
+        for (const [key, aggregate] of Object.entries(aggregates)) {
             const id = await this.getOrCreateIdForClassKey(filePath, key);
-            const aggregate = aggregates[key];
-            if (aggregate) {
-                aggregate[stableIdSymbol] = id;
-            }
+            aggregate[stableIdSymbol] = id;
+            objectCount += aggregate.count;
+            totalSelfSize += aggregate.self;
         }
-        return aggregates;
+        return {
+            aggregates,
+            objectCount,
+            totalSelfSize,
+        };
     }
     async getStats(filePath) {
         const snapshot = await this.getSnapshot(filePath);
@@ -50,15 +59,18 @@ export class HeapSnapshotManager {
         const cached = this.#getCachedSnapshot(filePath);
         let id = cached.classKeyToId.get(classKey);
         if (!id) {
-            id = cached.idGenerator();
+            id = cached.idToClassKey.length;
             cached.classKeyToId.set(classKey, id);
-            cached.idToClassKey.set(id, classKey);
+            cached.idToClassKey.push(classKey);
         }
         return id;
     }
-    async getNodesById(filePath, id) {
+    async getNodesById(filePath, id, filterName) {
         const snapshot = await this.getSnapshot(filePath);
         const filter = new DevTools.HeapSnapshotModel.HeapSnapshotModel.NodeFilter();
+        if (filterName) {
+            filter.filterName = filterName;
+        }
         const className = await this.resolveClassKeyFromId(filePath, id);
         if (!className) {
             throw new Error(`Class with ID ${id} not found in heap snapshot`);
@@ -100,6 +112,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 +152,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);
+        return cached.idToClassKey[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 +194,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;
     }