brave-mcp 0.1.0

package/build/src/formatters/NetworkFormatter.js

@@ -0,0 +1,218 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * */
+import { isUtf8 } from 'node:buffer';
+const BODY_CONTEXT_SIZE_LIMIT = 10000;
+export class NetworkFormatter {
+    #request;
+    #options;
+    #requestBody;
+    #responseBody;
+    #requestBodyFilePath;
+    #responseBodyFilePath;
+    constructor(request, options) {
+        this.#request = request;
+        this.#options = options;
+    }
+    static async from(request, options) {
+        const instance = new NetworkFormatter(request, options);
+        if (options.fetchData) {
+            await instance.#loadDetailedData();
+        }
+        return instance;
+    }
+    async #loadDetailedData() {
+        // Load Request Body
+        if (this.#request.hasPostData()) {
+            let data;
+            try {
+                data =
+                    this.#request.postData() ?? (await this.#request.fetchPostData());
+            }
+            catch {
+                // Ignore parsing errors
+            }
+            const requestBodyNotAvailableMessage = '<Request body not available anymore>';
+            if (this.#options.requestFilePath) {
+                if (!this.#options.saveFile) {
+                    throw new Error('saveFile is not provided');
+                }
+                if (data) {
+                    await this.#options.saveFile(Buffer.from(data), this.#options.requestFilePath);
+                    this.#requestBodyFilePath = this.#options.requestFilePath;
+                }
+                else {
+                    this.#requestBody = requestBodyNotAvailableMessage;
+                }
+            }
+            else {
+                if (data) {
+                    this.#requestBody = getSizeLimitedString(data, BODY_CONTEXT_SIZE_LIMIT);
+                }
+                else {
+                    this.#requestBody = requestBodyNotAvailableMessage;
+                }
+            }
+        }
+        // Load Response Body
+        const response = this.#request.response();
+        if (response) {
+            const responseBodyNotAvailableMessage = '<Response body not available anymore>';
+            if (this.#options.responseFilePath) {
+                try {
+                    const buffer = await response.buffer();
+                    if (!this.#options.saveFile) {
+                        throw new Error('saveFile is not provided');
+                    }
+                    await this.#options.saveFile(buffer, this.#options.responseFilePath);
+                    this.#responseBodyFilePath = this.#options.responseFilePath;
+                }
+                catch {
+                    // Flatten error handling for buffer() failure and save failure
+                }
+                if (!this.#responseBodyFilePath) {
+                    this.#responseBody = responseBodyNotAvailableMessage;
+                }
+            }
+            else {
+                this.#responseBody = await this.#getFormattedResponseBody(response, BODY_CONTEXT_SIZE_LIMIT);
+            }
+        }
+    }
+    toString() {
+        return convertNetworkRequestConciseToString(this.toJSON());
+    }
+    toStringDetailed() {
+        return converNetworkRequestDetailedToStringDetailed(this.toJSONDetailed());
+    }
+    toJSON() {
+        return {
+            requestId: this.#options.requestId,
+            method: this.#request.method(),
+            url: this.#request.url(),
+            status: this.#getStatusFromRequest(this.#request),
+            selectedInDevToolsUI: this.#options.selectedInDevToolsUI,
+        };
+    }
+    toJSONDetailed() {
+        const redirectChain = this.#request.redirectChain();
+        const formattedRedirectChain = redirectChain.reverse().map(request => {
+            const id = this.#options.requestIdResolver
+                ? this.#options.requestIdResolver(request)
+                : undefined;
+            const formatter = new NetworkFormatter(request, {
+                requestId: id,
+                saveFile: this.#options.saveFile,
+            });
+            return formatter.toJSON();
+        });
+        return {
+            ...this.toJSON(),
+            requestHeaders: this.#request.headers(),
+            requestBody: this.#requestBody,
+            requestBodyFilePath: this.#requestBodyFilePath,
+            responseHeaders: this.#request.response()?.headers(),
+            responseBody: this.#responseBody,
+            responseBodyFilePath: this.#responseBodyFilePath,
+            failure: this.#request.failure()?.errorText,
+            redirectChain: formattedRedirectChain.length
+                ? formattedRedirectChain
+                : undefined,
+        };
+    }
+    #getStatusFromRequest(request) {
+        const httpResponse = request.response();
+        const failure = request.failure();
+        let status;
+        if (httpResponse) {
+            status = httpResponse.status().toString();
+        }
+        else if (failure) {
+            status = failure.errorText;
+        }
+        else {
+            status = 'pending';
+        }
+        return status;
+    }
+    async #getFormattedResponseBody(httpResponse, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
+        try {
+            const responseBuffer = await httpResponse.buffer();
+            if (isUtf8(responseBuffer)) {
+                const responseAsTest = responseBuffer.toString('utf-8');
+                if (responseAsTest.length === 0) {
+                    return '<empty response>';
+                }
+                return getSizeLimitedString(responseAsTest, sizeLimit);
+            }
+            return '<binary data>';
+        }
+        catch {
+            return '<not available anymore>';
+        }
+    }
+}
+function getSizeLimitedString(text, sizeLimit) {
+    if (text.length > sizeLimit) {
+        return text.substring(0, sizeLimit) + '... <truncated>';
+    }
+    return text;
+}
+function convertNetworkRequestConciseToString(data) {
+    // TODO truncate the URL
+    return `reqid=${data.requestId} ${data.method} ${data.url} [${data.status}]${data.selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
+}
+function formatHeadlers(headers) {
+    const response = [];
+    for (const [name, value] of Object.entries(headers)) {
+        response.push(`- ${name}:${value}`);
+    }
+    return response;
+}
+function converNetworkRequestDetailedToStringDetailed(data) {
+    const response = [];
+    response.push(`## Request ${data.url}`);
+    response.push(`Status: ${data.status}`);
+    response.push(`### Request Headers`);
+    for (const line of formatHeadlers(data.requestHeaders)) {
+        response.push(line);
+    }
+    if (data.requestBody) {
+        response.push(`### Request Body`);
+        response.push(data.requestBody);
+    }
+    else if (data.requestBodyFilePath) {
+        response.push(`### Request Body`);
+        response.push(`Saved to ${data.requestBodyFilePath}.`);
+    }
+    if (data.responseHeaders) {
+        response.push(`### Response Headers`);
+        for (const line of formatHeadlers(data.responseHeaders)) {
+            response.push(line);
+        }
+    }
+    if (data.responseBody) {
+        response.push(`### Response Body`);
+        response.push(data.responseBody);
+    }
+    else if (data.responseBodyFilePath) {
+        response.push(`### Response Body`);
+        response.push(`Saved to ${data.responseBodyFilePath}.`);
+    }
+    if (data.failure) {
+        response.push(`### Request failed with`);
+        response.push(data.failure);
+    }
+    const redirectChain = data.redirectChain;
+    if (redirectChain?.length) {
+        response.push(`### Redirect chain`);
+        let indent = 0;
+        for (const request of redirectChain.reverse()) {
+            response.push(`${'  '.repeat(indent)}${convertNetworkRequestConciseToString(request)})}`);
+            indent++;
+        }
+    }
+    return response.join('\n');
+}

