@roxybrowser/playwright-mcp 0.0.1

package/lib/tools/utils.js

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+// @ts-ignore
+import { asLocator } from 'playwright-core/lib/utils';
+export async function waitForCompletion(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 tab.waitForTimeout(1000);
+        return result;
+    }
+    finally {
+        dispose();
+    }
+}
+export async function generateLocator(locator) {
+    try {
+        const { resolvedSelector } = await locator._resolveSelector();
+        return asLocator('javascript', resolvedSelector);
+    }
+    catch (e) {
+        throw new Error('Ref not found, likely because element was removed. Use browser_snapshot to see what elements are currently on the page.');
+    }
+}
+export async function callOnPageNoTrace(page, callback) {
+    return await page._wrapApiCall(() => callback(page), { internal: true });
+}

package/lib/tools/wait.js

@@ -0,0 +1,55 @@
+/**
+ * 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 wait = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_wait_for',
+        title: 'Wait for',
+        description: 'Wait for text to appear or disappear or a specified time to pass',
+        inputSchema: z.object({
+            time: z.number().optional().describe('The time to wait in seconds'),
+            text: z.string().optional().describe('The text to wait for'),
+            textGone: z.string().optional().describe('The text to wait for to disappear'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        if (!params.text && !params.textGone && !params.time)
+            throw new Error('Either time, text or textGone must be provided');
+        if (params.time) {
+            response.addCode(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
+            await new Promise(f => setTimeout(f, Math.min(30000, params.time * 1000)));
+        }
+        const tab = context.currentTabOrDie();
+        const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
+        const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
+        if (goneLocator) {
+            response.addCode(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+            await goneLocator.waitFor({ state: 'hidden' });
+        }
+        if (locator) {
+            response.addCode(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+            await locator.waitFor({ state: 'visible' });
+        }
+        response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+        response.setIncludeSnapshot();
+    },
+});
+export default [
+    wait,
+];

package/lib/tools.js

@@ -0,0 +1,52 @@
+/**
+ * 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 common from './tools/common.js';
+import console from './tools/console.js';
+import dialogs from './tools/dialogs.js';
+import evaluate from './tools/evaluate.js';
+import files from './tools/files.js';
+import install from './tools/install.js';
+import keyboard from './tools/keyboard.js';
+import navigate from './tools/navigate.js';
+import network from './tools/network.js';
+import pdf from './tools/pdf.js';
+import snapshot from './tools/snapshot.js';
+import tabs from './tools/tabs.js';
+import screenshot from './tools/screenshot.js';
+import wait from './tools/wait.js';
+import mouse from './tools/mouse.js';
+import roxy from './tools/roxy.js';
+export const allTools = [
+    ...common,
+    ...console,
+    ...dialogs,
+    ...evaluate,
+    ...files,
+    ...install,
+    ...keyboard,
+    ...navigate,
+    ...network,
+    ...mouse,
+    ...pdf,
+    ...roxy,
+    ...screenshot,
+    ...snapshot,
+    ...tabs,
+    ...wait,
+];
+export function filteredTools(config) {
+    return allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));
+}

package/lib/utils/codegen.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/utils/fileUtils.js

@@ -0,0 +1,36 @@
+/**
+ * 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, 'ms-playwright');
+}
+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));
+}

package/lib/utils/guid.js

@@ -0,0 +1,22 @@
+/**
+ * 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 crypto from 'crypto';
+export function createGuid() {
+    return crypto.randomBytes(16).toString('hex');
+}
+export function createHash(data) {
+    return crypto.createHash('sha256').update(data).digest('hex').slice(0, 7);
+}

package/lib/utils/log.js

@@ -0,0 +1,21 @@
+/**
+ * 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';
+const errorsDebug = debug('pw:mcp:errors');
+export function logUnhandledError(error) {
+    errorsDebug(error);
+}
+export const testDebug = debug('pw:mcp:test');

package/lib/utils/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');
+}

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

package/lib/vscode/host.js

@@ -0,0 +1,128 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { logUnhandledError } from '../utils/log.js';
+import { packageJSON } from '../utils/package.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import { contextFactory } from '../browserContextFactory.js';
+const contextSwitchOptions = z.object({
+    connectionString: z.string().optional().describe('The connection string to use to connect to the browser'),
+    lib: z.string().optional().describe('The library to use for the connection'),
+});
+class VSCodeProxyBackend {
+    _config;
+    _defaultTransportFactory;
+    name = 'Playwright MCP Client Switcher';
+    version = packageJSON.version;
+    _currentClient;
+    _contextSwitchTool;
+    _roots = [];
+    _clientVersion;
+    constructor(_config, _defaultTransportFactory) {
+        this._config = _config;
+        this._defaultTransportFactory = _defaultTransportFactory;
+        this._contextSwitchTool = this._defineContextSwitchTool();
+    }
+    async initialize(clientVersion, roots) {
+        this._clientVersion = clientVersion;
+        this._roots = roots;
+        const transport = await this._defaultTransportFactory();
+        await this._setCurrentClient(transport);
+    }
+    async listTools() {
+        const response = await this._currentClient.listTools();
+        return [
+            ...response.tools,
+            this._contextSwitchTool,
+        ];
+    }
+    async callTool(name, args) {
+        if (name === this._contextSwitchTool.name)
+            return this._callContextSwitchTool(args);
+        return await this._currentClient.callTool({
+            name,
+            arguments: args,
+        });
+    }
+    serverClosed() {
+        void this._currentClient?.close().catch(logUnhandledError);
+    }
+    async _callContextSwitchTool(params) {
+        if (!params.connectionString || !params.lib) {
+            const transport = await this._defaultTransportFactory();
+            await this._setCurrentClient(transport);
+            return {
+                content: [{ type: 'text', text: '### Result\nSuccessfully disconnected.\n' }],
+            };
+        }
+        await this._setCurrentClient(new StdioClientTransport({
+            command: process.execPath,
+            cwd: process.cwd(),
+            args: [
+                path.join(fileURLToPath(import.meta.url), '..', 'main.js'),
+                JSON.stringify(this._config),
+                params.connectionString,
+                params.lib,
+            ],
+        }));
+        return {
+            content: [{ type: 'text', text: '### Result\nSuccessfully connected.\n' }],
+        };
+    }
+    _defineContextSwitchTool() {
+        return {
+            name: 'browser_connect',
+            description: 'Do not call, this tool is used in the integration with the Playwright VS Code Extension and meant for programmatic usage only.',
+            inputSchema: zodToJsonSchema(contextSwitchOptions, { strictUnions: true }),
+            annotations: {
+                title: 'Connect to a browser running in VS Code.',
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+        };
+    }
+    async _setCurrentClient(transport) {
+        await this._currentClient?.close();
+        this._currentClient = undefined;
+        const client = new Client(this._clientVersion);
+        client.registerCapabilities({
+            roots: {
+                listRoots: true,
+            },
+        });
+        client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: this._roots }));
+        client.setRequestHandler(PingRequestSchema, () => ({}));
+        await client.connect(transport);
+        this._currentClient = client;
+    }
+}
+export async function runVSCodeTools(config) {
+    const serverBackendFactory = {
+        name: 'Playwright w/ vscode',
+        nameInConfig: 'playwright-vscode',
+        version: packageJSON.version,
+        create: () => new VSCodeProxyBackend(config, () => mcpServer.wrapInProcess(new BrowserServerBackend(config, contextFactory(config))))
+    };
+    await mcpServer.start(serverBackendFactory, config.server);
+    return;
+}

package/lib/vscode/main.js

@@ -0,0 +1,62 @@
+/**
+ * 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 { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as mcpServer from '../mcp/server.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+class VSCodeBrowserContextFactory {
+    _config;
+    _playwright;
+    _connectionString;
+    name = 'vscode';
+    description = 'Connect to a browser running in the Playwright VS Code extension';
+    constructor(_config, _playwright, _connectionString) {
+        this._config = _config;
+        this._playwright = _playwright;
+        this._connectionString = _connectionString;
+    }
+    async createContext(clientInfo, abortSignal) {
+        let launchOptions = this._config.browser.launchOptions;
+        if (this._config.browser.userDataDir) {
+            launchOptions = {
+                ...launchOptions,
+                ...this._config.browser.contextOptions,
+                userDataDir: this._config.browser.userDataDir,
+            };
+        }
+        const connectionString = new URL(this._connectionString);
+        connectionString.searchParams.set('launch-options', JSON.stringify(launchOptions));
+        const browserType = this._playwright.chromium; // it could also be firefox or webkit, we just need some browser type to call `connect` on
+        const browser = await browserType.connect(connectionString.toString());
+        const context = browser.contexts()[0] ?? await browser.newContext(this._config.browser.contextOptions);
+        return {
+            browserContext: context,
+            close: async () => {
+                await browser.close();
+            }
+        };
+    }
+}
+async function main(config, connectionString, lib) {
+    const playwright = await import(lib).then(mod => mod.default ?? mod);
+    const factory = new VSCodeBrowserContextFactory(config, playwright, connectionString);
+    await mcpServer.connect({
+        name: 'Playwright MCP',
+        nameInConfig: 'playwright-vscode',
+        create: () => new BrowserServerBackend(config, factory),
+        version: 'unused'
+    }, new StdioServerTransport(), false);
+}
+await main(JSON.parse(process.argv[2]), process.argv[3], process.argv[4]);