@andrew-chen-wang/camoufox-mcp 0.0.1

package/config.d.ts

@@ -0,0 +1,41 @@
+import type * as playwright from "playwright-core";
+export type ToolCapability =
+  | "core"
+  | "tabs"
+  | "pdf"
+  | "history"
+  | "wait"
+  | "files"
+  | "install"
+  | "testing";
+
+export type Config = {
+  browser?: {
+    browserAgent?: string;
+    browserName?: "chromium" | "firefox" | "webkit";
+    isolated?: boolean;
+    userDataDir?: string;
+    launchOptions?: playwright.LaunchOptions & Record<string, any>;
+    contextOptions?: playwright.BrowserContextOptions;
+    cdpEndpoint?: string;
+    remoteEndpoint?: string;
+  };
+  server?: {
+    port?: number;
+    host?: string;
+  };
+  capabilities?: ToolCapability[];
+  vision?: boolean;
+  saveTrace?: boolean;
+  saveVideo?: {
+    width: number;
+    height: number;
+  };
+  allowUnrestrictedFileAccess?: boolean;
+  outputDir?: string;
+  network?: {
+    allowedOrigins?: string[];
+    blockedOrigins?: string[];
+  };
+  imageResponses?: "allow" | "omit" | "auto";
+};

package/index.d.ts

@@ -0,0 +1,22 @@
+import type http from "node:http";
+
+import type { BrowserContext } from "playwright-core";
+import type { Config } from "./config.js";
+
+export type CreateMCPHTTPServerOptions = {
+  config?: Config;
+  headless?: boolean;
+  host?: string;
+  port?: number;
+};
+
+export declare function createConnection(
+  config?: Config,
+  contextGetter?: () => Promise<BrowserContext>,
+): Promise<import("@modelcontextprotocol/sdk/server/index.js").Server>;
+
+export declare function createMCPHTTPServer(
+  options?: CreateMCPHTTPServerOptions,
+): Promise<http.Server>;
+
+export type { Config } from "./config.js";

package/index.js

@@ -0,0 +1 @@
+export { createConnection, createMCPHTTPServer } from "./lib/index.js";

package/lib/browserContextFactory.js

@@ -0,0 +1,178 @@
+/**
+ * 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 os from 'node:os';
+import path from 'node:path';
+import debug from 'debug';
+import { launchOptions as createCamoufoxLaunchOptions } from 'camoufox-js';
+import { firefox } from 'playwright-core';
+const testDebug = debug('camoufox: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);
+    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() {
+        return firefox.launch({
+            ...(await toCamoufoxLaunchOptions(this.browserConfig)),
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).catch(error => {
+            if (String(error.message).includes('Executable doesn\'t exist'))
+                throw new Error('Camoufox is not installed. Run `npx camoufox-js fetch` and retry.');
+            throw error;
+        });
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext(this.browserConfig.contextOptions);
+    }
+}
+class CdpContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('cdp', browserConfig);
+    }
+    async _doObtainBrowser() {
+        throw new Error('camoufox-mcp does not support cdpEndpoint because Camoufox is Firefox-based.');
+    }
+    async _doCreateContext() {
+        throw new Error('Not implemented');
+    }
+}
+class RemoteContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('remote', browserConfig);
+    }
+    async _doObtainBrowser() {
+        return firefox.connect(this.browserConfig.remoteEndpoint);
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext(this.browserConfig.contextOptions);
+    }
+}
+class PersistentContextFactory {
+    browserConfig;
+    _userDataDirs = new Set();
+    constructor(browserConfig) {
+        this.browserConfig = browserConfig;
+    }
+    async createContext() {
+        testDebug('create browser context (persistent)');
+        const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+        this._userDataDirs.add(userDataDir);
+        testDebug('lock user data dir', userDataDir);
+        for (let i = 0; i < 5; i++) {
+            try {
+                const browserContext = await firefox.launchPersistentContext(userDataDir, {
+                    ...(await toCamoufoxLaunchOptions(this.browserConfig)),
+                    ...this.browserConfig.contextOptions,
+                    handleSIGINT: false,
+                    handleSIGTERM: false,
+                });
+                const close = () => this._closeBrowserContext(browserContext, userDataDir);
+                return { browserContext, close };
+            }
+            catch (error) {
+                if (String(error.message).includes('Executable doesn\'t exist'))
+                    throw new Error('Camoufox is not installed. Run `npx camoufox-js fetch` and retry.');
+                if (String(error.message).includes('ProcessSingleton') || String(error.message).includes('Invalid URL')) {
+                    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, 'camoufox-mcp', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+        await fs.promises.mkdir(result, { recursive: true });
+        return result;
+    }
+}
+async function toCamoufoxLaunchOptions(browserConfig) {
+    return createCamoufoxLaunchOptions({
+        ...browserConfig.launchOptions,
+    });
+}

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-core';
+import { sanitizeForFilePath } from './tools/utils.js';
+const defaultConfig = {
+    browser: {
+        browserName: 'firefox',
+        launchOptions: {
+            headless: os.platform() === 'linux' && !process.env.DISPLAY,
+        },
+        contextOptions: {
+            viewport: null,
+        },
+    },
+    network: {
+        allowedOrigins: undefined,
+        blockedOrigins: undefined,
+    },
+    server: {},
+    outputDir: path.join(os.tmpdir(), 'camoufox-mcp-output', sanitizeForFilePath(new Date().toISOString())),
+};
+export async function resolveConfig(config) {
+    return finalizeConfig(mergeConfig(defaultConfig, config));
+}
+export async function resolveCLIConfig(cliOptions) {
+    const configInFile = await loadConfig(cliOptions.config);
+    const cliOverrides = await configFromCLIOptions(cliOptions);
+    return finalizeConfig(mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides));
+}
+export function validateConfig(config) {
+    if (config.browser?.browserName && config.browser.browserName !== 'firefox')
+        throw new Error(`camoufox-mcp only supports Firefox-compatible Camoufox browsers. Received "${config.browser.browserName}".`);
+    if (config.browser?.cdpEndpoint)
+        throw new Error('camoufox-mcp does not support cdpEndpoint because Camoufox is Firefox-based.');
+    if (config.browser?.browserAgent)
+        throw new Error('camoufox-mcp does not support browserAgent mode.');
+    if (config.extension)
+        throw new Error('camoufox-mcp does not support extension mode.');
+}
+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,
+    };
+    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,
+        saveVideo: undefined,
+    };
+    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 ?? 'firefox',
+        isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
+        launchOptions: {
+            ...pickDefined(base.browser?.launchOptions),
+            ...pickDefined(overrides.browser?.launchOptions),
+        },
+        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),
+        },
+    };
+}
+function finalizeConfig(config) {
+    if (config.saveTrace)
+        config.browser.launchOptions.tracesDir = path.join(config.outputDir, 'traces');
+    if (config.saveVideo) {
+        config.browser.contextOptions.recordVideo = {
+            dir: path.join(config.outputDir, 'videos'),
+            size: config.saveVideo,
+        };
+    }
+    return config;
+}

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: 'Camoufox', 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();
+    }
+}