package/build/src/formatters/SnapshotFormatter.js

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class SnapshotFormatter {
+    #snapshot;
+    constructor(snapshot) {
+        this.#snapshot = snapshot;
+    }
+    toString() {
+        const chunks = [];
+        const root = this.#snapshot.root;
+        // Top-level content of the snapshot.
+        if (this.#snapshot.verbose &&
+            this.#snapshot.hasSelectedElement &&
+            !this.#snapshot.selectedElementUid) {
+            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+        }
+        chunks.push(this.#formatNode(root, 0));
+        return chunks.join('');
+    }
+    toJSON() {
+        return this.#nodeToJSON(this.#snapshot.root);
+    }
+    #formatNode(node, depth = 0) {
+        const chunks = [];
+        const attributes = this.#getAttributes(node);
+        const line = ' '.repeat(depth * 2) +
+            attributes.join(' ') +
+            (node.id === this.#snapshot.selectedElementUid
+                ? ' [selected in the DevTools Elements panel]'
+                : '') +
+            '\n';
+        chunks.push(line);
+        for (const child of node.children) {
+            chunks.push(this.#formatNode(child, depth + 1));
+        }
+        return chunks.join('');
+    }
+    #nodeToJSON(node) {
+        const rawAttrs = this.#getAttributesMap(node);
+        const children = node.children.map(child => this.#nodeToJSON(child));
+        const result = structuredClone(rawAttrs);
+        if (children.length > 0) {
+            result.children = children;
+        }
+        return result;
+    }
+    #getAttributes(serializedAXNodeRoot) {
+        const attributes = [`uid=${serializedAXNodeRoot.id}`];
+        if (serializedAXNodeRoot.role) {
+            attributes.push(serializedAXNodeRoot.role === 'none'
+                ? 'ignored'
+                : serializedAXNodeRoot.role);
+        }
+        if (serializedAXNodeRoot.name) {
+            attributes.push(`"${serializedAXNodeRoot.name}"`);
+        }
+        const simpleAttrs = this.#getAttributesMap(serializedAXNodeRoot, 
+        /* excludeSpecial */ true);
+        for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const mapped = booleanPropertyMap[attr];
+            if (mapped && simpleAttrs[mapped]) {
+                attributes.push(mapped);
+            }
+            const val = simpleAttrs[attr];
+            if (val === true) {
+                attributes.push(attr);
+            }
+            else if (typeof val === 'string' || typeof val === 'number') {
+                attributes.push(`${attr}="${val}"`);
+            }
+        }
+        return attributes;
+    }
+    #getAttributesMap(node, excludeSpecial = false) {
+        const result = {};
+        if (!excludeSpecial) {
+            result.id = node.id;
+            if (node.role) {
+                result.role = node.role;
+            }
+            if (node.name) {
+                result.name = node.name;
+            }
+        }
+        // Re-implementing the exact logic from original function for #getAttributes to be safe:
+        return {
+            ...result,
+            ...this.#extractedAttributes(node),
+        };
+    }
+    #extractedAttributes(node) {
+        const result = {};
+        for (const attr of Object.keys(node).sort()) {
+            if (excludedAttributes.has(attr)) {
+                continue;
+            }
+            const value = node[attr];
+            if (typeof value === 'boolean') {
+                if (booleanPropertyMap[attr]) {
+                    result[booleanPropertyMap[attr]] = true;
+                }
+                if (value) {
+                    result[attr] = true;
+                }
+            }
+            else if (typeof value === 'string' || typeof value === 'number') {
+                result[attr] = value;
+            }
+        }
+        return result;
+    }
+}
+const booleanPropertyMap = {
+    disabled: 'disableable',
+    expanded: 'expandable',
+    focused: 'focusable',
+    selected: 'selectable',
+};
+const excludedAttributes = new Set([
+    'id',
+    'role',
+    'name',
+    'elementHandle',
+    'children',
+    'backendNodeId',
+    'loaderId',
+]);

