@darbotlabs/darbot-browser-mcp 0.1.0

package/lib/cdpRelay.js

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Bridge Server - Standalone WebSocket server that bridges Darbot Browser MCP and Browser Extension
+ *
+ * Endpoints:
+ * - /cdp - Full CDP interface for Darbot Browser MCP
+ * - /extension - Extension connection for chrome.debugger forwarding
+ */
+/* eslint-disable no-console */
+import { WebSocket, WebSocketServer } from 'ws';
+import http from 'node:http';
+import { EventEmitter } from 'node:events';
+import debug from 'debug';
+import { httpAddressToString } from './transport.js';
+const debugLogger = debug('pw:mcp:relay');
+const CDP_PATH = '/cdp';
+const EXTENSION_PATH = '/extension';
+export class CDPRelayServer extends EventEmitter {
+    _wss;
+    _playwrightSocket = null;
+    _extensionSocket = null;
+    _connectionInfo;
+    constructor(server) {
+        super();
+        this._wss = new WebSocketServer({ server });
+        this._wss.on('connection', this._onConnection.bind(this));
+    }
+    stop() {
+        this._playwrightSocket?.close();
+        this._extensionSocket?.close();
+    }
+    _onConnection(ws, request) {
+        const url = new URL(`http://localhost${request.url}`);
+        debugLogger(`New connection to ${url.pathname}`);
+        if (url.pathname === CDP_PATH) {
+            this._handlePlaywrightConnection(ws);
+        }
+        else if (url.pathname === EXTENSION_PATH) {
+            this._handleExtensionConnection(ws);
+        }
+        else {
+            debugLogger(`Invalid path: ${url.pathname}`);
+            ws.close(4004, 'Invalid path');
+        }
+    }
+    /**
+     * Handle Darbot Browser MCP connection - provides full CDP interface
+     */
+    _handlePlaywrightConnection(ws) {
+        if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+            debugLogger('Closing previous Playwright connection');
+            this._playwrightSocket.close(1000, 'New connection established');
+        }
+        this._playwrightSocket = ws;
+        debugLogger('Darbot Browser MCP connected');
+        ws.on('message', data => {
+            try {
+                const message = JSON.parse(data.toString());
+                this._handlePlaywrightMessage(message);
+            }
+            catch (error) {
+                debugLogger('Error parsing Playwright message:', error);
+            }
+        });
+        ws.on('close', () => {
+            if (this._playwrightSocket === ws)
+                this._playwrightSocket = null;
+            debugLogger('Darbot Browser MCP disconnected');
+        });
+        ws.on('error', error => {
+            debugLogger('Playwright WebSocket error:', error);
+        });
+    }
+    /**
+     * Handle Extension connection - forwards to browser debugger
+     */
+    _handleExtensionConnection(ws) {
+        if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+            debugLogger('Closing previous extension connection');
+            this._extensionSocket.close(1000, 'New connection established');
+        }
+        this._extensionSocket = ws;
+        debugLogger('Extension connected');
+        ws.on('message', data => {
+            try {
+                const message = JSON.parse(data.toString());
+                this._handleExtensionMessage(message);
+            }
+            catch (error) {
+                debugLogger('Error parsing extension message:', error);
+            }
+        });
+        ws.on('close', () => {
+            if (this._extensionSocket === ws)
+                this._extensionSocket = null;
+            debugLogger('Extension disconnected');
+        });
+        ws.on('error', error => {
+            debugLogger('Extension WebSocket error:', error);
+        });
+    }
+    /**
+     * Handle messages from Darbot Browser MCP
+     */
+    _handlePlaywrightMessage(message) {
+        debugLogger('← Playwright:', message.method || `response(${message.id})`);
+        // Handle Browser domain methods locally
+        if (message.method?.startsWith('Browser.')) {
+            this._handleBrowserDomainMethod(message);
+            return;
+        }
+        // Handle Target domain methods
+        if (message.method?.startsWith('Target.')) {
+            this._handleTargetDomainMethod(message);
+            return;
+        }
+        // Forward other commands to extension
+        if (message.method)
+            this._forwardToExtension(message);
+    }
+    /**
+     * Handle messages from Extension
+     */
+    _handleExtensionMessage(message) {
+        // Handle connection info from extension
+        if (message.type === 'connection_info') {
+            debugLogger('← Extension connected to tab:', message);
+            this._connectionInfo = {
+                targetInfo: message.targetInfo,
+                // Page sessionId that should be used by this connection.
+                sessionId: message.sessionId
+            };
+            return;
+        }
+        // CDP event from extension
+        debugLogger(`← Extension message: ${message.method ?? (message.id && `response(id=${message.id})`) ?? 'unknown'}`);
+        this._sendToPlaywright(message);
+    }
+    /**
+     * Handle Browser domain methods locally
+     */
+    _handleBrowserDomainMethod(message) {
+        switch (message.method) {
+            case 'Browser.getVersion':
+                this._sendToPlaywright({
+                    id: message.id,
+                    result: {
+                        protocolVersion: '1.3',
+                        product: 'Browser/Extension-Bridge',
+                        userAgent: 'CDP-Bridge-Server/1.0.0',
+                    }
+                });
+                break;
+            case 'Browser.setDownloadBehavior':
+                this._sendToPlaywright({
+                    id: message.id,
+                    result: {}
+                });
+                break;
+            default:
+                // Forward unknown Browser methods to extension
+                this._forwardToExtension(message);
+        }
+    }
+    /**
+     * Handle Target domain methods
+     */
+    _handleTargetDomainMethod(message) {
+        switch (message.method) {
+            case 'Target.setAutoAttach':
+                // Simulate auto-attach behavior with real target info
+                if (this._connectionInfo && !message.sessionId) {
+                    debugLogger('Simulating auto-attach for target:', JSON.stringify(message));
+                    this._sendToPlaywright({
+                        method: 'Target.attachedToTarget',
+                        params: {
+                            sessionId: this._connectionInfo.sessionId,
+                            targetInfo: {
+                                ...this._connectionInfo.targetInfo,
+                                attached: true,
+                            },
+                            waitingForDebugger: false
+                        }
+                    });
+                    this._sendToPlaywright({
+                        id: message.id,
+                        result: {}
+                    });
+                }
+                else {
+                    this._forwardToExtension(message);
+                }
+                break;
+            case 'Target.getTargets':
+                const targetInfos = [];
+                if (this._connectionInfo) {
+                    targetInfos.push({
+                        ...this._connectionInfo.targetInfo,
+                        attached: true,
+                    });
+                }
+                this._sendToPlaywright({
+                    id: message.id,
+                    result: { targetInfos }
+                });
+                break;
+            default:
+                this._forwardToExtension(message);
+        }
+    }
+    /**
+     * Forward message to extension
+     */
+    _forwardToExtension(message) {
+        if (this._extensionSocket?.readyState === WebSocket.OPEN) {
+            debugLogger('→ Extension:', message.method || `command(${message.id})`);
+            this._extensionSocket.send(JSON.stringify(message));
+        }
+        else {
+            debugLogger('Extension not connected, cannot forward message');
+            if (message.id) {
+                this._sendToPlaywright({
+                    id: message.id,
+                    error: { message: 'Extension not connected' }
+                });
+            }
+        }
+    }
+    /**
+     * Forward message to Playwright
+     */
+    _sendToPlaywright(message) {
+        if (this._playwrightSocket?.readyState === WebSocket.OPEN) {
+            debugLogger('→ Playwright:', JSON.stringify(message));
+            this._playwrightSocket.send(JSON.stringify(message));
+        }
+    }
+}
+export async function startCDPRelayServer(httpServer) {
+    const wsAddress = httpAddressToString(httpServer.address()).replace(/^http/, 'ws');
+    const cdpRelayServer = new CDPRelayServer(httpServer);
+    process.on('exit', () => cdpRelayServer.stop());
+    debugLogger(`CDP relay server started on ${wsAddress}${EXTENSION_PATH} - Connect to it using the browser extension.`);
+    const cdpEndpoint = `${wsAddress}${CDP_PATH}`;
+    return cdpEndpoint;
+}
+// CLI usage
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const port = parseInt(process.argv[2], 10) || 9223;
+    const httpServer = http.createServer();
+    await new Promise(resolve => httpServer.listen(port, resolve));
+    const server = new CDPRelayServer(httpServer);
+    console.error(`CDP Bridge Server listening on ws://localhost:${port}`);
+    console.error(`- Darbot Browser MCP: ws://localhost:${port}${CDP_PATH}`);
+    console.error(`- Extension: ws://localhost:${port}${EXTENSION_PATH}`);
+    process.on('SIGINT', () => {
+        debugLogger('\nShutting down bridge server...');
+        server.stop();
+        process.exit(0);
+    });
+}

