@wordbricks/playwright-mcp 0.1.3

package/config.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 type * as playwright from 'playwright';
+
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
+
+export type Config = {
+  /**
+   * The browser to use.
+   */
+  browser?: {
+    /**
+     * The type of browser to use.
+     */
+    browserName?: 'chromium' | 'firefox' | 'webkit';
+
+    /**
+     * Keep the browser profile in memory, do not save it to disk.
+     */
+    isolated?: boolean;
+
+    /**
+     * Path to a user data directory for browser profile persistence.
+     * Temporary directory is created by default.
+     */
+    userDataDir?: string;
+
+    /**
+     * Launch options passed to
+     * @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
+     *
+     * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
+     */
+    launchOptions?: playwright.LaunchOptions;
+
+    /**
+     * Context options for the browser context.
+     *
+     * This is useful for settings options like `viewport`.
+     */
+    contextOptions?: playwright.BrowserContextOptions;
+
+    /**
+     * Chrome DevTools Protocol endpoint to connect to an existing browser instance in case of Chromium family browsers.
+     */
+    cdpEndpoint?: string;
+
+    /**
+     * Remote endpoint to connect to an existing Playwright server.
+     */
+    remoteEndpoint?: string;
+  },
+
+  server?: {
+    /**
+     * The port to listen on for SSE or MCP transport.
+     */
+    port?: number;
+
+    /**
+     * The host to bind the server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+     */
+    host?: string;
+  },
+
+  /**
+   * List of enabled tool capabilities. Possible values:
+   *   - 'core': Core browser automation features.
+   *   - 'pdf': PDF generation and manipulation.
+   *   - 'vision': Coordinate-based interactions.
+   */
+  capabilities?: ToolCapability[];
+
+  /**
+   * Whether to save the Playwright session into the output directory.
+   */
+  saveSession?: boolean;
+
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
+  /**
+   * The directory to save output files.
+   */
+  outputDir?: string;
+
+  network?: {
+    /**
+     * List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
+     */
+    blockedOrigins?: string[];
+  };
+
+  /**
+   * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
+   */
+  imageResponses?: 'allow' | 'omit';
+};

package/index.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * 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 type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Config } from './config.js';
+import type { BrowserContext } from 'playwright';
+
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
+export {};

package/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * 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 './lib/index.js';
+export { createConnection };

package/lib/browserContextFactory.js

