brave-mcp 0.3.0 → 0.5.0

package/README.md

@@ -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"
       ]
     }
   }
@@ -586,7 +595,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
-- **Input automation** (9 tools)
+- **Input automation** (10 tools)
   - [`click`](docs/tool-reference.md#click)
   - [`drag`](docs/tool-reference.md#drag)
   - [`fill`](docs/tool-reference.md#fill)
@@ -596,6 +605,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`press_key`](docs/tool-reference.md#press_key)
   - [`type_text`](docs/tool-reference.md#type_text)
   - [`upload_file`](docs/tool-reference.md#upload_file)
+  - [`click_at`](docs/tool-reference.md#click_at)
 - **Navigation automation** (6 tools)
   - [`close_page`](docs/tool-reference.md#close_page)
   - [`list_pages`](docs/tool-reference.md#list_pages)
@@ -613,21 +623,32 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
 - **Network** (2 tools)
   - [`get_network_request`](docs/tool-reference.md#get_network_request)
   - [`list_network_requests`](docs/tool-reference.md#list_network_requests)
-- **Debugging** (6 tools)
+- **Debugging** (8 tools)
   - [`evaluate_script`](docs/tool-reference.md#evaluate_script)
   - [`get_console_message`](docs/tool-reference.md#get_console_message)
   - [`lighthouse_audit`](docs/tool-reference.md#lighthouse_audit)
   - [`list_console_messages`](docs/tool-reference.md#list_console_messages)
   - [`take_screenshot`](docs/tool-reference.md#take_screenshot)
   - [`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)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)
   - [`reload_extension`](docs/tool-reference.md#reload_extension)
   - [`trigger_extension_action`](docs/tool-reference.md#trigger_extension_action)
   - [`uninstall_extension`](docs/tool-reference.md#uninstall_extension)
-- **Memory** (1 tools)
-  - [`take_memory_snapshot`](docs/tool-reference.md#take_memory_snapshot)
+- **Third-party** (2 tools)
+  - [`execute_3p_developer_tool`](docs/tool-reference.md#execute_3p_developer_tool)
+  - [`list_3p_developer_tools`](docs/tool-reference.md#list_3p_developer_tools)
+- **WebMCP** (2 tools)
+  - [`execute_webmcp_tool`](docs/tool-reference.md#execute_webmcp_tool)
+  - [`list_webmcp_tools`](docs/tool-reference.md#list_webmcp_tools)
 
 <!-- END AUTO GENERATED TOOLS -->
 
@@ -638,16 +659,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`**
@@ -660,7 +681,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`**
@@ -668,24 +689,24 @@ 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`**
@@ -704,16 +725,16 @@ The Brave DevTools MCP server supports the following configuration options:
   Path to ffmpeg executable for screencast recording.
   - **Type:** string
 
-- **`--experimentalWebmcp`/ `--experimental-webmcp`**
-  Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
+- **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
+  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
 
-- **`--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`**
@@ -736,15 +757,20 @@ The Brave DevTools MCP server supports the following configuration options:
   - **Type:** boolean
   - **Default:** `false`
 
+- **`--categoryExperimentalThirdParty`/ `--category-experimental-third-party`**
+  Set to true to enable third-party developer tools exposed by the inspected page itself
+  - **Type:** boolean
+  - **Default:** `false`
+
 - **`--performanceCrux`/ `--performance-crux`**
   Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.
   - **Type:** boolean
   - **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.

package/build/src/McpContext.js

@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { UniverseManager } from './DevtoolsUtils.js';
 import { HeapSnapshotManager } from './HeapSnapshotManager.js';
 import { McpPage } from './McpPage.js';
@@ -91,7 +92,16 @@ export class McpContext {
         return context;
     }
     roots() {
-        return this.#roots;
+        if (this.#roots === undefined) {
+            return undefined;
+        }
+        return [
+            ...this.#roots,
+            {
+                uri: pathToFileURL(os.tmpdir()).href,
+                name: 'temp',
+            },
+        ];
     }
     setRoots(roots) {
         this.#roots = roots;

package/build/src/McpPage.js

@@ -30,7 +30,7 @@ export class McpPage {
     // Dialog
     #dialog;
     #dialogHandler;
-    inPageTools;
+    thirdPartyDeveloperTools;
     constructor(page, id) {
         this.pptrPage = page;
         this.id = id;
@@ -48,8 +48,13 @@ export class McpPage {
     clearDialog() {
         this.#dialog = undefined;
     }
-    getInPageTools() {
-        return this.inPageTools;
+    throwIfDialogOpen() {
+        if (this.#dialog) {
+            throw new Error(`A dialog is open (${this.#dialog.type()}: ${this.#dialog.message()}).`);
+        }
+    }
+    getThirdPartyDeveloperTools() {
+        return this.thirdPartyDeveloperTools;
     }
     getWebMcpTools() {
         return this.pptrPage.webmcp.tools();
@@ -83,7 +88,7 @@ export class McpPage {
     dispose() {
         this.pptrPage.off('dialog', this.#dialogHandler);
     }
-    async executeInPageTool(toolName, params, response) {
+    async executeThirdPartyDeveloperTool(toolName, params, response) {
         // Creates array of ElementHandles from the UIDs in the params.
         // We do not replace the uids with the ElementsHandles yet, because
         // the `evaluate` function only turns them into DOM elements if they

package/build/src/McpResponse.js

@@ -5,6 +5,7 @@
  */
 import { ConsoleFormatter } from './formatters/ConsoleFormatter.js';
 import { HeapSnapshotFormatter } from './formatters/HeapSnapshotFormatter.js';
+import { isNodeLike } from './formatters/HeapSnapshotFormatter.js';
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
@@ -124,13 +125,14 @@ export class McpResponse {
     #networkRequestsOptions;
     #consoleDataOptions;
     #listExtensions;
-    #listInPageTools;
+    #listThirdPartyDeveloperTools;
     #listWebMcpTools;
     #devToolsData;
     #tabId;
     #args;
     #page;
     #redactNetworkHeaders = true;
+    #error;
     constructor(args) {
         this.#args = args;
     }
@@ -161,9 +163,9 @@ export class McpResponse {
     setListExtensions() {
         this.#listExtensions = true;
     }
-    setListInPageTools() {
-        if (this.#args.categoryInPageTools) {
-            this.#listInPageTools = true;
+    setListThirdPartyDeveloperTools() {
+        if (this.#args.categoryExperimentalThirdParty) {
+            this.#listThirdPartyDeveloperTools = true;
         }
     }
     setListWebMcpTools() {
@@ -204,6 +206,9 @@ export class McpResponse {
             includePreservedMessages: options?.includePreservedMessages,
         };
     }
+    setError(error) {
+        this.#error = error;
+    }
     attachNetworkRequest(reqId, options) {
         this.#attachedNetworkRequestId = reqId;
         this.#attachedNetworkRequestOptions = options;
@@ -254,6 +259,9 @@ export class McpResponse {
     get consoleMessagesTypes() {
         return this.#consoleDataOptions?.types;
     }
+    get error() {
+        return this.#error;
+    }
     appendResponseLine(value) {
         this.#textResponseLines.push(value);
     }
@@ -373,14 +381,14 @@ export class McpResponse {
         if (this.#listExtensions) {
             extensions = await context.listExtensions();
         }
-        let inPageTools;
-        if (this.#listInPageTools) {
+        let thirdPartyDeveloperTools;
+        if (this.#listThirdPartyDeveloperTools) {
             const page = this.#page ?? context.getSelectedMcpPage();
-            inPageTools = await getToolGroup(page);
-            page.inPageTools = inPageTools;
+            thirdPartyDeveloperTools = await getToolGroup(page);
+            page.thirdPartyDeveloperTools = thirdPartyDeveloperTools;
         }
         let webmcpTools;
-        if (this.#listWebMcpTools && this.#args.experimentalWebmcp) {
+        if (this.#listWebMcpTools && this.#args.categoryExperimentalWebmcp) {
             const page = this.#page ?? context.getSelectedMcpPage();
             webmcpTools = page.getWebMcpTools();
         }
@@ -461,8 +469,9 @@ export class McpResponse {
             traceSummary: this.#attachedTraceSummary,
             extensions,
             lighthouseResult: this.#attachedLighthouseResult,
-            inPageTools,
+            thirdPartyDeveloperTools,
             webmcpTools,
+            errorMessage: this.#error?.message,
         });
     }
     format(toolName, context, data) {
@@ -655,7 +664,10 @@ Call ${handleDialog.name} to handle it before continuing.`);
             }
             const nodes = this.#heapSnapshotOptions.nodes;
             if (nodes) {
-                const paginationData = this.#dataWithPagination(nodes.items, this.#heapSnapshotOptions.pagination);
+                const sortedItems = nodes.items
+                    .filter(isNodeLike)
+                    .sort((a, b) => b.retainedSize - a.retainedSize);
+                const paginationData = this.#dataWithPagination(sortedItems, this.#heapSnapshotOptions.pagination);
                 response.push(HeapSnapshotFormatter.formatNodes(paginationData.items));
                 structuredContent.pagination = paginationData.pagination;
                 response.push(...paginationData.info);
@@ -688,14 +700,16 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(extensionsMessage);
             }
         }
-        if (this.#listInPageTools) {
-            structuredContent.inPageTools = data.inPageTools ?? undefined;
-            response.push('## In-page tools');
-            if (!data.inPageTools || !data.inPageTools.tools) {
-                response.push('No in-page tools available.');
+        if (this.#listThirdPartyDeveloperTools) {
+            structuredContent.thirdPartyDeveloperTools =
+                data.thirdPartyDeveloperTools ?? undefined;
+            response.push('## Third-party developer tools');
+            if (!data.thirdPartyDeveloperTools ||
+                !data.thirdPartyDeveloperTools.tools) {
+                response.push('No third-party developer tools available.');
             }
             else {
-                const toolGroup = data.inPageTools;
+                const toolGroup = data.thirdPartyDeveloperTools;
                 response.push(`${toolGroup.name}: ${toolGroup.description}`);
                 response.push('Available tools:');
                 const toolDefinitionsMessage = toolGroup.tools
@@ -760,6 +774,10 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push('<no console messages found>');
             }
         }
+        if (data.errorMessage) {
+            response.push(`Error: ${data.errorMessage}`);
+            structuredContent.errorMessage = data.errorMessage;
+        }
         const text = {
             type: 'text',
             text: response.join('\n'),

package/build/src/TextSnapshot.js

@@ -99,8 +99,8 @@ export class TextSnapshot {
         return snapshot;
     }
     // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
-    // returned by in-page tools. We insert them into the tree by finding the closest ancestor in the
-    // tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+    // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
+    // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
     static async insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, extraHandles) {
         const { uniqueBackendNodeIdToMcpId } = page;
         const createExtraNode = async (handle) => {

package/build/src/WaitForHelper.js

@@ -104,8 +104,10 @@ export class WaitForHelper {
         });
     }
     async waitForEventsAfterAction(action, options) {
+        let dialogOpened = false;
         if (options?.handleDialog) {
             const dialogHandler = (dialog) => {
+                dialogOpened = true;
                 if (options.handleDialog === 'dismiss') {
                     void dialog.dismiss();
                 }
@@ -142,6 +144,9 @@ export class WaitForHelper {
         }
         try {
             await navigationFinished;
+            if (dialogOpened) {
+                return;
+            }
             // Wait for stable dom after navigation so we execute in
             // the correct context
             await this.waitForStableDom();