brave-mcp 0.1.2 → 0.2.0

package/README.md

@@ -8,6 +8,7 @@
 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
 DevTools for reliable automation, in-depth debugging, and performance analysis.
+A [CLI](docs/cli.md) is also provided for use without MCP.
 
 ## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
 
@@ -692,6 +693,10 @@ The Brave DevTools MCP server supports the following configuration options:
   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
 
+- **`--experimentalWebmcp`/ `--experimental-webmcp`**
+  Set to true to enable debugging WebMCP tools. Requires Chrome 149+ 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.
   - **Type:** array
@@ -729,6 +734,11 @@ The Brave DevTools MCP server supports the following configuration options:
   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.
+  - **Type:** boolean
+  - **Default:** `false`
+
 <!-- END AUTO GENERATED OPTIONS -->
 
 Pass them via the `args` property in the JSON configuration. For example:

package/build/src/McpContext.js

@@ -13,7 +13,7 @@ import { PredefinedNetworkConditions } from './third_party/index.js';
 import { listPages } from './tools/pages.js';
 import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
 import { ExtensionRegistry, } from './utils/ExtensionRegistry.js';
-import { saveTemporaryFile } from './utils/files.js';
+import { ensureExtension, saveTemporaryFile } from './utils/files.js';
 import { getNetworkMultiplierFromString } from './WaitForHelper.js';
 const DEFAULT_TIMEOUT = 5_000;
 const NAVIGATION_TIMEOUT = 10_000;
