brave-mcp 0.3.0 → 0.4.0

package/README.md

@@ -586,7 +586,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 +596,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 +614,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 -->
 
@@ -704,7 +716,7 @@ The Brave DevTools MCP server supports the following configuration options:
   Path to ffmpeg executable for screencast recording.
   - **Type:** string
 
-- **`--experimentalWebmcp`/ `--experimental-webmcp`**
+- **`--categoryExperimentalWebmcp`/ `--category-experimental-webmcp`**
   Set to true to enable debugging WebMCP tools. Requires Chrome 149+ with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`
   - **Type:** boolean
 
@@ -736,6 +748,11 @@ 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

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();