@@ -0,0 +1,289 @@
+/**
+ * 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 net from 'net';
+import path from 'path';
+import * as playwright from 'playwright';
+import ms from 'ms';
+// @ts-ignore
+import { registryDirectory } from 'playwright-core/lib/server/registry/index';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import { logUnhandledError, testDebug } from './utils/log.js';
+import { createHash } from './utils/guid.js';
+import { outputFile } from './config.js';
+import { extensionPath } from './utils/extensionPath.js';
+const TIMEOUT_STR = '30m';
+export function contextFactory(config) {
+    if (config.browser.remoteEndpoint)
+        return new RemoteContextFactory(config);
+    if (config.browser.cdpEndpoint)
+        return new CdpContextFactory(config);
+    if (config.browser.isolated)
+        return new IsolatedContextFactory(config);
+    return new PersistentContextFactory(config);
+}
+class BaseContextFactory {
+    name;
+    _autoCloseTimer;
+    description;
+    config;
+    _browserPromise;
+    constructor(name, description, config) {
+        this.name = name;
+        this.description = description;
+        this.config = config;
+    }
+    async _obtainBrowser(clientInfo) {
+        if (this._browserPromise)
+            return this._browserPromise;
+        testDebug(`obtain browser (${this.name})`);
+        this._browserPromise = this._doObtainBrowser(clientInfo);
+        void this._browserPromise.then(browser => {
+            browser.on('disconnected', () => {
+                this._browserPromise = undefined;
+                this._clearAutoCloseTimer();
+            });
+            // Start auto-close timer
+            this._startAutoCloseTimer(browser);
+        }).catch(() => {
+            this._browserPromise = undefined;
+            this._clearAutoCloseTimer();
+        });
+        return this._browserPromise;
+    }
+    _startAutoCloseTimer(browser) {
+        this._clearAutoCloseTimer();
+        testDebug(`schedule auto-close in ${TIMEOUT_STR} (${this.name})`);
+        this._autoCloseTimer = setTimeout(async () => {
+            testDebug(`auto-closing browser after ${TIMEOUT_STR} (${this.name})`);
+            try {
+                await browser.close();
+                this._browserPromise = undefined;
+                testDebug(`auto-close complete (${this.name})`);
+            }
+            catch (error) {
+                testDebug(`error during auto-close: ${error}`);
+            }
+        }, ms(TIMEOUT_STR));
+    }
+    _clearAutoCloseTimer() {
+        if (this._autoCloseTimer) {
+            testDebug(`cancel auto-close timer (${this.name})`);
+            clearTimeout(this._autoCloseTimer);
+            this._autoCloseTimer = undefined;
+        }
+    }
+    async _doObtainBrowser(clientInfo) {
+        throw new Error('Not implemented');
+    }
+    async createContext(clientInfo) {
+        testDebug(`create browser context (${this.name})`);
+        const browser = await this._obtainBrowser(clientInfo);
+        const browserContext = await this._doCreateContext(browser);
+        return { browserContext, close: () => this._closeBrowserContext(browserContext, browser) };
+    }
+    async _doCreateContext(browser) {
+        throw new Error('Not implemented');
+    }
+    async _closeBrowserContext(browserContext, browser) {
+        testDebug(`close browser context (${this.name})`);
+        if (browser.contexts().length === 1) {
+            this._browserPromise = undefined;
+            this._clearAutoCloseTimer();
+        }
+        await browserContext.close().catch(logUnhandledError);
+        if (browser.contexts().length === 0) {
+            testDebug(`close browser (${this.name})`);
+            this._clearAutoCloseTimer();
+            await browser.close().catch(logUnhandledError);
+        }
+    }
+}
+class IsolatedContextFactory extends BaseContextFactory {
+    constructor(config) {
+        super('isolated', 'Create a new isolated browser context', config);
+    }
+    async _doObtainBrowser(clientInfo) {
+        await injectCdpPort(this.config.browser);
+        const browserType = playwright[this.config.browser.browserName];
+        const extensionArgs = [
+            `--disable-extensions-except=${extensionPath}`,
+            `--load-extension=${extensionPath}`,
+        ];
+        const args = [...(this.config.browser.launchOptions?.args || []), ...extensionArgs];
+        return browserType.launch({
+            tracesDir: await startTraceServer(this.config, clientInfo.rootPath),
+            ...this.config.browser.launchOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+            args,
+        }).catch(error => {
+            if (error.message.includes('Executable doesn\'t exist'))
+                throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+            throw error;
+        });
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext(this.config.browser.contextOptions);
+    }
+}
+class CdpContextFactory extends BaseContextFactory {
+    constructor(config) {
+        super('cdp', 'Connect to a browser over CDP', config);
+    }
+    async _doObtainBrowser() {
+        return playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
+    }
+    async _doCreateContext(browser) {
+        return this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+}
+class RemoteContextFactory extends BaseContextFactory {
+    constructor(config) {
+        super('remote', 'Connect to a browser using a remote endpoint', config);
+    }
+    async _doObtainBrowser() {
+        const url = new URL(this.config.browser.remoteEndpoint);
+        url.searchParams.set('browser', this.config.browser.browserName);
+        if (this.config.browser.launchOptions)
+            url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
+        return playwright[this.config.browser.browserName].connect(String(url));
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext();
+    }
+}
+class PersistentContextFactory {
+    config;
+    name = 'persistent';
+    description = 'Create a new persistent browser context';
+    _userDataDirs = new Set();
+    _autoCloseTimer;
+    constructor(config) {
+        this.config = config;
+    }
+    async createContext(clientInfo) {
+        await injectCdpPort(this.config.browser);
+        testDebug('create browser context (persistent)');
+        const userDataDir = this.config.browser.userDataDir ?? await this._createUserDataDir(clientInfo.rootPath);
+        const tracesDir = await startTraceServer(this.config, clientInfo.rootPath);
+        this._userDataDirs.add(userDataDir);
+        testDebug('lock user data dir', userDataDir);
+        const browserType = playwright[this.config.browser.browserName];
+        for (let i = 0; i < 5; i++) {
+            try {
+                const extensionArgs = [
+                    `--disable-extensions-except=${extensionPath}`,
+                    `--load-extension=${extensionPath}`,
+                ];
+                const args = [...(this.config.browser.launchOptions?.args || []), ...extensionArgs];
+                const browserContext = await browserType.launchPersistentContext(userDataDir, {
+                    tracesDir,
+                    ...this.config.browser.launchOptions,
+                    ...this.config.browser.contextOptions,
+                    handleSIGINT: false,
+                    handleSIGTERM: false,
+                    args,
+                });
+                // Start auto-close timer
+                this._startAutoCloseTimer(browserContext);
+                const close = () => this._closeBrowserContext(browserContext, userDataDir);
+                return { browserContext, close };
+            }
+            catch (error) {
+                if (error.message.includes('Executable doesn\'t exist'))
+                    throw new Error(`Browser specified in your config is not installed. Either install it (likely) or change the config.`);
+                if (error.message.includes('ProcessSingleton') || error.message.includes('Invalid URL')) {
+                    // User data directory is already in use, try again.
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw new Error(`Browser is already in use for ${userDataDir}, use --isolated to run multiple instances of the same browser`);
+    }
+    _startAutoCloseTimer(browserContext) {
+        this._clearAutoCloseTimer();
+        testDebug(`schedule auto-close in ${TIMEOUT_STR} (persistent)`);
+        this._autoCloseTimer = setTimeout(async () => {
+            testDebug(`auto-closing browser after ${TIMEOUT_STR} (persistent)`);
+            try {
+                await browserContext.close();
+                testDebug(`auto-close complete (persistent)`);
+            }
+            catch (error) {
+                testDebug(`error during auto-close: ${error}`);
+            }
+        }, ms(TIMEOUT_STR));
+    }
+    _clearAutoCloseTimer() {
+        if (this._autoCloseTimer) {
+            testDebug(`cancel auto-close timer (persistent)`);
+            clearTimeout(this._autoCloseTimer);
+            this._autoCloseTimer = undefined;
+        }
+    }
+    async _closeBrowserContext(browserContext, userDataDir) {
+        testDebug('close browser context (persistent)');
+        testDebug('release user data dir', userDataDir);
+        this._clearAutoCloseTimer();
+        await browserContext.close().catch(() => { });
+        this._userDataDirs.delete(userDataDir);
+        testDebug('close browser context complete (persistent)');
+    }
+    async _createUserDataDir(rootPath) {
+        const dir = process.env.PWMCP_PROFILES_DIR_FOR_TEST ?? registryDirectory;
+        const browserToken = this.config.browser.launchOptions?.channel ?? this.config.browser?.browserName;
+        // Hesitant putting hundreds of files into the user's workspace, so using it for hashing instead.
+        const rootPathToken = rootPath ? `-${createHash(rootPath)}` : '';
+        const result = path.join(dir, `mcp-${browserToken}${rootPathToken}`);
+        await fs.promises.mkdir(result, { recursive: true });
+        return result;
+    }
+}
+async function injectCdpPort(browserConfig) {
+    const isBunRuntime = 'bun' in process.versions;
+    if (isBunRuntime)
+        return;
+    if (browserConfig.browserName !== 'chromium')
+        return;
+    const launchOptions = browserConfig.launchOptions || {};
+    launchOptions.cdpPort = await findFreePort();
+    browserConfig.launchOptions = launchOptions;
+}
+async function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}
+async function startTraceServer(config, rootPath) {
+    if (!config.saveTrace)
+        return undefined;
+    const tracesDir = await outputFile(config, rootPath, `traces-${Date.now()}`);
+    const server = await startTraceViewerServer();
+    const urlPrefix = server.urlPrefix('human-readable');
+    const url = urlPrefix + '/trace/index.html?trace=' + tracesDir + '/trace.json';
+    // eslint-disable-next-line no-console
+    console.error('\nTrace viewer listening on ' + url);
+    return tracesDir;
+}

package/lib/browserServerBackend.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { Context } from './context.js';
+import { logUnhandledError } from './utils/log.js';
+import { Response } from './response.js';
+import { SessionLog } from './sessionLog.js';
+import { filteredTools } from './tools.js';
+import { packageJSON } from './utils/package.js';
+import { toMcpTool } from './mcp/tool.js';
+export class BrowserServerBackend {
+    name = 'Playwright';
+    version = packageJSON.version;
+    _tools;
+    _context;
+    _sessionLog;
+    _config;
+    _browserContextFactory;
+    constructor(config, factory) {
+        this._config = config;
+        this._browserContextFactory = factory;
+        this._tools = filteredTools(config);
+    }
+    async initialize(server) {
+        const capabilities = server.getClientCapabilities();
+        let rootPath;
+        if (capabilities?.roots) {
+            const { roots } = await server.listRoots();
+            const firstRootUri = roots[0]?.uri;
+            const url = firstRootUri ? new URL(firstRootUri) : undefined;
+            rootPath = url ? fileURLToPath(url) : undefined;
+        }
+        this._sessionLog = this._config.saveSession ? await SessionLog.create(this._config, rootPath) : undefined;
+        this._context = new Context({
+            tools: this._tools,
+            config: this._config,
+            browserContextFactory: this._browserContextFactory,
+            sessionLog: this._sessionLog,
+            clientInfo: { ...server.getClientVersion(), rootPath },
+        });
+    }
+    async listTools() {
+        return this._tools.map(tool => toMcpTool(tool.schema));
+    }
+    async callTool(name, rawArguments) {
+        const context = this._context;
+        const tool = context.tools.find(tool => tool.schema.name === name);
+        if (!tool)
+            throw new Error(`Tool "${name}" not found`);
+        const parsedArguments = tool.schema.inputSchema.parse(rawArguments || {});
+        const response = new Response(context, name, parsedArguments);
+        context.setRunningTool(true);
+        try {
+            await tool.handle(context, parsedArguments, response);
+            await response.finish();
+            this._sessionLog?.logResponse(response);
+        }
+        catch (error) {
+            response.addError(String(error));
+        }
+        finally {
+            context.setRunningTool(false);
+        }
+        return response.serialize();
+    }
+    serverClosed() {
+        void this._context?.dispose().catch(logUnhandledError);
+    }
+}