@@ -56,7 +56,7 @@ export class McpContext {
                 uncaughtError: event => {
                     collect(event);
                 },
-                issue: event => {
+                devtoolsAggregatedIssue: event => {
                     collect(event);
                 },
             };
@@ -590,9 +590,9 @@ export class McpContext {
     async saveTemporaryFile(data, filename) {
         return await saveTemporaryFile(data, filename);
     }
-    async saveFile(data, filename) {
+    async saveFile(data, clientProvidedFilePath, extension) {
         try {
-            const filePath = path.resolve(filename);
+            const filePath = ensureExtension(path.resolve(clientProvidedFilePath), extension);
             await fs.mkdir(path.dirname(filePath), { recursive: true });
             await fs.writeFile(filePath, data);
             return { filename: filePath };

package/build/src/McpPage.js

@@ -48,6 +48,9 @@ export class McpPage {
     getInPageTools() {
         return this.inPageTools;
     }
+    getWebMcpTools() {
+        return this.pptrPage.webmcp.tools();
+    }
     get networkConditions() {
         return this.emulationSettings.networkConditions ?? null;
     }

package/build/src/McpResponse.js

@@ -122,16 +122,21 @@ export class McpResponse {
     #consoleDataOptions;
     #listExtensions;
     #listInPageTools;
+    #listWebMcpTools;
     #devToolsData;
     #tabId;
     #args;
     #page;
+    #redactNetworkHeaders = true;
     constructor(args) {
         this.#args = args;
     }
     setPage(page) {
         this.#page = page;
     }
+    setRedactNetworkHeaders(value) {
+        this.#redactNetworkHeaders = value;
+    }
     attachDevToolsData(data) {
         this.#devToolsData = data;
     }
@@ -158,6 +163,9 @@ export class McpResponse {
             this.#listInPageTools = true;
         }
     }
+    setListWebMcpTools() {
+        this.#listWebMcpTools = true;
+    }
     setIncludeNetworkRequests(value, options) {
         if (!value) {
             this.#networkRequestsOptions = undefined;
@@ -258,6 +266,9 @@ export class McpResponse {
     get snapshotParams() {
         return this.#snapshotParams;
     }
+    get listWebMcpTools() {
+        return this.#listWebMcpTools;
+    }
     async handle(toolName, context) {
         if (this.#includePages) {
             await context.createPagesSnapshot();
@@ -275,8 +286,8 @@ export class McpResponse {
             if (textSnapshot) {
                 const formatter = new SnapshotFormatter(textSnapshot);
                 if (this.#snapshotParams.filePath) {
-                    await context.saveFile(new TextEncoder().encode(formatter.toString()), this.#snapshotParams.filePath);
-                    snapshot = this.#snapshotParams.filePath;
+                    const result = await context.saveFile(new TextEncoder().encode(formatter.toString()), this.#snapshotParams.filePath, '.txt');
+                    snapshot = result.filename;
                 }
                 else {
                     snapshot = formatter;
@@ -295,7 +306,8 @@ export class McpResponse {
                 fetchData: true,
                 requestFilePath: this.#attachedNetworkRequestOptions?.requestFilePath,
                 responseFilePath: this.#attachedNetworkRequestOptions?.responseFilePath,
-                saveFile: (data, filename) => context.saveFile(data, filename),
+                saveFile: (data, filename, extension) => context.saveFile(data, filename, extension),
+                redactNetworkHeaders: this.#redactNetworkHeaders,
             });
             detailedNetworkRequest = formatter;
         }
@@ -337,6 +349,11 @@ export class McpResponse {
             inPageTools = await getToolGroup(page);
             page.inPageTools = inPageTools;
         }
+        let webmcpTools;
+        if (this.#listWebMcpTools && this.#args.experimentalWebmcp) {
+            const page = this.#page ?? context.getSelectedMcpPage();
+            webmcpTools = page.getWebMcpTools();
+        }
         let consoleMessages;
         if (this.#consoleDataOptions?.include) {
             if (!this.#page) {
@@ -399,7 +416,8 @@ export class McpResponse {
                     selectedInDevToolsUI: context.getNetworkRequestStableId(request) ===
                         this.#networkRequestsOptions?.networkRequestIdInDevToolsUI,
                     fetchData: false,
-                    saveFile: (data, filename) => context.saveFile(data, filename),
+                    saveFile: (data, filename, extension) => context.saveFile(data, filename, extension),
+                    redactNetworkHeaders: this.#redactNetworkHeaders,
                 })));
             }
         }
@@ -414,6 +432,7 @@ export class McpResponse {
             extensions,
             lighthouseResult: this.#attachedLighthouseResult,
             inPageTools,
+            webmcpTools,
         });
     }
     format(toolName, context, data) {
@@ -622,6 +641,26 @@ Call ${handleDialog.name} to handle it before continuing.`);
                 response.push(toolDefinitionsMessage);
             }
         }
+        if (this.#listWebMcpTools && data.webmcpTools) {
+            structuredContent.webmcpTools = data.webmcpTools.map(({ name, description, inputSchema, annotations }) => ({
+                name,
+                description,
+                inputSchema,
+                annotations,
+            }));
+            response.push('## WebMCP tools');
+            if (data.webmcpTools.length === 0) {
+                response.push('No WebMCP tools available.');
+            }
+            else {
+                const webmcpToolsMessage = data.webmcpTools
+                    .map(tool => {
+                    return `name="${tool.name}", description="${tool.description}", inputSchema=${JSON.stringify(tool.inputSchema)}, annotations=${JSON.stringify(tool.annotations)}`;
+                })
+                    .join('\n');
+                response.push(webmcpToolsMessage);
+            }
+        }
         if (this.#networkRequestsOptions?.include && data.networkRequests) {
             const requests = data.networkRequests;
             response.push('## Network requests');

package/build/src/PageCollector.js

@@ -206,7 +206,7 @@ class PageEventSubscriber {
     async subscribe() {
         this.#resetIssueAggregator();
         this.#page.on('framenavigated', this.#onFrameNavigated);
-        this.#session.on('Audits.issueAdded', this.#onIssueAdded);
+        this.#page.on('issue', this.#onIssueAdded);
         this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
         try {
             await this.#session.send('Audits.enable');
@@ -219,7 +219,7 @@ class PageEventSubscriber {
         this.#seenKeys.clear();
         this.#seenIssues.clear();
         this.#page.off('framenavigated', this.#onFrameNavigated);
-        this.#session.off('Audits.issueAdded', this.#onIssueAdded);
+        this.#page.off('issue', this.#onIssueAdded);
         this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
         if (this.#issueAggregator) {
             this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
@@ -233,7 +233,7 @@ class PageEventSubscriber {
             return;
         }
         this.#seenIssues.add(event.data);
-        this.#page.emit('issue', event.data);
+        this.#page.emit('devtoolsAggregatedIssue', event.data);
     };
     #onExceptionThrown = (event) => {
         this.#page.emit('uncaughtError', new UncaughtError(event.exceptionDetails, this.#targetId));
@@ -248,9 +248,8 @@ class PageEventSubscriber {
         this.#seenIssues.clear();
         this.#resetIssueAggregator();
     };
-    #onIssueAdded = (data) => {
+    #onIssueAdded = (inspectorIssue) => {
         try {
-            const inspectorIssue = data.issue;
             const issue = DevTools.createIssuesFromProtocolIssue(null, 
             // @ts-expect-error Protocol types diverge.
             inspectorIssue)[0];

package/build/src/bin/brave-devtools-mcp-cli-options.js

@@ -168,6 +168,10 @@ export const cliOptions = {
         type: 'boolean',
         describe: 'Exposes experimental screencast tools (requires ffmpeg). Install ffmpeg https://www.ffmpeg.org/download.html and ensure it is available in the MCP server PATH.',
     },
+    experimentalWebmcp: {
+        type: 'boolean',
+        describe: 'Set to true to enable debugging WebMCP tools. Requires Brave with the following flags: `--enable-features=WebMCPTesting,DevToolsWebMCPSupport`',
+    },
     braveArg: {
         type: 'array',
         describe: 'Additional arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.',
@@ -236,6 +240,11 @@ export const cliOptions = {
         describe: 'Set by Brave DevTools CLI if the MCP server is started via the CLI client (this arg exists for usage stats)',
         hidden: true,
     },
+    redactNetworkHeaders: {
+        type: 'boolean',
+        describe: 'If true, redacts some of the network headers considered senstive before returning to the client.',
+        default: false,
+    },
 };
 export function parseArguments(version, argv = process.argv) {
     const yargsInstance = yargs(hideBin(argv))

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

@@ -32,6 +32,7 @@ delete startCliOptions.viewport;
 // tools, they need to be enabled during CLI generation.
 delete startCliOptions.experimentalPageIdRouting;
 delete startCliOptions.experimentalVision;
+delete startCliOptions.experimentalWebmcp;
 delete startCliOptions.experimentalInteropTools;
 delete startCliOptions.experimentalScreencast;
 delete startCliOptions.categoryEmulation;

package/build/src/formatters/NetworkFormatter.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  * */
 import { isUtf8 } from 'node:buffer';
+import { DevTools, } from '../third_party/index.js';
 const BODY_CONTEXT_SIZE_LIMIT = 10000;
 export class NetworkFormatter {
     #request;
@@ -40,8 +41,8 @@ export class NetworkFormatter {
                     throw new Error('saveFile is not provided');
                 }
                 if (data) {
-                    await this.#options.saveFile(Buffer.from(data), this.#options.requestFilePath);
-                    this.#requestBodyFilePath = this.#options.requestFilePath;
+                    const result = await this.#options.saveFile(Buffer.from(data), this.#options.requestFilePath, '.network-request');
+                    this.#requestBodyFilePath = result.filename;
                 }
                 else {
                     this.#requestBody = requestBodyNotAvailableMessage;
@@ -66,8 +67,8 @@ export class NetworkFormatter {
                     if (!this.#options.saveFile) {
                         throw new Error('saveFile is not provided');
                     }
-                    await this.#options.saveFile(buffer, this.#options.responseFilePath);
-                    this.#responseBodyFilePath = this.#options.responseFilePath;
+                    const result = await this.#options.saveFile(buffer, this.#options.responseFilePath, '.network-response');
+                    this.#responseBodyFilePath = result.filename;
                 }
                 catch {
                     // Flatten error handling for buffer() failure and save failure
@@ -96,6 +97,16 @@ export class NetworkFormatter {
             selectedInDevToolsUI: this.#options.selectedInDevToolsUI,
         };
     }
+    #redactNetworkHeaders(headers) {
+        const headersList = Object.entries(headers).map(item => {
+            return { name: item[0], value: item[1] };
+        });
+        const redacted = DevTools.NetworkRequestFormatter.sanitizeHeaders(headersList);
+        return redacted.reduce((acc, item) => {
+            acc[item.name] = item.value;
+            return acc;
+        }, {});
+    }
     toJSONDetailed() {
         const redirectChain = this.#request.redirectChain();
         const formattedRedirectChain = redirectChain.reverse().map(request => {
@@ -105,15 +116,21 @@ export class NetworkFormatter {
             const formatter = new NetworkFormatter(request, {
                 requestId: id,
                 saveFile: this.#options.saveFile,
+                redactNetworkHeaders: this.#options.redactNetworkHeaders,
             });
             return formatter.toJSON();
         });
+        const responseHeaders = this.#request.response()?.headers();
         return {
             ...this.toJSON(),
-            requestHeaders: this.#request.headers(),
+            requestHeaders: this.#options.redactNetworkHeaders
+                ? this.#redactNetworkHeaders(this.#request.headers())
+                : this.#request.headers(),
             requestBody: this.#requestBody,
             requestBodyFilePath: this.#requestBodyFilePath,
-            responseHeaders: this.#request.response()?.headers(),
+            responseHeaders: this.#options.redactNetworkHeaders && responseHeaders
+                ? this.#redactNetworkHeaders(responseHeaders)
+                : this.#request.response()?.headers(),
             responseBody: this.#responseBody,
             responseBodyFilePath: this.#responseBodyFilePath,
             failure: this.#request.failure()?.errorText,

package/build/src/index.js

@@ -119,6 +119,10 @@ export async function createMcpServer(serverArgs, options) {
             !serverArgs.experimentalScreencast) {
             return;
         }
+        if (tool.annotations.conditions?.includes('experimentalWebmcp') &&
+            !serverArgs.experimentalWebmcp) {
+            return;
+        }
         const schema = 'pageScoped' in tool &&
             tool.pageScoped &&
             serverArgs.experimentalPageIdRouting &&
@@ -141,6 +145,7 @@ export async function createMcpServer(serverArgs, options) {
                 const response = serverArgs.slim
                     ? new SlimMcpResponse(serverArgs)
                     : new McpResponse(serverArgs);
+                response.setRedactNetworkHeaders(serverArgs.redactNetworkHeaders);
                 if ('pageScoped' in tool && tool.pageScoped) {
                     const page = serverArgs.experimentalPageIdRouting &&
                         params.pageId &&
@@ -189,6 +194,8 @@ export async function createMcpServer(serverArgs, options) {
             finally {
                 void clearcutLogger?.logToolInvocation({
                     toolName: tool.name,
+                    params,
+                    schema,
                     success,
                     latencyMs: bucketizeLatency(Date.now() - startTime),
                 });

package/build/src/telemetry/ClearcutLogger.js

@@ -38,14 +38,15 @@ export function getZodType(zodType) {
     throw new Error(`Unsupported zod type for tool parameter: ${typeName}`);
 }
 export function transformArgName(zodType, name) {
+    const snakeCaseName = name.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`);
     if (zodType === 'ZodString') {
-        return `${name}_length`;
+        return `${snakeCaseName}_length`;
     }
     else if (zodType === 'ZodArray') {
-        return `${name}_count`;
+        return `${snakeCaseName}_count`;
     }
     else {
-        return name;
+        return snakeCaseName;
     }
 }
 export function transformArgType(zodType) {
@@ -168,15 +169,21 @@ export class ClearcutLogger {
         }
     }
     async logToolInvocation(args) {
+        const tool_invocation = {
+            tool_name: args.toolName,
+            success: args.success,
+            latency_ms: args.latencyMs,
+        };
+        if (Object.keys(args.params).length > 0) {
+            tool_invocation.tool_params = {
+                [`${args.toolName}_params`]: sanitizeParams(args.params, args.schema),
+            };
+        }
         this.#watchdog.send({
             type: WatchdogMessageType.LOG_EVENT,
             payload: {
                 mcp_client: this.#mcpClient,
-                tool_invocation: {
-                    tool_name: args.toolName,
-                    success: args.success,
-                    latency_ms: args.latencyMs,
-                },
+                tool_invocation: tool_invocation,
             },
         });
     }

package/build/src/telemetry/watchdog/ClearcutSender.js

@@ -42,13 +42,14 @@ export class ClearcutSender {
             this.#sessionId = crypto.randomUUID();
             this.#sessionCreated = Date.now();
         }
-        logger('Enqueing telemetry event', JSON.stringify(event, null, 2));
-        this.#addToBuffer({
+        const eventToSend = {
             ...event,
             session_id: this.#sessionId,
             app_version: this.#appVersion,
             os_type: this.#osType,
-        });
+        };
+        logger('Enqueing telemetry event', JSON.stringify(eventToSend, null, 2));
+        this.#addToBuffer(eventToSend);
         if (!this.#timerStarted) {
             this.#timerStarted = true;
             this.#scheduleFlush(this.#flushIntervalMs);