brave-mcp 0.1.0

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

@@ -0,0 +1,312 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { yargs, hideBin } from '../third_party/index.js';
+export const cliOptions = {
+    autoConnect: {
+        type: 'boolean',
+        description: '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.',
+        conflicts: ['isolated', 'executablePath', 'categoryExtensions'],
+        default: false,
+        coerce: (value) => {
+            if (!value) {
+                return;
+            }
+            return value;
+        },
+    },
+    browserUrl: {
+        type: 'string',
+        description: 'Connect to a running, debuggable Brave instance (e.g. `http://127.0.0.1:9222`).',
+        alias: 'u',
+        conflicts: ['wsEndpoint', 'categoryExtensions'],
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                new URL(url);
+            }
+            catch {
+                throw new Error(`Provided browserUrl ${url} is not valid URL.`);
+            }
+            return url;
+        },
+    },
+    wsEndpoint: {
+        type: 'string',
+        description: 'WebSocket endpoint to connect to a running Brave instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
+        alias: 'w',
+        conflicts: ['browserUrl', 'categoryExtensions'],
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+                    throw new Error(`Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`);
+                }
+                return url;
+            }
+            catch (error) {
+                if (error.message.includes('ws://')) {
+                    throw error;
+                }
+                throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
+            }
+        },
+    },
+    wsHeaders: {
+        type: 'string',
+        description: 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
+        implies: 'wsEndpoint',
+        coerce: (val) => {
+            if (!val) {
+                return;
+            }
+            try {
+                const parsed = JSON.parse(val);
+                if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+                    throw new Error('Headers must be a JSON object');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw new Error(`Invalid JSON for wsHeaders: ${error.message}`);
+            }
+        },
+    },
+    headless: {
+        type: 'boolean',
+        description: 'Whether to run in headless (no UI) mode.',
+        default: false,
+    },
+    executablePath: {
+        type: 'string',
+        description: 'Path to custom Brave executable. Can also be set via BRAVE_PATH environment variable.',
+        conflicts: ['browserUrl', 'wsEndpoint'],
+        alias: 'e',
+    },
+    isolated: {
+        type: 'boolean',
+        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',
+    },
+    userDataDir: {
+        type: 'string',
+        description: 'Path to the user data directory for Brave. Default is $HOME/.cache/brave-devtools-mcp/brave-profile$CHANNEL_SUFFIX_IF_NON_RELEASE',
+        conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
+    },
+    channel: {
+        type: 'string',
+        description: 'Specify a different Brave channel that should be used. The default is the release channel.',
+        choices: ['release', 'beta', 'nightly', 'dev'],
+        conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
+    },
+    logFile: {
+        type: 'string',
+        describe: 'Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.',
+    },
+    viewport: {
+        type: 'string',
+        describe: 'Initial viewport size for the Brave instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.',
+        coerce: (arg) => {
+            if (arg === undefined) {
+                return;
+            }
+            const [width, height] = arg.split('x').map(Number);
+            if (!width || !height || Number.isNaN(width) || Number.isNaN(height)) {
+                throw new Error('Invalid viewport. Expected format is `1280x720`.');
+            }
+            return {
+                width,
+                height,
+            };
+        },
+    },
+    proxyServer: {
+        type: 'string',
+        description: `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.`,
+    },
+    acceptInsecureCerts: {
+        type: 'boolean',
+        description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
+    },
+    experimentalPageIdRouting: {
+        type: 'boolean',
+        describe: 'Whether to expose pageId on page-scoped tools and route requests by page ID.',
+        hidden: true,
+    },
+    experimentalDevtools: {
+        type: 'boolean',
+        describe: 'Whether to enable automation over DevTools targets',
+        hidden: true,
+    },
+    experimentalVision: {
+        type: 'boolean',
+        describe: 'Whether to enable coordinate-based tools such as click_at(x,y). Usually requires a computer-use model able to produce accurate coordinates by looking at screenshots.',
+        hidden: false,
+    },
+    experimentalStructuredContent: {
+        type: 'boolean',
+        describe: 'Whether to output structured formatted content.',
+        hidden: true,
+    },
+    experimentalIncludeAllPages: {
+        type: 'boolean',
+        describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
+        hidden: true,
+    },
+    experimentalInteropTools: {
+        type: 'boolean',
+        describe: 'Whether to enable interoperability tools',
+        hidden: true,
+    },
+    experimentalScreencast: {
+        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.',
+    },
+    braveArg: {
+        type: 'array',
+        describe: 'Additional arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.',
+    },
+    ignoreDefaultBraveArg: {
+        type: 'array',
+        describe: 'Explicitly disable default arguments for Brave. Only applies when Brave is launched by brave-devtools-mcp.',
+    },
+    categoryEmulation: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to emulation.',
+    },
+    categoryPerformance: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to performance.',
+    },
+    categoryNetwork: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to network.',
+    },
+    categoryExtensions: {
+        type: 'boolean',
+        hidden: true,
+        conflicts: ['browserUrl', 'autoConnect', 'wsEndpoint'],
+        describe: 'Set to true to include tools related to extensions. Note: This feature is only supported with a pipe connection. autoConnect is not supported.',
+    },
+    categoryInPageTools: {
+        type: 'boolean',
+        hidden: true,
+        describe: 'Set to true to enable tools exposed by the inspected page itself',
+    },
+    performanceCrux: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to disable sending URLs from performance traces to CrUX API to get field performance data.',
+    },
+    usageStatistics: {
+        type: 'boolean',
+        default: false,
+        describe: 'Usage statistics collection (disabled by default in this fork).',
+    },
+    clearcutEndpoint: {
+        type: 'string',
+        hidden: true,
+        describe: 'Endpoint for Clearcut telemetry.',
+    },
+    clearcutForceFlushIntervalMs: {
+        type: 'number',
+        hidden: true,
+        describe: 'Force flush interval in milliseconds (for testing).',
+    },
+    clearcutIncludePidHeader: {
+        type: 'boolean',
+        hidden: true,
+        describe: 'Include watchdog PID in Clearcut request headers (for testing).',
+    },
+    slim: {
+        type: 'boolean',
+        describe: 'Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.',
+    },
+    viaCli: {
+        type: 'boolean',
+        describe: 'Set by Brave DevTools CLI if the MCP server is started via the CLI client (this arg exists for usage stats)',
+        hidden: true,
+    },
+};
+export function parseArguments(version, argv = process.argv) {
+    const yargsInstance = yargs(hideBin(argv))
+        .scriptName('npx brave-devtools-mcp@latest')
+        .options(cliOptions)
+        .check(args => {
+        if (!args.channel &&
+            !args.browserUrl &&
+            !args.wsEndpoint &&
+            !args.executablePath) {
+            args.channel = 'release';
+        }
+        return true;
+    })
+        .example([
+        [
+            '$0 --browserUrl http://127.0.0.1:9222',
+            'Connect to an existing Brave instance via HTTP',
+        ],
+        [
+            '$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123',
+            'Connect to an existing Brave instance via WebSocket',
+        ],
+        [
+            `$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123 --wsHeaders '{"Authorization":"Bearer token"}'`,
+            'Connect via WebSocket with custom headers',
+        ],
+        ['$0 --channel beta', 'Use Brave Beta installed on this system'],
+        ['$0 --channel nightly', 'Use Brave Nightly installed on this system'],
+        ['$0 --channel dev', 'Use Brave Dev installed on this system'],
+        ['$0 --channel release', 'Use release Brave installed on this system'],
+        ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
+        ['$0 --help', 'Print CLI options'],
+        [
+            '$0 --viewport 1280x720',
+            'Launch Brave with the initial viewport size of 1280x720px',
+        ],
+        [
+            `$0 --brave-arg='--no-sandbox' --brave-arg='--disable-setuid-sandbox'`,
+            'Launch Brave without sandboxes. Use with caution.',
+        ],
+        [
+            `$0 --ignore-default-brave-arg='--disable-extensions'`,
+            'Disable the default arguments provided by Puppeteer. Use with caution.',
+        ],
+        ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
+        [
+            '$0 --no-category-performance',
+            'Disable tools in the performance category',
+        ],
+        ['$0 --no-category-network', 'Disable tools in the network category'],
+        [
+            '$0 --user-data-dir=/tmp/user-data-dir',
+            'Use a custom user data directory',
+        ],
+        [
+            '$0 --auto-connect',
+            'Connect to a release Brave instance running instead of launching a new instance',
+        ],
+        [
+            '$0 --auto-connect --channel=nightly',
+            'Connect to a nightly Brave instance running instead of launching a new instance',
+        ],
+        [
+            '$0 --slim',
+            'Only 3 tools: navigation, JavaScript execution and screenshot',
+        ],
+    ]);
+    return yargsInstance
+        .wrap(Math.min(120, yargsInstance.terminalWidth()))
+        .help()
+        .version(version)
+        .parseSync();
+}

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

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import '../polyfill.js';
+import process from 'node:process';
+import { createMcpServer, logDisclaimers } from '../index.js';
+import { logger, saveLogsToFile } from '../logger.js';
+import { computeFlagUsage } from '../telemetry/flagUtils.js';
+import { StdioServerTransport } from '../third_party/index.js';
+import { VERSION } from '../version.js';
+import { cliOptions, parseArguments } from './brave-devtools-mcp-cli-options.js';
+export const args = parseArguments(VERSION);
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+if (process.env['CI'] ||
+    process.env['BRAVE_DEVTOOLS_MCP_NO_USAGE_STATISTICS']) {
+    console.error("turning off usage statistics. process.env['CI'] || process.env['BRAVE_DEVTOOLS_MCP_NO_USAGE_STATISTICS'] is set.");
+    args.usageStatistics = false;
+}
+if (process.env['BRAVE_DEVTOOLS_MCP_CRASH_ON_UNCAUGHT'] !== 'true') {
+    process.on('unhandledRejection', (reason, promise) => {
+        logger('Unhandled promise rejection', promise, reason);
+    });
+}
+logger(`Starting Brave DevTools MCP Server v${VERSION}`);
+const { server, clearcutLogger } = await createMcpServer(args, {
+    logFile,
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Brave DevTools MCP Server connected');
+logDisclaimers(args);
+void clearcutLogger?.logDailyActiveIfNeeded();
+void clearcutLogger?.logServerStart(computeFlagUsage(args, cliOptions));

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

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+process.title = 'brave-devtools-mcp';
+import { version } from 'node:process';
+const [major, minor] = version.substring(1).split('.').map(Number);
+if (major === 20 && minor < 19) {
+    console.error(`ERROR: \`brave-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major === 22 && minor < 12) {
+    console.error(`ERROR: \`brave-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major < 20) {
+    console.error(`ERROR: \`brave-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+await import('./brave-devtools-mcp-main.js');

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

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+process.title = 'brave-devtools';
+import process from 'node:process';
+import { startDaemon, stopDaemon, sendCommand, handleResponse, } from '../daemon/client.js';
+import { isDaemonRunning, serializeArgs } from '../daemon/utils.js';
+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';
+await checkForUpdates('Run `npm install -g brave-devtools-mcp@latest` and `brave-devtools start` to update and restart the daemon.');
+async function start(args) {
+    const combinedArgs = [...args, ...defaultArgs];
+    await startDaemon(combinedArgs);
+    logDisclaimers(parseArguments(VERSION, combinedArgs));
+}
+const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
+const startCliOptions = {
+    ...cliOptions,
+};
+// Not supported in CLI on purpose.
+delete startCliOptions.autoConnect;
+// Missing CLI serialization.
+delete startCliOptions.viewport;
+// CLI is generated based on the default tool definitions. To enable conditional
+// tools, they need to be enabled during CLI generation.
+delete startCliOptions.experimentalPageIdRouting;
+delete startCliOptions.experimentalVision;
+delete startCliOptions.experimentalInteropTools;
+delete startCliOptions.experimentalScreencast;
+delete startCliOptions.categoryEmulation;
+delete startCliOptions.categoryPerformance;
+delete startCliOptions.categoryNetwork;
+delete startCliOptions.categoryExtensions;
+// Always on in CLI.
+delete startCliOptions.experimentalStructuredContent;
+// Change the defaults.
+if (!('default' in cliOptions.headless)) {
+    throw new Error('headless cli option unexpectedly does not have a default');
+}
+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.';
+const y = yargs(hideBin(process.argv))
+    .scriptName('brave-devtools')
+    .showHelpOnFail(true)
+    .usage('brave-devtools <command> [...args] --flags')
+    .usage(`Run 'brave-devtools <command> --help' for help on the specific command.`)
+    .demandCommand()
+    .version(VERSION)
+    .strict()
+    .help(true)
+    .wrap(120);
+y.command('start', 'Start or restart brave-devtools-mcp', y => y
+    .options(startCliOptions)
+    .example('$0 start --browserUrl http://localhost:9222', 'Start the server connecting to an existing browser')
+    .strict(), async (argv) => {
+    if (isDaemonRunning()) {
+        await stopDaemon();
+    }
+    // Defaults but we do not want to affect the yargs conflict resolution.
+    if (argv.isolated === undefined && argv.userDataDir === undefined) {
+        argv.isolated = true;
+    }
+    if (argv.headless === undefined) {
+        argv.headless = true;
+    }
+    const args = serializeArgs(cliOptions, argv);
+    await start(args);
+    process.exit(0);
+}).strict(); // Re-enable strict validation for other commands; this is applied to the yargs instance itself
+y.command('status', 'Checks if brave-devtools-mcp is running', async () => {
+    if (isDaemonRunning()) {
+        console.log('brave-devtools-mcp daemon is running.');
+        const response = await sendCommand({
+            method: 'status',
+        });
+        if (response.success) {
+            const data = JSON.parse(response.result);
+            console.log(`pid=${data.pid} socket=${data.socketPath} start-date=${data.startDate} version=${data.version}`);
+            console.log(`args=${JSON.stringify(data.args)}`);
+        }
+        else {
+            console.error('Error:', response.error);
+            process.exit(1);
+        }
+    }
+    else {
+        console.log('brave-devtools-mcp daemon is not running.');
+    }
+    process.exit(0);
+});
+y.command('stop', 'Stop brave-devtools-mcp if any', async () => {
+    if (!isDaemonRunning()) {
+        process.exit(0);
+    }
+    await stopDaemon();
+    process.exit(0);
+});
+for (const [commandName, commandDef] of Object.entries(commands)) {
+    const args = commandDef.args;
+    const requiredArgNames = Object.keys(args).filter(name => args[name].required);
+    const optionalArgNames = Object.keys(args).filter(name => !args[name].required);
+    let commandStr = commandName;
+    for (const arg of requiredArgNames) {
+        commandStr += ` <${arg}>`;
+    }
+    for (const arg of optionalArgNames) {
+        commandStr += ` [--${arg}]`;
+    }
+    y.command(commandStr, commandDef.description, y => {
+        y.option('output-format', {
+            choices: ['md', 'json'],
+            default: 'md',
+        });
+        for (const [argName, opt] of Object.entries(args)) {
+            const type = opt.type === 'integer' || opt.type === 'number'
+                ? 'number'
+                : opt.type === 'boolean'
+                    ? 'boolean'
+                    : opt.type === 'array'
+                        ? 'array'
+                        : 'string';
+            if (opt.required) {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.positional(argName, options);
+            }
+            else {
+                const options = {
+                    describe: opt.description,
+                    type: type,
+                };
+                if (opt.default !== undefined) {
+                    options.default = opt.default;
+                }
+                if (opt.enum) {
+                    options.choices = opt.enum;
+                }
+                y.option(argName, options);
+            }
+        }
+    }, async (argv) => {
+        try {
+            if (!isDaemonRunning()) {
+                await start([]);
+            }
+            const commandArgs = {};
+            for (const argName of Object.keys(args)) {
+                if (argName in argv) {
+                    commandArgs[argName] = argv[argName];
+                }
+            }
+            const response = await sendCommand({
+                method: 'invoke_tool',
+                tool: commandName,
+                args: commandArgs,
+            });
+            if (response.success) {
+                console.log(await handleResponse(JSON.parse(response.result), argv['output-format']));
+            }
+            else {
+                console.error('Error:', response.error);
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error('Failed to execute command:', error);
+            process.exit(1);
+        }
+    });
+}
+await y.parse();

package/build/src/bin/check-latest-version.js

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+const cachePath = process.argv[2];
+if (cachePath) {
+    try {
+        const response = await fetch('https://registry.npmjs.org/brave-mcp/latest');
+        const data = response.ok ? await response.json() : null;
+        if (data &&
+            typeof data === 'object' &&
+            'version' in data &&
+            typeof data.version === 'string') {
+            await fs.mkdir(path.dirname(cachePath), { recursive: true });
+            await fs.writeFile(cachePath, JSON.stringify({ version: data.version }));
+        }
+    }
+    catch {
+        // Ignore errors.
+    }
+}