@andrew-chen-wang/camoufox-mcp 0.0.1

package/lib/context.js

@@ -0,0 +1,361 @@
+/**
+ * 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 debug from 'debug';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
+import { ManualPromise } from './manualPromise.js';
+import { Tab } from './tab.js';
+import { outputFile } from './config.js';
+const testDebug = debug('pw:mcp:test');
+export class Context {
+    tools;
+    config;
+    _browserContextPromise;
+    _browserContextFactory;
+    _tabs = [];
+    _currentTab;
+    _modalStates = [];
+    _pendingAction;
+    _downloads = [];
+    _routeRules = [];
+    _networkOffline = false;
+    _tracingActive = false;
+    clientVersion;
+    constructor(tools, config, browserContextFactory) {
+        this.tools = tools;
+        this.config = config;
+        this._browserContextFactory = browserContextFactory;
+        testDebug('create context');
+    }
+    clientSupportsImages() {
+        if (this.config.imageResponses === 'allow')
+            return true;
+        if (this.config.imageResponses === 'omit')
+            return false;
+        return !this.clientVersion?.name.includes('cursor');
+    }
+    modalStates() {
+        return this._modalStates;
+    }
+    setModalState(modalState, inTab) {
+        this._modalStates.push({ ...modalState, tab: inTab });
+    }
+    clearModalState(modalState) {
+        this._modalStates = this._modalStates.filter(state => state !== modalState);
+    }
+    modalStatesMarkdown() {
+        const result = ['### Modal state'];
+        if (this._modalStates.length === 0)
+            result.push('- There is no modal state present');
+        for (const state of this._modalStates) {
+            const tool = this.tools.find(tool => tool.clearsModalState === state.type);
+            result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
+        }
+        return result;
+    }
+    tabs() {
+        return this._tabs;
+    }
+    currentTabOrDie() {
+        if (!this._currentTab)
+            throw new Error('No current snapshot available. Capture a snapshot or navigate to a new location first.');
+        return this._currentTab;
+    }
+    async newTab() {
+        const { browserContext } = await this._ensureBrowserContext();
+        const page = await browserContext.newPage();
+        this._currentTab = this._tabs.find(t => t.page === page);
+        return this._currentTab;
+    }
+    async selectTab(index) {
+        this._currentTab = this._tabs[index - 1];
+        await this._currentTab.page.bringToFront();
+    }
+    async ensureTab() {
+        const { browserContext } = await this._ensureBrowserContext();
+        if (!this._currentTab)
+            await browserContext.newPage();
+        return this._currentTab;
+    }
+    async listTabsMarkdown() {
+        if (!this._tabs.length)
+            return '### No tabs open';
+        const lines = ['### Open tabs'];
+        for (let i = 0; i < this._tabs.length; i++) {
+            const tab = this._tabs[i];
+            const title = await tab.title();
+            const url = tab.page.url();
+            const current = tab === this._currentTab ? ' (current)' : '';
+            lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
+        }
+        return lines.join('\n');
+    }
+    async closeTab(index) {
+        const tab = index === undefined ? this._currentTab : this._tabs[index - 1];
+        await tab?.page.close();
+        return await this.listTabsMarkdown();
+    }
+    async run(tool, params) {
+        // Tab management is done outside of the action() call.
+        const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params || {}));
+        const { code, action, waitForNetwork, captureSnapshot, resultOverride } = toolResult;
+        const racingAction = action ? () => this._raceAgainstModalDialogs(action) : undefined;
+        if (resultOverride)
+            return resultOverride;
+        if (!this._currentTab) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'No open pages available. Use the "browser_navigate" tool to navigate to a page first.',
+                    }],
+            };
+        }
+        const tab = this.currentTabOrDie();
+        // TODO: race against modal dialogs to resolve clicks.
+        let actionResult;
+        try {
+            if (waitForNetwork)
+                actionResult = await waitForCompletion(this, tab, async () => racingAction?.()) ?? undefined;
+            else
+                actionResult = await racingAction?.() ?? undefined;
+        }
+        finally {
+            if (captureSnapshot && !this._javaScriptBlocked())
+                await tab.captureSnapshot();
+        }
+        const result = [];
+        result.push(`- Ran Playwright code:
+\`\`\`js
+${code.join('\n')}
+\`\`\`
+`);
+        if (this.modalStates().length) {
+            result.push(...this.modalStatesMarkdown());
+            return {
+                content: [{
+                        type: 'text',
+                        text: result.join('\n'),
+                    }],
+            };
+        }
+        if (this._downloads.length) {
+            result.push('', '### Downloads');
+            for (const entry of this._downloads) {
+                if (entry.finished)
+                    result.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+                else
+                    result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+            }
+            result.push('');
+        }
+        if (this.tabs().length > 1)
+            result.push(await this.listTabsMarkdown(), '');
+        if (this.tabs().length > 1)
+            result.push('### Current tab');
+        result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.title()}`);
+        if (captureSnapshot && tab.hasSnapshot())
+            result.push(tab.snapshotOrDie().text());
+        const content = actionResult?.content ?? [];
+        return {
+            content: [
+                ...content,
+                {
+                    type: 'text',
+                    text: result.join('\n'),
+                }
+            ],
+        };
+    }
+    async waitForTimeout(time) {
+        if (!this._currentTab || this._javaScriptBlocked()) {
+            await new Promise(f => setTimeout(f, time));
+            return;
+        }
+        await callOnPageNoTrace(this._currentTab.page, page => {
+            return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+        });
+    }
+    async _raceAgainstModalDialogs(action) {
+        this._pendingAction = {
+            dialogShown: new ManualPromise(),
+        };
+        let result;
+        try {
+            await Promise.race([
+                action().then(r => result = r),
+                this._pendingAction.dialogShown,
+            ]);
+        }
+        finally {
+            this._pendingAction = undefined;
+        }
+        return result;
+    }
+    _javaScriptBlocked() {
+        return this._modalStates.some(state => state.type === 'dialog');
+    }
+    dialogShown(tab, dialog) {
+        this.setModalState({
+            type: 'dialog',
+            description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+            dialog,
+        }, tab);
+        this._pendingAction?.dialogShown.resolve();
+    }
+    async downloadStarted(tab, download) {
+        const entry = {
+            download,
+            finished: false,
+            outputFile: await outputFile(this.config, download.suggestedFilename())
+        };
+        this._downloads.push(entry);
+        await download.saveAs(entry.outputFile);
+        entry.finished = true;
+    }
+    _onPageCreated(page) {
+        const tab = new Tab(this, page, tab => this._onPageClosed(tab));
+        this._tabs.push(tab);
+        if (!this._currentTab)
+            this._currentTab = tab;
+    }
+    _onPageClosed(tab) {
+        this._modalStates = this._modalStates.filter(state => state.tab !== tab);
+        const index = this._tabs.indexOf(tab);
+        if (index === -1)
+            return;
+        this._tabs.splice(index, 1);
+        if (this._currentTab === tab)
+            this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
+        if (!this._tabs.length)
+            void this.close();
+    }
+    async close() {
+        if (!this._browserContextPromise)
+            return;
+        testDebug('close context');
+        const promise = this._browserContextPromise;
+        this._browserContextPromise = undefined;
+        await promise.then(async ({ browserContext, close }) => {
+            if (this._tracingActive)
+                await browserContext.tracing.stop();
+            this._tracingActive = false;
+            await close();
+        });
+    }
+    async _setupRequestInterception(context) {
+        await context.setOffline(this._networkOffline);
+        if (this.config.network?.allowedOrigins?.length) {
+            await context.route('**', route => route.abort('blockedbyclient'));
+            for (const origin of this.config.network.allowedOrigins)
+                await context.route(`*://${origin}/**`, route => route.continue());
+        }
+        if (this.config.network?.blockedOrigins?.length) {
+            for (const origin of this.config.network.blockedOrigins)
+                await context.route(`*://${origin}/**`, route => route.abort('blockedbyclient'));
+        }
+        for (const rule of this._routeRules) {
+            await context.route(rule.pattern, rule.handler);
+            rule.remove = () => {
+                void context.unroute(rule.pattern, rule.handler).catch(() => { });
+            };
+        }
+    }
+    _ensureBrowserContext() {
+        if (!this._browserContextPromise) {
+            this._browserContextPromise = this._setupBrowserContext();
+            this._browserContextPromise.catch(() => {
+                this._browserContextPromise = undefined;
+            });
+        }
+        return this._browserContextPromise;
+    }
+    async _setupBrowserContext() {
+        // TODO: move to the browser context factory to make it based on isolation mode.
+        const result = await this._browserContextFactory.createContext();
+        const { browserContext } = result;
+        await this._setupRequestInterception(browserContext);
+        for (const page of browserContext.pages())
+            this._onPageCreated(page);
+        browserContext.on('page', page => this._onPageCreated(page));
+        if (this.config.saveTrace) {
+            await browserContext.tracing.start({
+                name: 'trace',
+                screenshots: false,
+                snapshots: true,
+                sources: false,
+            });
+            this._tracingActive = true;
+        }
+        return result;
+    }
+    async browserContext() {
+        const { browserContext } = await this._ensureBrowserContext();
+        return browserContext;
+    }
+    hasBrowserContext() {
+        return !!this._browserContextPromise;
+    }
+    async addRouteRule(pattern, handler) {
+        const rule = { pattern, handler };
+        this._routeRules.push(rule);
+        if (this._browserContextPromise) {
+            const browserContext = await this.browserContext();
+            await browserContext.route(pattern, handler);
+            rule.remove = () => {
+                void browserContext.unroute(pattern, handler).catch(() => { });
+            };
+        }
+    }
+    listRouteRules() {
+        return this._routeRules.map(rule => rule.pattern);
+    }
+    async removeRouteRule(pattern) {
+        const rules = pattern ? this._routeRules.filter(rule => rule.pattern === pattern) : [...this._routeRules];
+        for (const rule of rules)
+            rule.remove?.();
+        this._routeRules = pattern ? this._routeRules.filter(rule => rule.pattern !== pattern) : [];
+    }
+    async setNetworkOffline(offline) {
+        this._networkOffline = offline;
+        if (this._browserContextPromise) {
+            const browserContext = await this.browserContext();
+            await browserContext.setOffline(offline);
+        }
+    }
+    async startTracing() {
+        const browserContext = await this.browserContext();
+        if (this._tracingActive)
+            throw new Error('Tracing is already active.');
+        await browserContext.tracing.start({
+            name: 'trace',
+            screenshots: false,
+            snapshots: true,
+            sources: false,
+        });
+        this._tracingActive = true;
+    }
+    async stopTracing(filename) {
+        const browserContext = await this.browserContext();
+        if (!this._tracingActive)
+            throw new Error('Tracing is not active.');
+        const tracePath = filename ? await outputFile(this.config, filename) : await outputFile(this.config, `trace-${new Date().toISOString()}.zip`);
+        await browserContext.tracing.stop({ path: tracePath });
+        this._tracingActive = false;
+        return tracePath;
+    }
+    tracingActive() {
+        return this._tracingActive;
+    }
+}

package/lib/fileUtils.js

@@ -0,0 +1,32 @@
+/**
+ * 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 os from 'node:os';
+import path from 'node:path';
+export function cacheDir() {
+    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);
+    return path.join(cacheDirectory, 'camoufox-mcp');
+}
+export async function userDataDir(browserConfig) {
+    return path.join(cacheDir(), `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
+}

package/lib/index.js

@@ -0,0 +1,66 @@
+/**
+ * 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 as createConnectionImpl } from './connection.js';
+import { createMCPHTTPServer } from './mcpHttpServer.js';
+import { resolveConfig } from './config.js';
+import { contextFactory } from './browserContextFactory.js';
+export async function createConnection(userConfig = {}, contextGetter) {
+    const config = await resolveConfig(userConfig);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
+    const connection = createConnectionImpl(config, factory);
+    return bindConnectionLifecycle(connection);
+}
+export { createMCPHTTPServer };
+class SimpleBrowserContextFactory {
+    _contextGetter;
+    constructor(contextGetter) {
+        this._contextGetter = contextGetter;
+    }
+    async createContext() {
+        const browserContext = await this._contextGetter();
+        return {
+            browserContext,
+            close: () => browserContext.close()
+        };
+    }
+}
+function bindConnectionLifecycle(connection) {
+    const server = connection.server;
+    const originalConnect = server.connect.bind(server);
+    const originalClose = server.close.bind(server);
+    let closed = false;
+    const closeConnection = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await originalClose();
+        await connection.context.close();
+    };
+    server.close = closeConnection;
+    server.connect = async (transport) => {
+        const previousOnClose = transport.onclose;
+        transport.onclose = async () => {
+            try {
+                await previousOnClose?.();
+            }
+            finally {
+                await closeConnection();
+            }
+        };
+        await originalConnect(transport);
+    };
+    return server;
+}

package/lib/javascript.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+// adapted from:
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/utils/isomorphic/stringUtils.ts
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/server/codegen/javascript.ts
+// NOTE: this function should not be used to escape any selectors.
+export function escapeWithQuotes(text, char = '\'') {
+    const stringified = JSON.stringify(text);
+    const escapedText = stringified.substring(1, stringified.length - 1).replace(/\\"/g, '"');
+    if (char === '\'')
+        return char + escapedText.replace(/[']/g, '\\\'') + char;
+    if (char === '"')
+        return char + escapedText.replace(/["]/g, '\\"') + char;
+    if (char === '`')
+        return char + escapedText.replace(/[`]/g, '`') + char;
+    throw new Error('Invalid escape char');
+}
+export function quote(text) {
+    return escapeWithQuotes(text, '\'');
+}
+export function formatObject(value, indent = '  ') {
+    if (typeof value === 'string')
+        return quote(value);
+    if (Array.isArray(value))
+        return `[${value.map(o => formatObject(o)).join(', ')}]`;
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+        if (!keys.length)
+            return '{}';
+        const tokens = [];
+        for (const key of keys)
+            tokens.push(`${key}: ${formatObject(value[key])}`);
+        return `{\n${indent}${tokens.join(`,\n${indent}`)}\n}`;
+    }
+    return String(value);
+}

package/lib/manualPromise.js

@@ -0,0 +1,111 @@
+/**
+ * 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 class ManualPromise extends Promise {
+    _resolve;
+    _reject;
+    _isDone;
+    constructor() {
+        let resolve;
+        let reject;
+        super((f, r) => {
+            resolve = f;
+            reject = r;
+        });
+        this._isDone = false;
+        this._resolve = resolve;
+        this._reject = reject;
+    }
+    isDone() {
+        return this._isDone;
+    }
+    resolve(t) {
+        this._isDone = true;
+        this._resolve(t);
+    }
+    reject(e) {
+        this._isDone = true;
+        this._reject(e);
+    }
+    static get [Symbol.species]() {
+        return Promise;
+    }
+    get [Symbol.toStringTag]() {
+        return 'ManualPromise';
+    }
+}
+export class LongStandingScope {
+    _terminateError;
+    _closeError;
+    _terminatePromises = new Map();
+    _isClosed = false;
+    reject(error) {
+        this._isClosed = true;
+        this._terminateError = error;
+        for (const p of this._terminatePromises.keys())
+            p.resolve(error);
+    }
+    close(error) {
+        this._isClosed = true;
+        this._closeError = error;
+        for (const [p, frames] of this._terminatePromises)
+            p.resolve(cloneError(error, frames));
+    }
+    isClosed() {
+        return this._isClosed;
+    }
+    static async raceMultiple(scopes, promise) {
+        return Promise.race(scopes.map(s => s.race(promise)));
+    }
+    async race(promise) {
+        return this._race(Array.isArray(promise) ? promise : [promise], false);
+    }
+    async safeRace(promise, defaultValue) {
+        return this._race([promise], true, defaultValue);
+    }
+    async _race(promises, safe, defaultValue) {
+        const terminatePromise = new ManualPromise();
+        const frames = captureRawStack();
+        if (this._terminateError)
+            terminatePromise.resolve(this._terminateError);
+        if (this._closeError)
+            terminatePromise.resolve(cloneError(this._closeError, frames));
+        this._terminatePromises.set(terminatePromise, frames);
+        try {
+            return await Promise.race([
+                terminatePromise.then(e => safe ? defaultValue : Promise.reject(e)),
+                ...promises
+            ]);
+        }
+        finally {
+            this._terminatePromises.delete(terminatePromise);
+        }
+    }
+}
+function cloneError(error, frames) {
+    const clone = new Error();
+    clone.name = error.name;
+    clone.message = error.message;
+    clone.stack = [error.name + ':' + error.message, ...frames].join('\n');
+    return clone;
+}
+function captureRawStack() {
+    const stackTraceLimit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 50;
+    const error = new Error();
+    const stack = error.stack || '';
+    Error.stackTraceLimit = stackTraceLimit;
+    return stack.split('\n');
+}