brave-mcp 1.7.0 → 1.8.0

package/README.md

@@ -1,16 +1,62 @@
 # Brave DevTools for agents
 
-[![npm brave-mcp package](https://img.shields.io/npm/v/brave-mcp.svg)](https://npmjs.org/package/brave-mcp)
+**Full Chrome DevTools MCP parity, rebuilt for Brave.**
 
-Brave DevTools for agents (`brave-mcp`) lets your coding agent (such as Antigravity, Claude, Cursor or Copilot)
-control and inspect a live Brave browser. It acts as a Model-Context-Protocol
-(MCP) server, giving your AI coding assistant access to the full power of
-Brave DevTools for reliable automation, in-depth debugging, and performance analysis.
-A [CLI](docs/cli.md) is also provided for use without MCP.
+[![CI](https://github.com/triuzzi/brave-devtools-mcp/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/triuzzi/brave-devtools-mcp/actions/workflows/run-tests.yml)
+[![npm](https://img.shields.io/npm/v/brave-mcp.svg?logo=npm)](https://www.npmjs.com/package/brave-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/brave-mcp.svg?logo=npm)](https://www.npmjs.com/package/brave-mcp)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-active-5B5BD6)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.triuzzi%2Fbrave-mcp)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-2E7D32)](https://registry.npmjs.org/-/npm/v1/attestations/brave-mcp@1.7.1)
+[![upstream](https://img.shields.io/badge/upstream-0%20commits%20behind-brightgreen)](https://github.com/triuzzi/brave-devtools-mcp/compare/ChromeDevTools:main...main)
+[![license](https://img.shields.io/github/license/triuzzi/brave-devtools-mcp)](./LICENSE)
 
-This Brave port tracks [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) and preserves its complete tool surface.
+![Brave DevTools MCP: full Chrome DevTools MCP parity, rebuilt for Brave](./docs/assets/social-preview.png)
 
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
+`brave-mcp` gives Claude Code, Codex, Cursor, OpenCode, and other MCP clients direct access to Brave for browser automation, network and console debugging, performance analysis, screenshots, accessibility inspection, and memory profiling. A standalone [`brave-devtools`](docs/cli.md) CLI is included too.
+
+## Install in one command
+
+### Claude Code
+
+```bash
+claude mcp add brave-devtools --scope user -- npx -y brave-mcp@latest
+```
+
+### Cursor
+
+```bash
+cursor --add-mcp '{"name":"brave-devtools","command":"npx","args":["-y","brave-mcp@latest"]}'
+```
+
+### Codex
+
+```bash
+codex mcp add brave-devtools -- npx -y brave-mcp@latest
+```
+
+### OpenCode
+
+```bash
+opencode mcp add brave-devtools -- npx -y brave-mcp@latest
+```
+
+Restart your client, then try this prompt:
+
+> Open my app in Brave. Find console errors and failed network requests, inspect the accessibility tree, run Lighthouse, and explain the highest-impact issue.
+
+## Why use this instead of Chrome DevTools MCP?
+
+| Capability                               | `brave-mcp`                             | `chrome-devtools-mcp`                |
+| ---------------------------------------- | --------------------------------------- | ------------------------------------ |
+| Browser launched and discovered natively | Brave Release, Beta, and Nightly        | Chrome Stable, Beta, Dev, and Canary |
+| Attach to an existing browser            | Brave profiles, HTTP, or WebSocket      | Chrome profiles, HTTP, or WebSocket  |
+| Upstream DevTools features               | Full parity; currently 0 commits behind | Source implementation                |
+| Usage telemetry                          | Disabled by default                     | Enabled by default                   |
+| Standalone CLI                           | `brave-devtools`                        | `chrome-devtools`                    |
+
+Use [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) when your target browser is Chrome. Use `brave-mcp` when your target browser is Brave and you want Brave-native discovery, profiles, channels, naming, and privacy defaults without giving up upstream features.
+
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design principles](./docs/design-principles.md)
 
 ## Key features
 
@@ -551,7 +597,7 @@ 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** (12 tools)
+- **Memory** (13 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)
@@ -564,6 +610,7 @@ If you run into any issues, checkout our [troubleshooting guide](./docs/troubles
   - [`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)
+  - [`query_heapsnapshot_objects`](docs/tool-reference.md#query_heapsnapshot_objects)
 - **Extensions** (5 tools)
   - [`install_extension`](docs/tool-reference.md#install_extension)
   - [`list_extensions`](docs/tool-reference.md#list_extensions)
@@ -656,10 +703,10 @@ The Brave DevTools MCP server supports the following configuration option:
   - **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).
+- **`--pageIdRouting`/ `--page-id-routing`**
+  Require pageId on page-scoped tools and route requests by page ID (useful for concurrent agent sessions). Use --no-page-id-routing to disable.
   - **Type:** boolean
-  - **Default:** `false`
+  - **Default:** `true`
 
 - **`--experimentalDevtools`/ `--experimental-devtools`**
   Whether to enable automation over DevTools targets
@@ -844,18 +891,25 @@ You can also run `npx brave-mcp@latest --help` to see all available configuratio
 
 ### Concurrent sessions
 
-Most MCP clients start one Brave 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.
+Most MCP clients start one Brave DevTools MCP server per conversation.
+By default, the server runs with `--pageIdRouting` enabled, making `pageId` a
+required parameter on page-scoped tools (such as `click`, `fill`, `navigate_page`,
+`take_snapshot`, etc.) so multiple agents or subagents sharing a server instance can
+route tool calls directly to the specific tab they are working with.
+
+For `evaluate_script`, `pageId` is required by default for targeting pages, but
+becomes optional when `--categoryExtensions` is enabled so that `serviceWorkerId`
+can be specified instead to evaluate inside an extension background service worker.
+
+To disable this behavior and default to the currently selected page, pass
+`--no-page-id-routing`.
 
 ```json
 {
   "mcpServers": {
     "brave-devtools": {
       "command": "npx",
-      "args": ["-y", "brave-mcp@latest", "--experimentalPageIdRouting"]
+      "args": ["-y", "brave-mcp@latest"]
     }
   }
 }

package/build/src/McpContext.js

@@ -8,9 +8,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { overrideDevToolsGlobals } from './devtools/DevtoolsUtils.js';
-import { HeapSnapshotManager } from './HeapSnapshotManager.js';
+import { HeapSnapshotManager } from './processors/HeapSnapshotManager.js';
 import { McpPage } from './McpPage.js';
-import { ServiceWorkerConsoleCollector } from './ServiceWorkerCollector.js';
+import { ServiceWorkerConsoleCollector } from './collectors/ServiceWorkerCollector.js';
 import { Locator, } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
@@ -137,28 +137,30 @@ export class McpContext {
     }
     async validatePath(filePath) {
         if (filePath === undefined) {
-            return;
+            return undefined;
+        }
+        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}.`);
         }
         // If the client never negotiated roots and the operator has explicitly
         // opted into unrestricted access via --allow-unrestricted-paths, restore
         // the previous permissive behavior and skip validation.
         if (this.#roots === undefined && this.#allowUnrestrictedPaths) {
-            return;
+            // Canonical path might not exist yet so we fallback to
+            // path.resolve(filePath). Consumers should not follow symlinks.
+            return canonicalPath || path.resolve(filePath);
         }
         // roots() always returns at least the temp directory, even if the
         // connecting client never negotiated the optional `roots` capability.
         // Path validation must not be skipped just because no workspace roots
         // were configured.
         const roots = this.roots();
-        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;
         const resolvedRoots = await Promise.allSettled(roots.map(async (root) => {
             const rootPathUri = root.uri;
@@ -186,12 +188,12 @@ export class McpContext {
         if (!allowed) {
             throw new Error(`Access denied: path ${filePath} (canonical: ${canonicalPath}) is not within any of the configured workspace roots.`);
         }
+        return canonicalPath || path.resolve(filePath);
     }
     async ensureExtension(filePath, extension) {
-        const resolvedPath = path.resolve(filePath);
-        const currentExtension = path.extname(resolvedPath);
-        const outputPath = `${resolvedPath.slice(0, resolvedPath.length - currentExtension.length)}${extension}`;
-        await this.validatePath(outputPath);
+        const resolved = await this.validatePath(filePath);
+        const currentExtension = path.extname(resolved);
+        const outputPath = `${resolved.slice(0, resolved.length - currentExtension.length)}${extension}`;
         return outputPath;
     }
     async newPage(background, isolatedContextName) {
@@ -266,6 +268,21 @@ export class McpContext {
         }
         return page;
     }
+    getSelectedMcpPageUrl(page) {
+        let targetPage = page;
+        if (!targetPage) {
+            try {
+                targetPage = this.getSelectedMcpPage();
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (targetPage?.pptrPage?.isClosed() === false) {
+            return targetPage.pptrPage.url();
+        }
+        return undefined;
+    }
     async getDevToolsData(page) {
         const targetPage = page ?? this.#selectedPage;
         if (!targetPage) {
@@ -441,16 +458,16 @@ export class McpContext {
         return this.#extensionServiceWorkerMap.get(extensionServiceWorker.target);
     }
     async #writeFile(filepath, data) {
-        await this.validatePath(filepath);
+        const resolved = await this.validatePath(filepath);
         try {
-            await fs.mkdir(path.dirname(filepath), { recursive: true });
+            await fs.mkdir(path.dirname(resolved), { recursive: true });
             // Open the file with flags to:
             // - O_WRONLY: Write-only
             // - O_CREAT: Create if it doesn't exist
             // - O_TRUNC: Truncate to zero length if it exists
             // - O_NOFOLLOW: DO NOT follow symlinks.
             // - 0o600: Permissions: read/write for owner, no permissions for others.
-            await fs.writeFile(filepath, data, {
+            await fs.writeFile(resolved, data, {
                 flag: fs.constants.O_WRONLY |
                     fs.constants.O_CREAT |
                     fs.constants.O_TRUNC |
@@ -515,6 +532,9 @@ export class McpContext {
     async getHeapSnapshotDuplicateStrings(filePath) {
         return await this.#heapSnapshotManager.getDuplicateStrings(filePath);
     }
+    async queryHeapSnapshotObjects(filePath, options) {
+        return await this.#heapSnapshotManager.queryObjects(filePath, options);
+    }
     async getHeapSnapshotStats(filePath) {
         return await this.#heapSnapshotManager.getStats(filePath);
     }
@@ -524,6 +544,9 @@ export class McpContext {
     async getHeapSnapshotNativeContextSizes(filePath) {
         return await this.#heapSnapshotManager.getNativeContextSizes(filePath);
     }
+    async getHeapSnapshotRetainedByContextSummary(filePath) {
+        return await this.#heapSnapshotManager.getRetainedByContextSummary(filePath);
+    }
     async getHeapSnapshotNodesById(filePath, id, filterName, objectId) {
         return await this.#heapSnapshotManager.getNodesById(filePath, id, filterName, objectId);
     }
@@ -582,15 +605,15 @@ export class McpContext {
                 return response.text();
             }
             case 'file:': {
-                await this.validatePath(fileURLToPath(url));
-                return await fs.readFile(url, 'utf-8');
+                const resolved = await this.validatePath(fileURLToPath(url));
+                return await fs.readFile(resolved, 'utf-8');
             }
             default:
                 throw new Error(`Unsupported protocol for: ${url}`);
         }
     }
-    async getHeapSnapshotEdges(filePath, nodeId) {
-        return await this.#heapSnapshotManager.getEdges(filePath, nodeId);
+    async getHeapSnapshotEdges(filePath, nodeId, options) {
+        return await this.#heapSnapshotManager.getEdges(filePath, nodeId, options);
     }
     async getHeapSnapshotClassDiffs(baseFilePath, currentFilePath) {
         return await this.#heapSnapshotManager.getClassDiffs(baseFilePath, currentFilePath);

package/build/src/McpPage.js

@@ -102,14 +102,14 @@ export function replaceHtmlElementsWithUids(schema) {
     }
 }
 import { createTargetUniverse, } from './devtools/DevtoolsUtils.js';
-import { ConsoleCollector, NetworkCollector, } from './PageCollector.js';
+import { ConsoleCollector, NetworkCollector, } from './collectors/PageCollector.js';
 import { TextSnapshot } from './TextSnapshot.js';
 import { PredefinedNetworkConditions, } from './third_party/index.js';
 import { takeSnapshot } from './tools/snapshot.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
 import { logger } from './utils/logger.js';
-import { getNetworkMultiplierFromString, WaitForHelper, } from './WaitForHelper.js';
+import { getNetworkMultiplierFromString, WaitForHelper, } from './utils/WaitForHelper.js';
 /**
  * Per-page state wrapper. Consolidates dialog, snapshot, emulation,
  * and metadata that were previously scattered across Maps in McpContext.

package/build/src/McpResponse.js

@@ -8,11 +8,11 @@ import { HeapSnapshotFormatter, isEdgeLike, isNodeLike, } from './formatters/Hea
 import { IssueFormatter } from './formatters/IssueFormatter.js';
 import { NetworkFormatter } from './formatters/NetworkFormatter.js';
 import { SnapshotFormatter } from './formatters/SnapshotFormatter.js';
-import { UncaughtError } from './PageCollector.js';
+import { UncaughtError } from './collectors/PageCollector.js';
 import { TextSnapshot } from './TextSnapshot.js';
 import { DevTools, getToonEncode, getGcfEncode } from './third_party/index.js';
 import { handleDialog, listPages } from './tools/pages.js';
-import { getInsightOutput, getTraceSummary } from './trace-processing/parse.js';
+import { getInsightOutput, getTraceSummary, } from './processors/PerformanceTrace.js';
 import { stableIdSymbol } from './utils/id.js';
 import { paginate } from './utils/pagination.js';
 const { formatBytesToKb } = DevTools.I18n.ByteUtilities;
@@ -196,13 +196,14 @@ export class McpResponse {
             pagination: options,
         };
     }
-    setHeapSnapshotStats(stats, staticData, nativeContextSizes) {
+    setHeapSnapshotStats(stats, staticData, nativeContextSizes, retainedByContextSummary) {
         this.#heapSnapshotOptions = {
             ...this.#heapSnapshotOptions,
             include: true,
             stats,
             staticData,
             nativeContextSizes,
+            retainedByContextSummary,
         };
     }
     setHeapSnapshotNodes(nodes, options) {
@@ -651,7 +652,11 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 for (const [insightName, model] of Object.entries(insightSet.model)) {
                     structuredContent.traceInsights.push({
                         insightName,
-                        insightKey: model.insightKey,
+                        insightKey: typeof model === 'object' &&
+                            model !== null &&
+                            'insightKey' in model
+                            ? model.insightKey
+                            : undefined,
                     });
                 }
             }
@@ -719,6 +724,14 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
                 structuredContent.heapSnapshot.nativeContextSizes = nativeContextSizes;
             }
+            const retainedByContextSummary = this.#heapSnapshotOptions.retainedByContextSummary;
+            if (retainedByContextSummary) {
+                response.push('### Retained by Context Summary');
+                response.push(HeapSnapshotFormatter.formatRetainedByContextSummary(retainedByContextSummary));
+                structuredContent.heapSnapshot = structuredContent.heapSnapshot || {};
+                structuredContent.heapSnapshot.retainedByContextSummary =
+                    retainedByContextSummary;
+            }
             const aggregateData = this.#heapSnapshotOptions.aggregateData;
             if (aggregateData) {
                 const sortedEntries = HeapSnapshotFormatter.sort(aggregateData.aggregates);

package/build/src/ToolHandler.js

@@ -11,6 +11,8 @@ import { zod } from './third_party/index.js';
 import { labels, OFF_BY_DEFAULT_CATEGORIES } from './tools/categories.js';
 import { pageIdSchema } from './tools/ToolDefinition.js';
 import { logger } from './utils/logger.js';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isLocalhost } from './utils/url.js';
 export function buildFlag(category) {
     return `category${category.charAt(0).toUpperCase() + category.slice(1)}`;
 }
@@ -82,6 +84,66 @@ function buildUnknownArgumentsMessage(toolName, unknownArgumentNames, expectedAr
     const correction = unknownArgumentNames.length === 1 ? 'Remove it' : 'Remove them';
     return `Unknown ${unknownLabel} for tool "${toolName}": ${formatArgumentNames(unknownArgumentNames)}. ${expectedArguments} ${correction} and retry.`;
 }
+async function validateAndResolvePathOrUrl(filePathOrUrl, context) {
+    try {
+        const url = new URL(filePathOrUrl);
+        if (url.protocol === 'file:') {
+            return pathToFileURL(await context.validatePath(fileURLToPath(url))).href;
+        }
+        else if (['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)) {
+            return filePathOrUrl;
+        }
+    }
+    catch {
+        // Suppress parsing errors for regular file paths.
+    }
+    return await context.validatePath(filePathOrUrl);
+}
+function isLocalBrowser(context) {
+    if (context.browser.process()) {
+        return true;
+    }
+    const wsEndpoint = context.browser.wsEndpoint();
+    if (wsEndpoint && isLocalhost(wsEndpoint)) {
+        return true;
+    }
+    return false;
+}
+function shouldValidateFile(option, isLocal) {
+    if (option === true) {
+        return true;
+    }
+    if (typeof option === 'object' && option !== null) {
+        if (isLocal) {
+            return Boolean(option.local);
+        }
+        return Boolean(option.remote);
+    }
+    return false;
+}
+async function validateToolFiles(tool, params, context) {
+    const isLocal = isLocalBrowser(context);
+    for (const [key, option] of Object.entries(tool.verifyFilesSchema)) {
+        if (shouldValidateFile(option, isLocal)) {
+            const val = params[key];
+            if (typeof val === 'string') {
+                params[key] = await validateAndResolvePathOrUrl(val, context);
+            }
+            else if (Array.isArray(val)) {
+                const updated = [];
+                for (const item of val) {
+                    if (typeof item === 'string') {
+                        updated.push(await validateAndResolvePathOrUrl(item, context));
+                    }
+                    else {
+                        throw new Error('Unexpected non-string value as a file path or URL');
+                    }
+                }
+                params[key] = updated;
+            }
+        }
+    }
+}
 export class ToolHandler {
     tool;
     serverArgs;
@@ -102,7 +164,7 @@ export class ToolHandler {
         this.inputSchema =
             'pageScoped' in tool &&
                 tool.pageScoped &&
-                serverArgs.experimentalPageIdRouting &&
+                serverArgs.pageIdRouting &&
                 !serverArgs.slim
                 ? { ...pageIdSchema, ...tool.schema }
                 : tool.schema;
@@ -153,19 +215,11 @@ export class ToolHandler {
             }
             let page;
             try {
-                if (this.tool.verifyFilesSchema) {
-                    for (const key of this.tool.verifyFilesSchema) {
-                        const filePath = params[key];
-                        const paths = Array.isArray(filePath) ? filePath : [filePath];
-                        for (const path of paths) {
-                            await context.validatePath(path);
-                        }
-                    }
-                }
+                await validateToolFiles(this.tool, params, context);
                 if (isPageScopedTool(this.tool)) {
                     const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
                     page =
-                        this.serverArgs.experimentalPageIdRouting &&
+                        this.serverArgs.pageIdRouting &&
                             pageId !== undefined &&
                             !this.serverArgs.slim
                             ? context.getPageById(pageId)
@@ -189,10 +243,7 @@ export class ToolHandler {
                 response.setError(err);
             }
             devToolsData = await context.getDevToolsData(page);
-            const targetPage = page ?? context.getSelectedMcpPage();
-            if (targetPage?.pptrPage?.isClosed() === false) {
-                pageUrl = targetPage.pptrPage.url();
-            }
+            pageUrl = context.getSelectedMcpPageUrl(page);
             // Resolve data format: --experimentalDataFormat takes precedence, fall back to legacy --experimentalToonFormat
             let dataFormat = 'default';
             if (this.serverArgs.experimentalDataFormat) {

package/build/src/bin/brave-devtools-mcp-main.js

@@ -13,7 +13,7 @@ import { StdioServerTransport } from '../third_party/index.js';
 import { checkForUpdates } from '../utils/check-for-updates.js';
 import { logger, saveLogsToFile } from '../utils/logger.js';
 import { VERSION } from '../version.js';
-import { cliOptions, parseArguments } from './brave-devtools-mcp-cli-options.js';
+import { mcpOptions, parseArguments } from '../config/mcp-options.js';
 await checkForUpdates('Run `npm install brave-mcp@latest` to update.');
 export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
@@ -68,5 +68,5 @@ await server.connect(transport);
 logger?.('Brave DevTools MCP Server connected');
 logDisclaimers(args);
 void ClearcutLogger.get()?.logDailyActiveIfNeeded();
-void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, cliOptions));
+void ClearcutLogger.get()?.logServerStart(computeFlagUsage(args, mcpOptions));
 //# sourceMappingURL=brave-devtools-mcp-main.js.map

package/build/src/bin/brave-devtools.js

@@ -12,34 +12,26 @@ import { logDisclaimers } from '../index.js';
 import { hideBin, yargs } from '../third_party/index.js';
 import { checkForUpdates } from '../utils/check-for-updates.js';
 import { VERSION } from '../version.js';
-import { commands } from './brave-devtools-cli-options.js';
-import { cliOptions, parseArguments } from './brave-devtools-mcp-cli-options.js';
+import { commands } from '../config/cli-options.js';
+import { mcpOptions, parseArguments, getMcpOptionsForViaCli, } from '../config/mcp-options.js';
 await checkForUpdates('Run `npm install -g brave-mcp@latest` and `brave-devtools start` to update and restart the daemon.');
+const DEFAULT_CLI_ARGS = ['--viaCli'];
 async function start(args, sessionId) {
-    const combinedArgs = [...args, ...defaultArgs];
+    const combinedArgs = [...DEFAULT_CLI_ARGS, ...args];
     await startDaemon(combinedArgs, sessionId);
     logDisclaimers(parseArguments(VERSION, combinedArgs));
 }
-const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
-const startCliOptions = {
-    ...cliOptions,
-};
-// Missing CLI serialization.
-delete startCliOptions.viewport;
-// Change the defaults for the CLI.
-delete startCliOptions.experimentalStructuredContent;
-delete startCliOptions.experimentalInteropTools;
-delete startCliOptions.experimentalPageIdRouting;
-if (!('default' in cliOptions.headless)) {
-    throw new Error('headless cli option unexpectedly does not have a default');
+function getCliOptions() {
+    const options = {
+        ...getMcpOptionsForViaCli(),
+    };
+    // Missing CLI serialization.
+    delete options.viewport;
+    // Change the defaults for the CLI.
+    delete options.experimentalStructuredContent;
+    delete options.experimentalInteropTools;
+    return options;
 }
-if ('default' in cliOptions.isolated) {
-    throw new Error('isolated cli option unexpectedly has a default');
-}
-startCliOptions.headless.default = true;
-startCliOptions.isolated.description =
-    'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to true unless userDataDir is provided.';
-startCliOptions.categoryExtensions.default = true;
 const y = yargs(hideBin(process.argv))
     .locale('en') // Force English to ensure error string matching works in .fail, all custom messages we output are in English anyways
     .scriptName('brave-devtools')
@@ -71,9 +63,9 @@ const y = yargs(hideBin(process.argv))
             console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
             console.error('In the `brave-devtools` CLI:');
             console.error('1. Required parameters MUST be passed as positional arguments (without flags).');
-            console.error('   - INCORRECT: brave-devtools evaluate_script --expression "() => document.title"');
-            console.error('   - CORRECT:   brave-devtools evaluate_script "() => document.title"');
-            console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --pageId 1).');
+            console.error('   - INCORRECT: brave-devtools click --pageId 1 --uid "1_2"');
+            console.error('   - CORRECT:   brave-devtools click 1 "1_2"');
+            console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --dblClick true).');
             console.error('3. Make sure to escape quotes properly for your shell environment.');
             console.error('Run `brave-devtools <command> --help` to see exact positional and optional parameters.');
             console.error('=========================================');
@@ -85,7 +77,7 @@ const y = yargs(hideBin(process.argv))
     process.exit(1);
 });
 y.command('start', 'Start or restart brave-devtools-mcp', y => y
-    .options(startCliOptions)
+    .options(getCliOptions())
     .example('$0 start --browserUrl http://localhost:9222', 'Start the server connecting to an existing browser')
     .strict(), async (argv) => {
     if (isDaemonRunning(argv.sessionId)) {
@@ -106,7 +98,7 @@ y.command('start', 'Start or restart brave-devtools-mcp', y => y
             argv.headless = true;
         }
     }
-    const args = serializeArgs(cliOptions, argv);
+    const args = serializeArgs(mcpOptions, argv);
     await start(args, argv.sessionId);
     process.exit(0);
 }).strict(); // Re-enable strict validation for other commands; this is applied to the yargs instance itself
@@ -200,7 +192,7 @@ for (const [commandName, commandDef] of Object.entries(commands)) {
                 ? verifyDaemonVersion(sessionId, VERSION)
                 : Promise.resolve(undefined);
             if (!isDaemonRunning(sessionId)) {
-                await start(serializeArgs(cliOptions, argv), sessionId);
+                await start(serializeArgs(mcpOptions, argv), sessionId);
             }
             const commandArgs = {};
             for (const argName of Object.keys(args)) {

package/build/src/browser.js

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { puppeteer } from './third_party/index.js';
-import { logger } from './utils/logger.js';
+import { logger, puppeteerLogger } from './utils/logger.js';
 let browser;
 let browserMode;
 // Heavy pages (e.g. Studio module dev bundles >100MB) cannot ack
@@ -161,6 +161,7 @@ export async function ensureBrowserConnected(options) {
         protocolTimeout: PROTOCOL_TIMEOUT_MILLISECONDS,
         blocklist: options.blocklist,
         allowlist: options.allowlist,
+        logger: puppeteerLogger,
     };
     let autoConnect = false;
     if (options.wsEndpoint) {
@@ -281,6 +282,7 @@ export async function launch(options) {
             protocolTimeout: PROTOCOL_TIMEOUT_MILLISECONDS,
             blocklist: options.blocklist,
             allowlist: options.allowlist,
+            logger: puppeteerLogger,
         });
         if (options.logFile) {
             // FIXME: we are probably subscribing too late to catch startup logs. We

package/build/src/{PageCollector.js → collectors/PageCollector.js}

@@ -3,10 +3,10 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { FakeIssuesManager } from './devtools/DevtoolsUtils.js';
-import { DevTools } from './third_party/index.js';
-import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
-import { logger } from './utils/logger.js';
+import { FakeIssuesManager } from '../devtools/DevtoolsUtils.js';
+import { DevTools } from '../third_party/index.js';
+import { createIdGenerator, stableIdSymbol, } from '../utils/id.js';
+import { logger } from '../utils/logger.js';
 export class UncaughtError {
     details;
     targetId;

package/build/src/{ServiceWorkerCollector.js → collectors/ServiceWorkerCollector.js}

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { UncaughtError } from './PageCollector.js';
-import { createIdGenerator, stableIdSymbol } from './utils/id.js';
+import { createIdGenerator, stableIdSymbol } from '../utils/id.js';
 const CHROME_EXTENSION_PREFIX = 'chrome-extension://';
 export class ServiceWorkerSubscriber {
     #target;