@andrew-chen-wang/camoufox-mcp 0.0.1

package/lib/tools/storage.js

@@ -0,0 +1,344 @@
+/**
+ * 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 * as javascript from '../javascript.js';
+import { outputFile } from '../config.js';
+import { defineTool } from './tool.js';
+const storageState = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_storage_state',
+        title: 'Save storage state',
+        description: 'Save the current browser storage state to a file',
+        inputSchema: z.object({
+            filename: z.string().optional(),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        const browserContext = await context.browserContext();
+        const fileName = await outputFile(context.config, params.filename ?? `storage-state-${new Date().toISOString()}.json`);
+        return {
+            code: [`await context.storageState({ path: ${javascript.quote(fileName)} });`],
+            action: async () => {
+                await browserContext.storageState({ path: fileName });
+                return { content: [{ type: 'text', text: fileName }] };
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+const setStorageState = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_set_storage_state',
+        title: 'Load storage state',
+        description: 'Load browser storage state from a file',
+        inputSchema: z.object({
+            filename: z.string(),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => {
+        return {
+            code: [`// Load storage state from ${params.filename}`],
+            action: async () => {
+                const browserContext = await context.browserContext();
+                const page = context.currentTabOrDie().page;
+                const state = JSON.parse(await fs.readFile(params.filename, 'utf8'));
+                await browserContext.clearCookies();
+                if (state.cookies?.length)
+                    await browserContext.addCookies(state.cookies);
+                for (const originState of state.origins ?? []) {
+                    await page.goto(originState.origin, { waitUntil: 'domcontentloaded' });
+                    await page.evaluate(entries => {
+                        localStorage.clear();
+                        for (const entry of entries)
+                            localStorage.setItem(entry.name, entry.value);
+                    }, originState.localStorage);
+                }
+            },
+            captureSnapshot: true,
+            waitForNetwork: true,
+        };
+    },
+});
+const cookieList = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_cookie_list',
+        title: 'List cookies',
+        description: 'List cookies for the current browser context',
+        inputSchema: z.object({
+            domain: z.string().optional(),
+            path: z.string().optional(),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to list cookies>'],
+        action: async () => {
+            const browserContext = await context.browserContext();
+            const cookies = (await browserContext.cookies()).filter(cookie => {
+                if (params.domain && cookie.domain !== params.domain)
+                    return false;
+                if (params.path && cookie.path !== params.path)
+                    return false;
+                return true;
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(cookies, null, 2) }] };
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const cookieGet = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_cookie_get',
+        title: 'Get cookie',
+        description: 'Get a cookie by name',
+        inputSchema: z.object({
+            name: z.string(),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to get cookie>'],
+        action: async () => {
+            const browserContext = await context.browserContext();
+            const cookie = (await browserContext.cookies()).find(entry => entry.name === params.name);
+            return { content: [{ type: 'text', text: JSON.stringify(cookie ?? null, null, 2) }] };
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const cookieSet = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_cookie_set',
+        title: 'Set cookie',
+        description: 'Set a cookie in the current browser context',
+        inputSchema: z.object({
+            name: z.string(),
+            value: z.string(),
+            domain: z.string().optional(),
+            path: z.string().optional(),
+            expires: z.number().optional(),
+            httpOnly: z.boolean().optional(),
+            secure: z.boolean().optional(),
+            sameSite: z.enum(['Strict', 'Lax', 'None']).optional(),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to set cookie>'],
+        action: async () => {
+            const browserContext = await context.browserContext();
+            const pageUrl = context.currentTabOrDie().page.url();
+            const cookie = {
+                ...params,
+            };
+            if (!cookie.domain) {
+                if (!/^https?:/.test(pageUrl))
+                    throw new Error('cookie domain is required when the current page does not have an http(s) URL.');
+                cookie.url = pageUrl;
+            }
+            await browserContext.addCookies([cookie]);
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const cookieDelete = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_cookie_delete',
+        title: 'Delete cookie',
+        description: 'Delete a cookie by name',
+        inputSchema: z.object({
+            name: z.string(),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => ({
+        code: ['// <internal code to delete cookie>'],
+        action: async () => {
+            const browserContext = await context.browserContext();
+            const cookies = await browserContext.cookies();
+            const remaining = cookies.filter(cookie => cookie.name !== params.name);
+            await browserContext.clearCookies();
+            if (remaining.length)
+                await browserContext.addCookies(remaining.map(toSetCookie));
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+const cookieClear = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_cookie_clear',
+        title: 'Clear cookies',
+        description: 'Clear all cookies',
+        inputSchema: z.object({}),
+        type: 'destructive',
+    },
+    handle: async (context) => ({
+        code: ['// <internal code to clear cookies>'],
+        action: async () => {
+            const browserContext = await context.browserContext();
+            await browserContext.clearCookies();
+        },
+        captureSnapshot: false,
+        waitForNetwork: false,
+    }),
+});
+function createWebStorageTools(kind) {
+    const prefix = kind === 'localStorage' ? 'browser_localstorage_' : 'browser_sessionstorage_';
+    const titlePrefix = kind === 'localStorage' ? 'localStorage' : 'sessionStorage';
+    const list = defineTool({
+        capability: 'core',
+        schema: {
+            name: `${prefix}list`,
+            title: `List ${titlePrefix}`,
+            description: `List all ${titlePrefix} key-value pairs`,
+            inputSchema: z.object({}),
+            type: 'readOnly',
+        },
+        handle: async (context) => ({
+            code: [`// <internal code to list ${titlePrefix}>`],
+            action: async () => {
+                const page = context.currentTabOrDie().page;
+                const result = await page.evaluate(storageKind => Object.fromEntries(Array.from(window[storageKind].entries())), kind);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        }),
+    });
+    const get = defineTool({
+        capability: 'core',
+        schema: {
+            name: `${prefix}get`,
+            title: `Get ${titlePrefix} item`,
+            description: `Get a ${titlePrefix} item by key`,
+            inputSchema: z.object({
+                key: z.string(),
+            }),
+            type: 'readOnly',
+        },
+        handle: async (context, params) => ({
+            code: [`// <internal code to get ${titlePrefix} item>`],
+            action: async () => {
+                const page = context.currentTabOrDie().page;
+                const value = await page.evaluate(({ storageKind, key }) => window[storageKind].getItem(key), { storageKind: kind, key: params.key });
+                return { content: [{ type: 'text', text: value ?? '' }] };
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        }),
+    });
+    const set = defineTool({
+        capability: 'core',
+        schema: {
+            name: `${prefix}set`,
+            title: `Set ${titlePrefix} item`,
+            description: `Set a ${titlePrefix} item`,
+            inputSchema: z.object({
+                key: z.string(),
+                value: z.string(),
+            }),
+            type: 'destructive',
+        },
+        handle: async (context, params) => ({
+            code: [`// <internal code to set ${titlePrefix} item>`],
+            action: async () => {
+                const page = context.currentTabOrDie().page;
+                await page.evaluate(({ storageKind, key, value }) => window[storageKind].setItem(key, value), { storageKind: kind, key: params.key, value: params.value });
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        }),
+    });
+    const del = defineTool({
+        capability: 'core',
+        schema: {
+            name: `${prefix}delete`,
+            title: `Delete ${titlePrefix} item`,
+            description: `Delete a ${titlePrefix} item`,
+            inputSchema: z.object({
+                key: z.string(),
+            }),
+            type: 'destructive',
+        },
+        handle: async (context, params) => ({
+            code: [`// <internal code to delete ${titlePrefix} item>`],
+            action: async () => {
+                const page = context.currentTabOrDie().page;
+                await page.evaluate(({ storageKind, key }) => window[storageKind].removeItem(key), { storageKind: kind, key: params.key });
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        }),
+    });
+    const clear = defineTool({
+        capability: 'core',
+        schema: {
+            name: `${prefix}clear`,
+            title: `Clear ${titlePrefix}`,
+            description: `Clear all ${titlePrefix}`,
+            inputSchema: z.object({}),
+            type: 'destructive',
+        },
+        handle: async (context) => ({
+            code: [`// <internal code to clear ${titlePrefix}>`],
+            action: async () => {
+                const page = context.currentTabOrDie().page;
+                await page.evaluate(storageKind => window[storageKind].clear(), kind);
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        }),
+    });
+    return [list, get, set, del, clear];
+}
+function toSetCookie(cookie) {
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+        path: cookie.path,
+        expires: cookie.expires,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite,
+    };
+}
+export default [
+    storageState,
+    setStorageState,
+    cookieList,
+    cookieGet,
+    cookieSet,
+    cookieDelete,
+    cookieClear,
+    ...createWebStorageTools('localStorage'),
+    ...createWebStorageTools('sessionStorage'),
+];

package/lib/tools/tabs.js

@@ -0,0 +1,172 @@
+/**
+ * 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 listTabs = defineTool({
+    capability: 'tabs',
+    schema: {
+        name: 'browser_tab_list',
+        title: 'List tabs',
+        description: 'List browser tabs',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context) => {
+        await context.ensureTab();
+        return {
+            code: [`// <internal code to list tabs>`],
+            captureSnapshot: false,
+            waitForNetwork: false,
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: await context.listTabsMarkdown(),
+                    }],
+            },
+        };
+    },
+});
+const selectTab = captureSnapshot => defineTool({
+    capability: 'tabs',
+    schema: {
+        name: 'browser_tab_select',
+        title: 'Select a tab',
+        description: 'Select a tab by index',
+        inputSchema: z.object({
+            index: z.number().describe('The index of the tab to select'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        await context.selectTab(params.index);
+        const code = [
+            `// <internal code to select tab ${params.index}>`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false
+        };
+    },
+});
+const newTab = captureSnapshot => defineTool({
+    capability: 'tabs',
+    schema: {
+        name: 'browser_tab_new',
+        title: 'Open a new tab',
+        description: 'Open a new tab',
+        inputSchema: z.object({
+            url: z.string().optional().describe('The URL to navigate to in the new tab. If not provided, the new tab will be blank.'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        await context.newTab();
+        if (params.url)
+            await context.currentTabOrDie().navigate(params.url);
+        const code = [
+            `// <internal code to open a new tab>`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false
+        };
+    },
+});
+const closeTab = captureSnapshot => defineTool({
+    capability: 'tabs',
+    schema: {
+        name: 'browser_tab_close',
+        title: 'Close a tab',
+        description: 'Close a tab',
+        inputSchema: z.object({
+            index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params) => {
+        await context.closeTab(params.index);
+        const code = [
+            `// <internal code to close tab ${params.index}>`,
+        ];
+        return {
+            code,
+            captureSnapshot,
+            waitForNetwork: false
+        };
+    },
+});
+const tabs = captureSnapshot => defineTool({
+    capability: 'tabs',
+    schema: {
+        name: 'browser_tabs',
+        title: 'Manage tabs',
+        description: 'List, create, select, or close browser tabs',
+        inputSchema: z.object({
+            action: z.enum(['list', 'new', 'select', 'close']),
+            index: z.number().optional().describe('Tab index for select/close actions'),
+            url: z.string().optional().describe('Optional URL for new tab'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        if (params.action === 'list') {
+            await context.ensureTab();
+            return {
+                code: ['// <internal code to list tabs>'],
+                captureSnapshot: false,
+                waitForNetwork: false,
+                resultOverride: {
+                    content: [{ type: 'text', text: await context.listTabsMarkdown() }],
+                },
+            };
+        }
+        if (params.action === 'new') {
+            await context.newTab();
+            if (params.url)
+                await context.currentTabOrDie().navigate(params.url);
+            return {
+                code: ['// <internal code to open a new tab>'],
+                captureSnapshot,
+                waitForNetwork: false,
+            };
+        }
+        if (params.action === 'select') {
+            if (params.index === undefined)
+                throw new Error('index is required when action is "select".');
+            await context.selectTab(params.index);
+            return {
+                code: [`// <internal code to select tab ${params.index}>`],
+                captureSnapshot,
+                waitForNetwork: false,
+            };
+        }
+        await context.closeTab(params.index);
+        return {
+            code: [`// <internal code to close tab ${params.index}>`],
+            captureSnapshot,
+            waitForNetwork: false,
+        };
+    },
+});
+export default (captureSnapshot) => [
+    tabs(captureSnapshot),
+    listTabs,
+    newTab(captureSnapshot),
+    selectTab(captureSnapshot),
+    closeTab(captureSnapshot),
+];

package/lib/tools/testing.js

@@ -0,0 +1,60 @@
+/**
+ * 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 generateTestSchema = z.object({
+    name: z.string().describe('The name of the test'),
+    description: z.string().describe('The description of the test'),
+    steps: z.array(z.string()).describe('The steps of the test'),
+});
+const generateTest = defineTool({
+    capability: 'testing',
+    schema: {
+        name: 'browser_generate_playwright_test',
+        title: 'Generate a Playwright test',
+        description: 'Generate a Playwright test for given scenario',
+        inputSchema: generateTestSchema,
+        type: 'readOnly',
+    },
+    handle: async (context, params) => {
+        return {
+            resultOverride: {
+                content: [{
+                        type: 'text',
+                        text: instructions(params),
+                    }],
+            },
+            code: [],
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+const instructions = (params) => [
+    `## Instructions`,
+    `- You are a playwright test generator.`,
+    `- You are given a scenario and you need to generate a playwright test for it.`,
+    '- DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided instead.',
+    '- Only after all steps are completed, emit a Playwright TypeScript test that uses @playwright/test based on message history',
+    '- Save generated test file in the tests directory',
+    `Test name: ${params.name}`,
+    `Description: ${params.description}`,
+    `Steps:`,
+    ...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
+].join('\n');
+export default [
+    generateTest,
+];

package/lib/tools/tool.js

@@ -0,0 +1,18 @@
+/**
+ * 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 function defineTool(tool) {
+    return tool;
+}

package/lib/tools/utils.js

@@ -0,0 +1,87 @@
+/**
+ * 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 async function waitForCompletion(context, tab, callback) {
+    const requests = new Set();
+    let frameNavigated = false;
+    let waitCallback = () => { };
+    const waitBarrier = new Promise(f => { waitCallback = f; });
+    const requestListener = (request) => requests.add(request);
+    const requestFinishedListener = (request) => {
+        requests.delete(request);
+        if (!requests.size)
+            waitCallback();
+    };
+    const frameNavigateListener = (frame) => {
+        if (frame.parentFrame())
+            return;
+        frameNavigated = true;
+        dispose();
+        clearTimeout(timeout);
+        void tab.waitForLoadState('load').then(waitCallback);
+    };
+    const onTimeout = () => {
+        dispose();
+        waitCallback();
+    };
+    tab.page.on('request', requestListener);
+    tab.page.on('requestfinished', requestFinishedListener);
+    tab.page.on('framenavigated', frameNavigateListener);
+    const timeout = setTimeout(onTimeout, 10000);
+    const dispose = () => {
+        tab.page.off('request', requestListener);
+        tab.page.off('requestfinished', requestFinishedListener);
+        tab.page.off('framenavigated', frameNavigateListener);
+        clearTimeout(timeout);
+    };
+    try {
+        const result = await callback();
+        if (!requests.size && !frameNavigated)
+            waitCallback();
+        await waitBarrier;
+        await context.waitForTimeout(1000);
+        return result;
+    }
+    finally {
+        dispose();
+    }
+}
+export function sanitizeForFilePath(s) {
+    const sanitize = (s) => s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+    const separator = s.lastIndexOf('.');
+    if (separator === -1)
+        return sanitize(s);
+    return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
+}
+export async function generateLocator(locator) {
+    try {
+        return await locator._generateLocatorString();
+    }
+    catch (e) {
+        if (e instanceof Error && /locator._generateLocatorString: Timeout .* exceeded/.test(e.message))
+            throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+        throw e;
+    }
+}
+export async function callOnPageNoTrace(page, callback) {
+    return await page._wrapApiCall(() => callback(page), { internal: true });
+}
+export function resolveLocator(tab, params) {
+    if (params.selector)
+        return params.element ? tab.page.locator(params.selector).describe(params.element) : tab.page.locator(params.selector);
+    if (params.ref)
+        return tab.snapshotOrDie().refLocator({ element: params.element ?? params.ref, ref: params.ref });
+    throw new Error('Either ref or selector must be provided.');
+}