@andrew-chen-wang/camoufox-mcp 0.0.1

package/lib/mcpHttpServer.js

@@ -0,0 +1,90 @@
+/**
+ * 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 http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createConnection } from './index.js';
+export async function createMCPHTTPServer(options = {}) {
+    const sessions = new Map();
+    const config = mergeConfig(options.config, options.headless);
+    const server = http.createServer((req, res) => {
+        void handleRequest(req, res, config, sessions);
+    });
+    await new Promise((resolve, reject) => {
+        server.on('error', reject);
+        server.listen(options.port ?? 0, options.host ?? '127.0.0.1', () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    const closeSessions = async () => {
+        await Promise.all([...sessions.values()].map(session => session.connection.close().catch(() => { })));
+        sessions.clear();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = ((callback) => {
+        void closeSessions().finally(() => {
+            server.closeAllConnections();
+            originalClose(callback);
+        });
+        return server;
+    });
+    const shutdown = () => {
+        void closeSessions().finally(() => {
+            server.closeAllConnections();
+            originalClose();
+        });
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    return server;
+}
+async function handleRequest(req, res, config, sessions) {
+    const sessionId = req.headers['mcp-session-id'];
+    const existingSession = sessionId ? sessions.get(sessionId) : undefined;
+    if (existingSession) {
+        await existingSession.transport.handleRequest(req, res);
+        return;
+    }
+    const connection = await createConnection(config);
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    transport.onclose = () => {
+        if (transport.sessionId) {
+            sessions.delete(transport.sessionId);
+            void connection.close().catch(() => { });
+        }
+    };
+    await connection.connect(transport);
+    await transport.handleRequest(req, res);
+    if (transport.sessionId)
+        sessions.set(transport.sessionId, { connection, transport });
+}
+function mergeConfig(config, headless) {
+    if (headless === undefined)
+        return config ?? {};
+    return {
+        ...config,
+        browser: {
+            ...config?.browser,
+            launchOptions: {
+                ...config?.browser?.launchOptions,
+                headless,
+            },
+        },
+    };
+}

package/lib/package.js

@@ -0,0 +1,20 @@
+/**
+ * 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 url from 'node:url';
+import path from 'node:path';
+const __filename = url.fileURLToPath(import.meta.url);
+export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/pageSnapshot.js

@@ -0,0 +1,44 @@
+/**
+ * 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 { callOnPageNoTrace } from './tools/utils.js';
+export class PageSnapshot {
+    _page;
+    _text;
+    constructor(page) {
+        this._page = page;
+    }
+    static async create(page) {
+        const snapshot = new PageSnapshot(page);
+        await snapshot._build();
+        return snapshot;
+    }
+    text() {
+        return this._text;
+    }
+    async _build() {
+        const snapshot = await callOnPageNoTrace(this._page, page => page._snapshotForAI());
+        const snapshotText = typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
+        this._text = [
+            `- Page Snapshot`,
+            '```yaml',
+            snapshotText,
+            '```',
+        ].join('\n');
+    }
+    refLocator(params) {
+        return this._page.locator(`aria-ref=${params.ref}`).describe(params.element);
+    }
+}

package/lib/resources/resource.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export {};

package/lib/server.js

@@ -0,0 +1,48 @@
+/**
+ * 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 './connection.js';
+import { contextFactory } from './browserContextFactory.js';
+export class Server {
+    config;
+    _connectionList = [];
+    _browserConfig;
+    _contextFactory;
+    constructor(config) {
+        this.config = config;
+        this._browserConfig = config.browser;
+        this._contextFactory = contextFactory(this._browserConfig);
+    }
+    async createConnection(transport) {
+        const connection = createConnection(this.config, this._contextFactory);
+        this._connectionList.push(connection);
+        await connection.server.connect(transport);
+        return connection;
+    }
+    setupExitWatchdog() {
+        let isExiting = false;
+        const handleExit = async () => {
+            if (isExiting)
+                return;
+            isExiting = true;
+            setTimeout(() => process.exit(0), 15000);
+            await Promise.all(this._connectionList.map(connection => connection.close()));
+            process.exit(0);
+        };
+        process.stdin.on('close', handleExit);
+        process.on('SIGINT', handleExit);
+        process.on('SIGTERM', handleExit);
+    }
+}

package/lib/tab.js

@@ -0,0 +1,107 @@
+/**
+ * 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 { PageSnapshot } from './pageSnapshot.js';
+import { callOnPageNoTrace } from './tools/utils.js';
+export class Tab {
+    context;
+    page;
+    _consoleMessages = [];
+    _requests = new Map();
+    _snapshot;
+    _onPageClose;
+    constructor(context, page, onPageClose) {
+        this.context = context;
+        this.page = page;
+        this._onPageClose = onPageClose;
+        page.on('console', event => this._consoleMessages.push(event));
+        page.on('request', request => this._requests.set(request, null));
+        page.on('response', response => this._requests.set(response.request(), response));
+        page.on('close', () => this._onClose());
+        page.on('filechooser', chooser => {
+            this.context.setModalState({
+                type: 'fileChooser',
+                description: 'File chooser',
+                fileChooser: chooser,
+            }, this);
+        });
+        page.on('dialog', dialog => this.context.dialogShown(this, dialog));
+        page.on('download', download => {
+            void this.context.downloadStarted(this, download);
+        });
+        page.setDefaultNavigationTimeout(60000);
+        page.setDefaultTimeout(5000);
+    }
+    _clearCollectedArtifacts() {
+        this._consoleMessages.length = 0;
+        this._requests.clear();
+    }
+    _onClose() {
+        this._clearCollectedArtifacts();
+        this._onPageClose(this);
+    }
+    async title() {
+        return await callOnPageNoTrace(this.page, page => page.title());
+    }
+    async waitForLoadState(state, options) {
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => { }));
+    }
+    async navigate(url) {
+        this._clearCollectedArtifacts();
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => { }));
+        try {
+            await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+        }
+        catch (_e) {
+            const e = _e;
+            const mightBeDownload = e.message.includes('net::ERR_ABORTED') // chromium
+                || e.message.includes('Download is starting'); // firefox + webkit
+            if (!mightBeDownload)
+                throw e;
+            // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
+            const download = await Promise.race([
+                downloadEvent,
+                new Promise(resolve => setTimeout(resolve, 1000)),
+            ]);
+            if (!download)
+                throw e;
+        }
+        // Cap load event to 5 seconds, the page is operational at this point.
+        await this.waitForLoadState('load', { timeout: 5000 });
+    }
+    hasSnapshot() {
+        return !!this._snapshot;
+    }
+    snapshotOrDie() {
+        if (!this._snapshot)
+            throw new Error('No snapshot available');
+        return this._snapshot;
+    }
+    consoleMessages() {
+        return this._consoleMessages;
+    }
+    clearConsoleMessages() {
+        this._consoleMessages.length = 0;
+    }
+    requests() {
+        return this._requests;
+    }
+    clearRequests() {
+        this._requests.clear();
+    }
+    async captureSnapshot() {
+        this._snapshot = await PageSnapshot.create(this.page);
+    }
+}

package/lib/tools/common.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { z } from 'zod';
+import { defineTool } from './tool.js';
+const close = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_close',
+        title: 'Close browser',
+        description: 'Close the page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => {
+        await context.close();
+        return {
+            code: [`await page.close()`],
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+const resize = captureSnapshot => defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_resize',
+        title: 'Resize browser window',
+        description: 'Resize the browser window',
+        inputSchema: z.object({
+            width: z.number().describe('Width of the browser window'),
+            height: z.number().describe('Height of the browser window'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        const tab = context.currentTabOrDie();
+        const code = [
+            `// Resize browser window to ${params.width}x${params.height}`,
+            `await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`
+        ];
+        const action = async () => {
+            await tab.page.setViewportSize({ width: params.width, height: params.height });
+        };
+        return {
+            code,
+            action,
+            captureSnapshot,
+            waitForNetwork: true
+        };
+    },
+});
+export default (captureSnapshot) => [
+    close,
+    resize(captureSnapshot)
+];

package/lib/tools/console.js

@@ -0,0 +1,77 @@
+/**
+ * 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 { z } from 'zod';
+import { defineTool } from './tool.js';
+const levels = ['debug', 'info', 'warning', 'error'];
+const levelWeight = {
+    debug: 0,
+    info: 1,
+    warning: 2,
+    error: 3,
+};
+const consoleMessages = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_console_messages',
+        title: 'Get console messages',
+        description: 'Returns all console messages',
+        inputSchema: z.object({
+            level: z.enum(levels).optional().describe('Minimum console level to include.'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        const messages = context.currentTabOrDie().consoleMessages().filter(message => {
+            const normalized = normalizeConsoleType(message.type());
+            const threshold = params.level ?? 'info';
+            return levelWeight[normalized] >= levelWeight[threshold];
+        });
+        const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).join('\n');
+        return {
+            code: ['// <internal code to get console messages>'],
+            action: async () => ({ content: [{ type: 'text', text: log }] }),
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+const consoleClear = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_console_clear',
+        title: 'Clear console messages',
+        description: 'Clear collected console messages',
+        inputSchema: z.object({}),
+        type: 'destructive',
+    },
+    handle: async (context) => {
+        context.currentTabOrDie().clearConsoleMessages();
+        return {
+            code: ['// <internal code to clear console messages>'],
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+function normalizeConsoleType(type) {
+    if (type === 'error' || type === 'warning' || type === 'info')
+        return type;
+    return 'debug';
+}
+export default [
+    consoleMessages,
+    consoleClear,
+];

package/lib/tools/devtools.js

@@ -0,0 +1,189 @@
+/**
+ * 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/promises';
+import { z } from 'zod';
+import { outputFile } from '../config.js';
+import { defineTool } from './tool.js';
+import { resolveLocator } from './utils.js';
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+const evaluate = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_evaluate',
+        title: 'Evaluate JavaScript',
+        description: 'Evaluate JavaScript expression on page or element',
+        inputSchema: z.object({
+            function: z.string(),
+            filename: z.string().optional(),
+            element: z.string().optional(),
+            ref: z.string().optional(),
+            selector: z.string().optional(),
+        }).refine(value => {
+            const targets = Number(!!value.ref) + Number(!!value.selector);
+            if (value.element)
+                return targets === 1;
+            return targets === 0;
+        }, {
+            message: 'Provide element with exactly one of ref or selector, or provide no target.',
+            path: ['ref'],
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to evaluate JavaScript>'],
+        action: async () => {
+            const page = context.currentTabOrDie().page;
+            const fn = new Function(`return (${params.function});`)();
+            const result = params.element
+                ? await resolveLocator(context.currentTabOrDie(), { element: params.element, ref: params.ref, selector: params.selector }).evaluate(fn)
+                : await page.evaluate(fn);
+            const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            if (params.filename) {
+                const fileName = await outputFile(context.config, params.filename);
+                await fs.writeFile(fileName, text, 'utf8');
+                return { content: [{ type: 'text', text: fileName }] };
+            }
+            return { content: [{ type: 'text', text }] };
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const runCode = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_run_code',
+        title: 'Run Playwright code',
+        description: 'Run a Playwright code snippet against the current page',
+        inputSchema: z.object({
+            code: z.string(),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to run Playwright snippet>'],
+        action: async () => {
+            const page = context.currentTabOrDie().page;
+            const fn = new AsyncFunction('page', `return (${params.code})(page);`);
+            const result = await fn(page);
+            if (result === undefined)
+                return;
+            return {
+                content: [{
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    }],
+            };
+        },
+        captureSnapshot: true,
+        waitForNetwork: true,
+    }),
+});
+const startTracing = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_start_tracing',
+        title: 'Start tracing',
+        description: 'Start Playwright tracing',
+        inputSchema: z.object({}),
+        type: 'destructive',
+    },
+    handle: async (context) => ({
+        code: ['// <internal code to start tracing>'],
+        action: async () => {
+            await context.startTracing();
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const stopTracing = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_stop_tracing',
+        title: 'Stop tracing',
+        description: 'Stop Playwright tracing and save the trace to a file',
+        inputSchema: z.object({
+            filename: z.string().optional(),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to stop tracing>'],
+        action: async () => {
+            const fileName = await context.stopTracing(params.filename);
+            return { content: [{ type: 'text', text: fileName }] };
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const getConfig = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_get_config',
+        title: 'Get config',
+        description: 'Return the resolved browser config',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => ({
+        code: ['// <internal code to get config>'],
+        action: async () => ({
+            content: [{ type: 'text', text: JSON.stringify(context.config, null, 2) }],
+        }),
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+function unsupportedTool(name, title, description) {
+    return defineTool({
+        capability: 'core',
+        schema: {
+            name,
+            title,
+            description,
+            inputSchema: z.object({
+                filename: z.string().optional(),
+                step: z.boolean().optional(),
+                location: z.string().optional(),
+            }).partial(),
+            type: 'readOnly',
+        },
+        handle: async () => ({
+            code: [`// ${name} is not supported in camoufox-mcp`],
+            captureSnapshot: false,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: `${name} is not supported by camoufox-mcp yet.`,
+                    }],
+                isError: true,
+            },
+        }),
+    });
+}
+export default [
+    evaluate,
+    runCode,
+    startTracing,
+    stopTracing,
+    getConfig,
+    unsupportedTool('browser_start_video', 'Start video', 'Start video recording'),
+    unsupportedTool('browser_stop_video', 'Stop video', 'Stop video recording'),
+    unsupportedTool('browser_resume', 'Resume debugger', 'Resume or step a paused debugging session'),
+];