package/build/src/index.js

@@ -0,0 +1,216 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ensureBrowserConnected, ensureBrowserLaunched } from './browser.js';
+import { loadIssueDescriptions } from './issue-descriptions.js';
+import { logger } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import { SlimMcpResponse } from './SlimMcpResponse.js';
+import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
+import { bucketizeLatency } from './telemetry/metricUtils.js';
+import { McpServer, SetLevelRequestSchema, } from './third_party/index.js';
+import { ToolCategory } from './tools/categories.js';
+import { pageIdSchema } from './tools/ToolDefinition.js';
+import { createTools } from './tools/tools.js';
+import { VERSION } from './version.js';
+export async function createMcpServer(serverArgs, options) {
+    let clearcutLogger;
+    if (serverArgs.usageStatistics) {
+        clearcutLogger = new ClearcutLogger({
+            logFile: serverArgs.logFile,
+            appVersion: VERSION,
+            clearcutEndpoint: serverArgs.clearcutEndpoint,
+            clearcutForceFlushIntervalMs: serverArgs.clearcutForceFlushIntervalMs,
+            clearcutIncludePidHeader: serverArgs.clearcutIncludePidHeader,
+        });
+    }
+    const server = new McpServer({
+        name: 'brave_devtools',
+        title: 'Brave DevTools MCP server',
+        version: VERSION,
+    }, { capabilities: { logging: {} } });
+    server.server.setRequestHandler(SetLevelRequestSchema, () => {
+        return {};
+    });
+    server.server.oninitialized = () => {
+        const clientName = server.server.getClientVersion()?.name;
+        if (clientName) {
+            clearcutLogger?.setClientName(clientName);
+        }
+    };
+    let context;
+    async function getContext() {
+        const braveArgs = (serverArgs.braveArg ?? []).map(String);
+        const ignoreDefaultBraveArgs = (serverArgs.ignoreDefaultBraveArg ?? []).map(String);
+        if (serverArgs.proxyServer) {
+            braveArgs.push(`--proxy-server=${serverArgs.proxyServer}`);
+        }
+        const devtools = serverArgs.experimentalDevtools ?? false;
+        const browser = serverArgs.browserUrl || serverArgs.wsEndpoint || serverArgs.autoConnect
+            ? await ensureBrowserConnected({
+                browserURL: serverArgs.browserUrl,
+                wsEndpoint: serverArgs.wsEndpoint,
+                wsHeaders: serverArgs.wsHeaders,
+                channel: serverArgs.autoConnect
+                    ? serverArgs.channel
+                    : undefined,
+                userDataDir: serverArgs.userDataDir,
+                devtools,
+            })
+            : await ensureBrowserLaunched({
+                headless: serverArgs.headless,
+                executablePath: serverArgs.executablePath,
+                channel: serverArgs.channel,
+                isolated: serverArgs.isolated ?? false,
+                userDataDir: serverArgs.userDataDir,
+                logFile: options.logFile,
+                viewport: serverArgs.viewport,
+                braveArgs,
+                ignoreDefaultBraveArgs,
+                acceptInsecureCerts: serverArgs.acceptInsecureCerts,
+                devtools,
+                enableExtensions: serverArgs.categoryExtensions,
+                viaCli: serverArgs.viaCli,
+            });
+        if (context?.browser !== browser) {
+            context = await McpContext.from(browser, logger, {
+                experimentalDevToolsDebugging: devtools,
+                experimentalIncludeAllPages: serverArgs.experimentalIncludeAllPages,
+                performanceCrux: serverArgs.performanceCrux,
+            });
+        }
+        return context;
+    }
+    const toolMutex = new Mutex();
+    function registerTool(tool) {
+        if (tool.annotations.category === ToolCategory.EMULATION &&
+            serverArgs.categoryEmulation === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.PERFORMANCE &&
+            serverArgs.categoryPerformance === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.NETWORK &&
+            serverArgs.categoryNetwork === false) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.EXTENSIONS &&
+            !serverArgs.categoryExtensions) {
+            return;
+        }
+        if (tool.annotations.category === ToolCategory.IN_PAGE &&
+            !serverArgs.categoryInPageTools) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('computerVision') &&
+            !serverArgs.experimentalVision) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('experimentalInteropTools') &&
+            !serverArgs.experimentalInteropTools) {
+            return;
+        }
+        if (tool.annotations.conditions?.includes('screencast') &&
+            !serverArgs.experimentalScreencast) {
+            return;
+        }
+        const schema = 'pageScoped' in tool &&
+            tool.pageScoped &&
+            serverArgs.experimentalPageIdRouting &&
+            !serverArgs.slim
+            ? { ...tool.schema, ...pageIdSchema }
+            : tool.schema;
+        server.registerTool(tool.name, {
+            description: tool.description,
+            inputSchema: schema,
+            annotations: tool.annotations,
+        }, async (params) => {
+            const guard = await toolMutex.acquire();
+            const startTime = Date.now();
+            let success = false;
+            try {
+                logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+                const context = await getContext();
+                logger(`${tool.name} context: resolved`);
+                await context.detectOpenDevToolsWindows();
+                const response = serverArgs.slim
+                    ? new SlimMcpResponse(serverArgs)
+                    : new McpResponse(serverArgs);
+                if ('pageScoped' in tool && tool.pageScoped) {
+                    const page = serverArgs.experimentalPageIdRouting &&
+                        params.pageId &&
+                        !serverArgs.slim
+                        ? context.getPageById(params.pageId)
+                        : context.getSelectedMcpPage();
+                    response.setPage(page);
+                    await tool.handler({
+                        params,
+                        page,
+                    }, response, context);
+                }
+                else {
+                    await tool.handler(
+                    // @ts-expect-error types do not match.
+                    {
+                        params,
+                    }, response, context);
+                }
+                const { content, structuredContent } = await response.handle(tool.name, context);
+                const result = {
+                    content,
+                };
+                success = true;
+                if (serverArgs.experimentalStructuredContent) {
+                    result.structuredContent = structuredContent;
+                }
+                return result;
+            }
+            catch (err) {
+                logger(`${tool.name} error:`, err, err?.stack);
+                let errorText = err && 'message' in err ? err.message : String(err);
+                if ('cause' in err && err.cause) {
+                    errorText += `\nCause: ${err.cause.message}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            finally {
+                void clearcutLogger?.logToolInvocation({
+                    toolName: tool.name,
+                    success,
+                    latencyMs: bucketizeLatency(Date.now() - startTime),
+                });
+                guard.dispose();
+            }
+        });
+    }
+    const tools = createTools(serverArgs);
+    for (const tool of tools) {
+        registerTool(tool);
+    }
+    await loadIssueDescriptions();
+    return { server, clearcutLogger };
+}
+export const logDisclaimers = (args) => {
+    console.error(`brave-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+    if (!args.slim && args.performanceCrux) {
+        console.error(`Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data. To disable, run with --no-performance-crux.`);
+    }
+    if (!args.slim && args.usageStatistics) {
+        console.error(`Usage statistics are enabled. To opt-out, run with --no-usage-statistics.`);
+    }
+};

package/build/src/issue-descriptions.js

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, 'third_party/issue-descriptions');
+let issueDescriptions = {};
+/**
+ * Reads all issue descriptions from the filesystem into memory.
+ */
+export async function loadIssueDescriptions() {
+    if (Object.keys(issueDescriptions).length > 0) {
+        return;
+    }
+    const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
+    const descriptions = {};
+    for (const file of files) {
+        if (!file.endsWith('.md')) {
+            continue;
+        }
+        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        descriptions[file] = content;
+    }
+    issueDescriptions = descriptions;
+}
+/**
+ * Gets an issue description from the in-memory cache.
+ * @param fileName The file name of the issue description.
+ * @returns The description of the issue, or null if it doesn't exist.
+ */
+export function getIssueDescription(fileName) {
+    return issueDescriptions[fileName] ?? null;
+}
+export const ISSUE_UTILS = {
+    loadIssueDescriptions,
+    getIssueDescription,
+};

package/build/src/logger.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import { debug } from './third_party/index.js';
+const mcpDebugNamespace = 'mcp:log';
+const namespacesToEnable = [
+    mcpDebugNamespace,
+    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
+];
+export function saveLogsToFile(fileName) {
+    // Enable overrides everything so we need to add them
+    debug.enable(namespacesToEnable.join(','));
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
+    debug.log = function (...chunks) {
+        logFile.write(`${chunks.join(' ')}\n`);
+    };
+    logFile.on('error', function (error) {
+        console.error(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    return logFile;
+}
+export function flushLogs(logFile, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(reject, timeoutMs);
+        logFile.end(() => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+export const logger = debug(mcpDebugNamespace);

package/build/src/polyfill.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// polyfills are now bundled with all other dependencies
+import './third_party/index.js';