package/lib/config.js

@@ -0,0 +1,204 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { devices } from 'playwright';
+import { sanitizeForFilePath } from './tools/utils.js';
+const defaultConfig = {
+    browser: {
+        browserName: 'chromium',
+        launchOptions: {
+            channel: 'msedge',
+            headless: os.platform() === 'linux' && !process.env.DISPLAY,
+            chromiumSandbox: true,
+            args: [
+                '--disable-popup-blocking',
+                '--allow-popups',
+                `--disable-extensions-except=${process.env.EXTENSION_PATH || '/default/path/to/extension'}`, // Use EXTENSION_PATH environment variable or fallback to default
+                `--load-extension=${process.env.EXTENSION_PATH || '/default/path/to/extension'}`, // Use EXTENSION_PATH environment variable or fallback to default
+            ],
+        },
+        contextOptions: {
+            viewport: null,
+        },
+    },
+    network: {
+        allowedOrigins: undefined,
+        blockedOrigins: undefined,
+    },
+    server: {},
+    outputDir: path.join(os.tmpdir(), 'darbot-browser-mcp-output', sanitizeForFilePath(new Date().toISOString())),
+};
+export async function resolveConfig(config) {
+    return mergeConfig(defaultConfig, config);
+}
+export async function resolveCLIConfig(cliOptions) {
+    const configInFile = await loadConfig(cliOptions.config);
+    const cliOverrides = await configFromCLIOptions(cliOptions);
+    const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+    // Derive artifact output directory from config.outputDir
+    if (result.saveTrace)
+        result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+    return result;
+}
+export function validateConfig(config) {
+    if (config.extension) {
+        if (config.browser?.browserName !== 'chromium')
+            throw new Error('Extension mode is only supported for Chromium browsers.');
+    }
+}
+export async function configFromCLIOptions(cliOptions) {
+    let browserName;
+    let channel;
+    switch (cliOptions.browser) {
+        case 'chrome':
+        case 'chrome-beta':
+        case 'chrome-canary':
+        case 'chrome-dev':
+        case 'chromium':
+        case 'msedge':
+        case 'msedge-beta':
+        case 'msedge-canary':
+        case 'msedge-dev':
+            browserName = 'chromium';
+            channel = cliOptions.browser;
+            break;
+        case 'firefox':
+            browserName = 'firefox';
+            break;
+        case 'webkit':
+            browserName = 'webkit';
+            break;
+    }
+    // Launch options
+    const launchOptions = {
+        channel,
+        executablePath: cliOptions.executablePath,
+        headless: cliOptions.headless,
+    };
+    // --no-sandbox was passed, disable the sandbox
+    if (!cliOptions.sandbox)
+        launchOptions.chromiumSandbox = false;
+    if (cliOptions.proxyServer) {
+        launchOptions.proxy = {
+            server: cliOptions.proxyServer
+        };
+        if (cliOptions.proxyBypass)
+            launchOptions.proxy.bypass = cliOptions.proxyBypass;
+    }
+    if (cliOptions.device && cliOptions.cdpEndpoint)
+        throw new Error('Device emulation is not supported with cdpEndpoint.');
+    if (cliOptions.device && cliOptions.extension)
+        throw new Error('Device emulation is not supported with extension mode.');
+    // Context options
+    const contextOptions = cliOptions.device ? devices[cliOptions.device] : {};
+    if (cliOptions.storageState)
+        contextOptions.storageState = cliOptions.storageState;
+    if (cliOptions.userAgent)
+        contextOptions.userAgent = cliOptions.userAgent;
+    if (cliOptions.viewportSize) {
+        try {
+            const [width, height] = cliOptions.viewportSize.split(',').map(n => +n);
+            if (isNaN(width) || isNaN(height))
+                throw new Error('bad values');
+            contextOptions.viewport = { width, height };
+        }
+        catch (e) {
+            throw new Error('Invalid viewport size format: use "width,height", for example --viewport-size="800,600"');
+        }
+    }
+    if (cliOptions.ignoreHttpsErrors)
+        contextOptions.ignoreHTTPSErrors = true;
+    if (cliOptions.blockServiceWorkers)
+        contextOptions.serviceWorkers = 'block';
+    const result = {
+        browser: {
+            browserAgent: cliOptions.browserAgent ?? process.env.PW_BROWSER_AGENT,
+            browserName,
+            isolated: cliOptions.isolated,
+            userDataDir: cliOptions.userDataDir,
+            launchOptions,
+            contextOptions,
+            cdpEndpoint: cliOptions.cdpEndpoint,
+        },
+        server: {
+            port: cliOptions.port,
+            host: cliOptions.host,
+        },
+        capabilities: cliOptions.caps?.split(',').map((c) => c.trim()),
+        vision: !!cliOptions.vision,
+        extension: !!cliOptions.extension,
+        network: {
+            allowedOrigins: cliOptions.allowedOrigins,
+            blockedOrigins: cliOptions.blockedOrigins,
+        },
+        saveTrace: cliOptions.saveTrace,
+        outputDir: cliOptions.outputDir,
+        imageResponses: cliOptions.imageResponses,
+    };
+    return result;
+}
+async function loadConfig(configFile) {
+    if (!configFile)
+        return {};
+    try {
+        return JSON.parse(await fs.promises.readFile(configFile, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Failed to load config file: ${configFile}, ${error}`);
+    }
+}
+export async function outputFile(config, name) {
+    await fs.promises.mkdir(config.outputDir, { recursive: true });
+    const fileName = sanitizeForFilePath(name);
+    return path.join(config.outputDir, fileName);
+}
+function pickDefined(obj) {
+    return Object.fromEntries(Object.entries(obj ?? {}).filter(([_, v]) => v !== undefined));
+}
+function mergeConfig(base, overrides) {
+    const browser = {
+        ...pickDefined(base.browser),
+        ...pickDefined(overrides.browser),
+        browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
+        isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
+        launchOptions: {
+            ...pickDefined(base.browser?.launchOptions),
+            ...pickDefined(overrides.browser?.launchOptions),
+            ...{ assistantMode: true },
+        },
+        contextOptions: {
+            ...pickDefined(base.browser?.contextOptions),
+            ...pickDefined(overrides.browser?.contextOptions),
+        },
+    };
+    if (browser.browserName !== 'chromium' && browser.launchOptions)
+        delete browser.launchOptions.channel;
+    return {
+        ...pickDefined(base),
+        ...pickDefined(overrides),
+        browser,
+        network: {
+            ...pickDefined(base.network),
+            ...pickDefined(overrides.network),
+        },
+        server: {
+            ...pickDefined(base.server),
+            ...pickDefined(overrides.server),
+        },
+    };
+}

package/lib/connection.js

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Context } from './context.js';
+import { snapshotTools, visionTools } from './tools.js';
+import { packageJSON } from './package.js';
+import { validateConfig } from './config.js';
+export function createConnection(config, browserContextFactory) {
+    const allTools = config.vision ? visionTools : snapshotTools;
+    const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
+    validateConfig(config);
+    const context = new Context(tools, config, browserContextFactory);
+    const server = new McpServer({ name: 'Browser', version: packageJSON.version }, {
+        capabilities: {
+            tools: {},
+        }
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: tools.map(tool => ({
+                name: tool.schema.name,
+                description: tool.schema.description,
+                inputSchema: zodToJsonSchema(tool.schema.inputSchema),
+                annotations: {
+                    title: tool.schema.title,
+                    readOnlyHint: tool.schema.type === 'readOnly',
+                    destructiveHint: tool.schema.type === 'destructive',
+                    openWorldHint: true,
+                },
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const errorResult = (...messages) => ({
+            content: [{ type: 'text', text: messages.join('\n') }],
+            isError: true,
+        });
+        const tool = tools.find(tool => tool.schema.name === request.params.name);
+        if (!tool)
+            return errorResult(`Tool "${request.params.name}" not found`);
+        const modalStates = context.modalStates().map(state => state.type);
+        if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
+            return errorResult(`The tool "${request.params.name}" can only be used when there is related modal state present.`, ...context.modalStatesMarkdown());
+        if (!tool.clearsModalState && modalStates.length)
+            return errorResult(`Tool "${request.params.name}" does not handle the modal state.`, ...context.modalStatesMarkdown());
+        try {
+            return await context.run(tool, request.params.arguments);
+        }
+        catch (error) {
+            return errorResult(String(error));
+        }
+    });
+    return new Connection(server, context);
+}
+export class Connection {
+    server;
+    context;
+    constructor(server, context) {
+        this.server = server;
+        this.context = context;
+        this.server.oninitialized = () => {
+            this.context.clientVersion = this.server.getClientVersion();
+        };
+    }
+    async close() {
+        await this.server.close();
+        await this.context.close();
+    }
+}