@darbotlabs/darbot-browser-mcp 0.1.0

package/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * 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 './lib/program.js';

package/config.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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 type * as playwright from 'playwright';
+
+export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install' | 'testing';
+
+export type Config = {
+  /**
+   * The browser to use.
+   */
+  browser?: {
+    /**
+     * Use browser agent (experimental).
+     */
+    browserAgent?: string;
+
+    /**
+     * The type of browser to use.
+     */
+    browserName?: 'chromium' | 'firefox' | 'webkit';
+
+    /**
+     * Keep the browser profile in memory, do not save it to disk.
+     */
+    isolated?: boolean;
+
+    /**
+     * Path to a user data directory for browser profile persistence.
+     * Temporary directory is created by default.
+     */
+    userDataDir?: string;
+
+    /**
+     * Launch options passed to
+     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
+     *
+     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
+     */
+    launchOptions?: playwright.LaunchOptions;
+
+    /**
+     * Context options for the browser context.
+     *
+     * This is useful for settings options like `viewport`.
+     */
+    contextOptions?: playwright.BrowserContextOptions;
+
+    /**
+     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
+     */
+    cdpEndpoint?: string;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+  },
+
+  server?: {
+    /**
+     * The port to listen on for SSE or MCP transport.
+     */
+    port?: number;
+
+    /**
+     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     */
+    host?: string;
+  },
+
+  /**
+   * List of enabled tool capabilities. Possible values:
+   *   - 'core': Core browser automation features.
+   *   - 'tabs': Tab management features.
+   *   - 'pdf': PDF generation and manipulation.
+   *   - 'history': Browser history access.
+   *   - 'wait': Wait and timing utilities.
+   *   - 'files': File upload/download support.
+   *   - 'install': Browser installation utilities.
+   */
+  capabilities?: ToolCapability[];
+
+  /**
+   * Run server that uses screenshots (Aria snapshots are used by default).
+   */
+  vision?: boolean;
+
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  network?: {
+    /**
+     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    blockedOrigins?: string[];
+  };
+
+  /**
+   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   */
+  imageResponses?: 'allow' | 'omit' | 'auto';
+};

package/index.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * 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 type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
+
+export type Connection = {
+  server: Server;
+  close(): Promise<void>;
+};
+
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
+export {};

package/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * 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 { createConnection } from './lib/index.js';
+export { createConnection };

package/lib/browserContextFactory.js

@@ -0,0 +1,227 @@
+/**
+ * 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 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import os from 'node:os';
+import debug from 'debug';
+import * as playwright from 'playwright';
+import { userDataDir } from './fileUtils.js';
+const testDebug = debug('pw:mcp:test');
+export function contextFactory(browserConfig) {
+    if (browserConfig.remoteEndpoint)
+        return new RemoteContextFactory(browserConfig);
+    if (browserConfig.cdpEndpoint)
+        return new CdpContextFactory(browserConfig);
+    if (browserConfig.isolated)
+        return new IsolatedContextFactory(browserConfig);
+    if (browserConfig.browserAgent)
+        return new BrowserServerContextFactory(browserConfig);
+    return new PersistentContextFactory(browserConfig);
+}
+class BaseContextFactory {
+    browserConfig;
+    _browserPromise;
+    name;
+    constructor(name, browserConfig) {
+        this.name = name;
+        this.browserConfig = browserConfig;
+    }
+    async _obtainBrowser() {
+        if (this._browserPromise)
+            return this._browserPromise;
+        testDebug(`obtain browser (${this.name})`);
+        this._browserPromise = this._doObtainBrowser();
+        void this._browserPromise.then(browser => {
+            browser.on('disconnected', () => {
+                this._browserPromise = undefined;
+            });
+        }).catch(() => {
+            this._browserPromise = undefined;
+        });
+        return this._browserPromise;
+    }
+    async _doObtainBrowser() {
+        throw new Error('Not implemented');
+    }
+    async createContext() {
+        testDebug(`create browser context (${this.name})`);
+        const browser = await this._obtainBrowser();
+        const browserContext = await this._doCreateContext(browser);
+        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
+    }
+    async _doCreateContext(browser) {
+        throw new Error('Not implemented');
+    }
+    async _closeBrowserContext(browserContext, browser) {
+        testDebug(`close browser context (${this.name})`);
+        if (browser.contexts().length === 1)
+            this._browserPromise = undefined;
+        await browserContext.close().catch(() => { });
+        if (browser.contexts().length === 0) {
+            testDebug(`close browser (${this.name})`);
+            await browser.close().catch(() => { });
+        }
+    }
+}
+class IsolatedContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('isolated', browserConfig);
+    }
+    async _doObtainBrowser() {
+        await injectCdpPort(this.browserConfig);
+        const browserType = playwright[this.browserConfig.browserName];
+        return browserType.launch({
+            ...this.browserConfig.launchOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).catch(error => {
+            if (error.message.includes('Executable doesn\'t exist'))
+                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+            throw error;
+        });
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext(this.browserConfig.contextOptions);
+    }
+}
+class CdpContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('cdp', browserConfig);
+    }
+    async _doObtainBrowser() {
+        return playwright.chromium.connectOverCDP(this.browserConfig.cdpEndpoint);
+    }
+    async _doCreateContext(browser) {
+        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+}
+class RemoteContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('remote', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const url = new URL(this.browserConfig.remoteEndpoint);
+        url.searchParams.set('browser', this.browserConfig.browserName);
+        if (this.browserConfig.launchOptions)
+            url.searchParams.set('launch-options', JSON.stringify(this.browserConfig.launchOptions));
+        return playwright[this.browserConfig.browserName].connect(String(url));
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext();
+    }
+}
+class PersistentContextFactory {
+    browserConfig;
+    _userDataDirs = new Set();
+    constructor(browserConfig) {
+        this.browserConfig = browserConfig;
+    }
+    async createContext() {
+        await injectCdpPort(this.browserConfig);
+        testDebug('create browser context (persistent)');
+        const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+        this._userDataDirs.add(userDataDir);
+        testDebug('lock user data dir', userDataDir);
+        const browserType = playwright[this.browserConfig.browserName];
+        for (let i = 0; i < 5; i++) {
+            try {
+                const browserContext = await browserType.launchPersistentContext(userDataDir, {
+                    ...this.browserConfig.launchOptions,
+                    ...this.browserConfig.contextOptions,
+                    handleSIGINT: false,
+                    handleSIGTERM: false,
+                });
+                const close = () => this._closeBrowserContext(browserContext, userDataDir);
+                return { browserContext, close };
+            }
+            catch (error) {
+                if (error.message.includes('Executable doesn\'t exist'))
+                    throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
+                    // User data directory is already in use, try again.
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+    }
+    async _closeBrowserContext(browserContext, userDataDir) {
+        testDebug('close browser context (persistent)');
+        testDebug('release user data dir', userDataDir);
+        await browserContext.close().catch(() => { });
+        this._userDataDirs.delete(userDataDir);
+        testDebug('close browser context complete (persistent)');
+    }
+    async _createUserDataDir() {
+        let cacheDirectory;
+        if (process.platform === 'linux')
+            cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+        else if (process.platform === 'darwin')
+            cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+        else if (process.platform === 'win32')
+            cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+        else
+            throw new Error('Unsupported platform: ' + process.platform);
+        const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+        await fs.promises.mkdir(result, { recursive: true });
+        return result;
+    }
+}
+export class BrowserServerContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('persistent', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const response = await fetch(new URL(`/json/launch`, this.browserConfig.browserAgent), {
+            method: 'POST',
+            body: JSON.stringify({
+                browserType: this.browserConfig.browserName,
+                userDataDir: this.browserConfig.userDataDir ?? await this._createUserDataDir(),
+                launchOptions: this.browserConfig.launchOptions,
+                contextOptions: this.browserConfig.contextOptions,
+            }),
+        });
+        const info = await response.json();
+        if (info.error)
+            throw new Error(info.error);
+        return await playwright.chromium.connectOverCDP(`http://localhost:${info.cdpPort}/`);
+    }
+    async _doCreateContext(browser) {
+        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+    async _createUserDataDir() {
+        const dir = await userDataDir(this.browserConfig);
+        await fs.promises.mkdir(dir, { recursive: true });
+        return dir;
+    }
+}
+async function injectCdpPort(browserConfig) {
+    if (browserConfig.browserName === 'chromium')
+        browserConfig.launchOptions.cdpPort = await findFreePort();
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}

package/lib/browserServer.js

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+/* eslint-disable no-console */
+import net from 'net';
+import { program } from 'commander';
+import playwright from 'playwright';
+import { HttpServer } from './httpServer.js';
+import { packageJSON } from './package.js';
+class BrowserServer {
+    _server = new HttpServer();
+    _entries = [];
+    constructor() {
+        this._setupExitHandler();
+    }
+    async start(port) {
+        await this._server.start({ port });
+        this._server.routePath('/json/list', (req, res) => {
+            this._handleJsonList(res);
+        });
+        this._server.routePath('/json/launch', async (req, res) => {
+            void this._handleLaunchBrowser(req, res).catch(e => console.error(e));
+        });
+        this._setEntries([]);
+    }
+    _handleJsonList(res) {
+        const list = this._entries.map(browser => browser.info);
+        res.end(JSON.stringify(list));
+    }
+    async _handleLaunchBrowser(req, res) {
+        const request = await readBody(req);
+        let info = this._entries.map(entry => entry.info).find(info => info.userDataDir === request.userDataDir);
+        if (!info || info.error)
+            info = await this._newBrowser(request);
+        res.end(JSON.stringify(info));
+    }
+    async _newBrowser(request) {
+        const cdpPort = await findFreePort();
+        request.launchOptions.cdpPort = cdpPort;
+        const info = {
+            browserType: request.browserType,
+            userDataDir: request.userDataDir,
+            cdpPort,
+            launchOptions: request.launchOptions,
+            contextOptions: request.contextOptions,
+        };
+        const browserType = playwright[request.browserType];
+        const { browser, error } = await browserType.launchPersistentContext(request.userDataDir, {
+            ...request.launchOptions,
+            ...request.contextOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).then(context => {
+            return { browser: context.browser(), error: undefined };
+        }).catch(error => {
+            return { browser: undefined, error: error.message };
+        });
+        this._setEntries([...this._entries, {
+                browser,
+                info: {
+                    browserType: request.browserType,
+                    userDataDir: request.userDataDir,
+                    cdpPort,
+                    launchOptions: request.launchOptions,
+                    contextOptions: request.contextOptions,
+                    error,
+                },
+            }]);
+        browser?.on('disconnected', () => {
+            this._setEntries(this._entries.filter(entry => entry.browser !== browser));
+        });
+        return info;
+    }
+    _updateReport() {
+        // Clear the current line and move cursor to top of screen
+        process.stdout.write('\x1b[2J\x1b[H');
+        process.stdout.write(`Browser Server v${packageJSON.version}\n`);
+        process.stdout.write(`Listening on ${this._server.urlPrefix('human-readable')}\n\n`);
+        if (this._entries.length === 0) {
+            process.stdout.write('No browsers currently running\n');
+            return;
+        }
+        process.stdout.write('Running browsers:\n');
+        for (const entry of this._entries) {
+            const status = entry.browser ? 'running' : 'error';
+            const statusColor = entry.browser ? '\x1b[32m' : '\x1b[31m'; // green for running, red for error
+            process.stdout.write(`${statusColor}${entry.info.browserType}\x1b[0m (${entry.info.userDataDir}) - ${statusColor}${status}\x1b[0m\n`);
+            if (entry.info.error)
+                process.stdout.write(`  Error: ${entry.info.error}\n`);
+        }
+    }
+    _setEntries(entries) {
+        this._entries = entries;
+        this._updateReport();
+    }
+    _setupExitHandler() {
+        let isExiting = false;
+        const handleExit = async () => {
+            if (isExiting)
+                return;
+            isExiting = true;
+            setTimeout(() => process.exit(0), 15000);
+            for (const entry of this._entries)
+                await entry.browser?.close().catch(() => { });
+            process.exit(0);
+        };
+        process.stdin.on('close', handleExit);
+        process.on('SIGINT', handleExit);
+        process.on('SIGTERM', handleExit);
+    }
+}
+program
+    .name('browser-agent')
+    .option('-p, --port <port>', 'Port to listen on', '9224')
+    .action(async (options) => {
+    await main(options);
+});
+void program.parseAsync(process.argv);
+async function main(options) {
+    const server = new BrowserServer();
+    await server.start(+options.port);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => resolve(JSON.parse(Buffer.concat(chunks).toString())));
+    });
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}