@playwright/mcp 0.0.30 → 0.0.32

package/config.d.ts

@@ -16,18 +16,13 @@
 
 import type * as playwright from 'playwright';
 
-export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install' | 'testing';
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
 
 export type Config = {
   /**
    * The browser to use.
    */
   browser?: {
-    /**
-     * Use browser agent (experimental).
-     */
-    browserAgent?: string;
-
     /**
      * The type of browser to use.
      */
@@ -85,19 +80,15 @@ export type Config = {
   /**
    * List of enabled tool capabilities. Possible values:
    *   - 'core': Core browser automation features.
-   *   - 'tabs': Tab management features.
    *   - 'pdf': PDF generation and manipulation.
-   *   - 'history': Browser history access.
-   *   - 'wait': Wait and timing utilities.
-   *   - 'files': File upload/download support.
-   *   - 'install': Browser installation utilities.
+   *   - 'vision': Coordinate-based interactions.
    */
   capabilities?: ToolCapability[];
 
   /**
-   * Run server that uses screenshots (Aria snapshots are used by default).
+   * Whether to save the Playwright session into the output directory.
    */
-  vision?: boolean;
+  saveSession?: boolean;
 
   /**
    * Whether to save the Playwright trace of the session into the output directory.
@@ -124,5 +115,5 @@ export type Config = {
   /**
    * 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' | 'auto';
+  imageResponses?: 'allow' | 'omit';
 };

package/index.d.ts

@@ -19,10 +19,5 @@ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Config } from './config.js';
 import type { BrowserContext } from 'playwright';
 
-export type Connection = {
-  server: Server;
-  close(): Promise<void>;
-};
-
-export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Connection>;
+export declare function createConnection(config?: Config, contextGetter?: () => Promise<BrowserContext>): Promise<Server>;
 export {};

package/lib/browserContextFactory.js

@@ -17,10 +17,8 @@ import fs from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import os from 'node:os';
-import debug from 'debug';
 import * as playwright from 'playwright';
-import { userDataDir } from './fileUtils.js';
-const testDebug = debug('pw:mcp:test');
+import { logUnhandledError, testDebug } from './log.js';
 export function contextFactory(browserConfig) {
     if (browserConfig.remoteEndpoint)
         return new RemoteContextFactory(browserConfig);
@@ -28,8 +26,6 @@ export function contextFactory(browserConfig) {
         return new CdpContextFactory(browserConfig);
     if (browserConfig.isolated)
         return new IsolatedContextFactory(browserConfig);
-    if (browserConfig.browserAgent)
-        return new BrowserServerContextFactory(browserConfig);
     return new PersistentContextFactory(browserConfig);
 }
 class BaseContextFactory {
@@ -70,10 +66,10 @@ class BaseContextFactory {
         testDebug(`close browser context (${this.name})`);
         if (browser.contexts().length === 1)
             this._browserPromise = undefined;
-        await browserContext.close().catch(() => { });
+        await browserContext.close().catch(logUnhandledError);
         if (browser.contexts().length === 0) {
             testDebug(`close browser (${this.name})`);
-            await browser.close().catch(() => { });
+            await browser.close().catch(logUnhandledError);
         }
     }
 }
@@ -183,34 +179,6 @@ class PersistentContextFactory {
         return result;
     }
 }
-export class BrowserServerContextFactory extends BaseContextFactory {
-    constructor(browserConfig) {
-        super('persistent', browserConfig);
-    }
-    async _doObtainBrowser() {
-        const response = await fetch(new URL(`/json/launch`, this.browserConfig.browserAgent), {
-            method: 'POST',
-            body: JSON.stringify({
-                browserType: this.browserConfig.browserName,
-                userDataDir: this.browserConfig.userDataDir ?? await this._createUserDataDir(),
-                launchOptions: this.browserConfig.launchOptions,
-                contextOptions: this.browserConfig.contextOptions,
-            }),
-        });
-        const info = await response.json();
-        if (info.error)
-            throw new Error(info.error);
-        return await playwright.chromium.connectOverCDP(`http://localhost:${info.cdpPort}/`);
-    }
-    async _doCreateContext(browser) {
-        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
-    }
-    async _createUserDataDir() {
-        const dir = await userDataDir(this.browserConfig);
-        await fs.promises.mkdir(dir, { recursive: true });
-        return dir;
-    }
-}
 async function injectCdpPort(browserConfig) {
     if (browserConfig.browserName === 'chromium')
         browserConfig.launchOptions.cdpPort = await findFreePort();

package/lib/browserServerBackend.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { Context } from './context.js';
+import { logUnhandledError } from './log.js';
+import { Response } from './response.js';
+import { SessionLog } from './sessionLog.js';
+import { filteredTools } from './tools.js';
+import { packageJSON } from './package.js';
+export class BrowserServerBackend {
+    name = 'Playwright';
+    version = packageJSON.version;
+    onclose;
+    _tools;
+    _context;
+    _sessionLog;
+    constructor(config, browserContextFactory) {
+        this._tools = filteredTools(config);
+        this._context = new Context(this._tools, config, browserContextFactory);
+    }
+    async initialize() {
+        this._sessionLog = this._context.config.saveSession ? await SessionLog.create(this._context.config) : undefined;
+    }
+    tools() {
+        return this._tools.map(tool => tool.schema);
+    }
+    async callTool(schema, parsedArguments) {
+        const response = new Response(this._context, schema.name, parsedArguments);
+        const tool = this._tools.find(tool => tool.schema.name === schema.name);
+        await tool.handle(this._context, parsedArguments, response);
+        if (this._sessionLog)
+            await this._sessionLog.log(response);
+        return await response.serialize();
+    }
+    serverInitialized(version) {
+        this._context.clientVersion = version;
+    }
+    serverClosed() {
+        this.onclose?.();
+        void this._context.dispose().catch(logUnhandledError);
+    }
+}

package/lib/config.js

@@ -42,14 +42,18 @@ export async function resolveConfig(config) {
 }
 export async function resolveCLIConfig(cliOptions) {
     const configInFile = await loadConfig(cliOptions.config);
-    const cliOverrides = await configFromCLIOptions(cliOptions);
-    const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+    const envOverrides = configFromEnv();
+    const cliOverrides = configFromCLIOptions(cliOptions);
+    let result = defaultConfig;
+    result = mergeConfig(result, configInFile);
+    result = mergeConfig(result, envOverrides);
+    result = mergeConfig(result, cliOverrides);
     // Derive artifact output directory from config.outputDir
     if (result.saveTrace)
         result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
     return result;
 }
-export async function configFromCLIOptions(cliOptions) {
+export function configFromCLIOptions(cliOptions) {
     let browserName;
     let channel;
     switch (cliOptions.browser) {
@@ -79,7 +83,7 @@ export async function configFromCLIOptions(cliOptions) {
         headless: cliOptions.headless,
     };
     // --no-sandbox was passed, disable the sandbox
-    if (!cliOptions.sandbox)
+    if (cliOptions.sandbox === false)
         launchOptions.chromiumSandbox = false;
     if (cliOptions.proxyServer) {
         launchOptions.proxy = {
@@ -113,7 +117,6 @@ export async function configFromCLIOptions(cliOptions) {
         contextOptions.serviceWorkers = 'block';
     const result = {
         browser: {
-            browserAgent: cliOptions.browserAgent ?? process.env.PW_BROWSER_AGENT,
             browserName,
             isolated: cliOptions.isolated,
             userDataDir: cliOptions.userDataDir,
@@ -125,18 +128,47 @@ export async function configFromCLIOptions(cliOptions) {
             port: cliOptions.port,
             host: cliOptions.host,
         },
-        capabilities: cliOptions.caps?.split(',').map((c) => c.trim()),
-        vision: !!cliOptions.vision,
+        capabilities: cliOptions.caps,
         network: {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
         },
+        saveSession: cliOptions.saveSession,
         saveTrace: cliOptions.saveTrace,
         outputDir: cliOptions.outputDir,
         imageResponses: cliOptions.imageResponses,
     };
     return result;
 }
+function configFromEnv() {
+    const options = {};
+    options.allowedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_ALLOWED_ORIGINS);
+    options.blockedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_BLOCKED_ORIGINS);
+    options.blockServiceWorkers = envToBoolean(process.env.PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS);
+    options.browser = envToString(process.env.PLAYWRIGHT_MCP_BROWSER);
+    options.caps = commaSeparatedList(process.env.PLAYWRIGHT_MCP_CAPS);
+    options.cdpEndpoint = envToString(process.env.PLAYWRIGHT_MCP_CDP_ENDPOINT);
+    options.config = envToString(process.env.PLAYWRIGHT_MCP_CONFIG);
+    options.device = envToString(process.env.PLAYWRIGHT_MCP_DEVICE);
+    options.executablePath = envToString(process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH);
+    options.headless = envToBoolean(process.env.PLAYWRIGHT_MCP_HEADLESS);
+    options.host = envToString(process.env.PLAYWRIGHT_MCP_HOST);
+    options.ignoreHttpsErrors = envToBoolean(process.env.PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS);
+    options.isolated = envToBoolean(process.env.PLAYWRIGHT_MCP_ISOLATED);
+    if (process.env.PLAYWRIGHT_MCP_IMAGE_RESPONSES === 'omit')
+        options.imageResponses = 'omit';
+    options.sandbox = envToBoolean(process.env.PLAYWRIGHT_MCP_SANDBOX);
+    options.outputDir = envToString(process.env.PLAYWRIGHT_MCP_OUTPUT_DIR);
+    options.port = envToNumber(process.env.PLAYWRIGHT_MCP_PORT);
+    options.proxyBypass = envToString(process.env.PLAYWRIGHT_MCP_PROXY_BYPASS);
+    options.proxyServer = envToString(process.env.PLAYWRIGHT_MCP_PROXY_SERVER);
+    options.saveTrace = envToBoolean(process.env.PLAYWRIGHT_MCP_SAVE_TRACE);
+    options.storageState = envToString(process.env.PLAYWRIGHT_MCP_STORAGE_STATE);
+    options.userAgent = envToString(process.env.PLAYWRIGHT_MCP_USER_AGENT);
+    options.userDataDir = envToString(process.env.PLAYWRIGHT_MCP_USER_DATA_DIR);
+    options.viewportSize = envToString(process.env.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
+    return configFromCLIOptions(options);
+}
 async function loadConfig(configFile) {
     if (!configFile)
         return {};
@@ -187,3 +219,28 @@ function mergeConfig(base, overrides) {
         },
     };
 }
+export function semicolonSeparatedList(value) {
+    if (!value)
+        return undefined;
+    return value.split(';').map(v => v.trim());
+}
+export function commaSeparatedList(value) {
+    if (!value)
+        return undefined;
+    return value.split(',').map(v => v.trim());
+}
+function envToNumber(value) {
+    if (!value)
+        return undefined;
+    return +value;
+}
+function envToBoolean(value) {
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
+function envToString(value) {
+    return value ? value.trim() : undefined;
+}

package/lib/context.js

@@ -14,10 +14,8 @@
  * limitations under the License.
  */
 import debug from 'debug';
-import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
-import { ManualPromise } from './manualPromise.js';
+import { logUnhandledError } from './log.js';
 import { Tab } from './tab.js';
-import { outputFile } from './config.js';
 const testDebug = debug('pw:mcp:test');
 export class Context {
     tools;
@@ -26,48 +24,28 @@ export class Context {
     _browserContextFactory;
     _tabs = [];
     _currentTab;
-    _modalStates = [];
-    _pendingAction;
-    _downloads = [];
     clientVersion;
+    static _allContexts = new Set();
+    _closeBrowserContextPromise;
     constructor(tools, config, browserContextFactory) {
         this.tools = tools;
         this.config = config;
         this._browserContextFactory = browserContextFactory;
         testDebug('create context');
+        Context._allContexts.add(this);
     }
-    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;
+    static async disposeAll() {
+        await Promise.all([...Context._allContexts].map(context => context.dispose()));
     }
     tabs() {
         return this._tabs;
     }
+    currentTab() {
+        return this._currentTab;
+    }
     currentTabOrDie() {
         if (!this._currentTab)
-            throw new Error('No current snapshot available. Capture a snapshot or navigate to a new location first.');
+            throw new Error('No open pages available. Use the "browser_navigate" tool to navigate to a page first.');
         return this._currentTab;
     }
     async newTab() {
@@ -77,8 +55,12 @@ export class Context {
         return this._currentTab;
     }
     async selectTab(index) {
-        this._currentTab = this._tabs[index - 1];
-        await this._currentTab.page.bringToFront();
+        const tab = this._tabs[index];
+        if (!tab)
+            throw new Error(`Tab ${index} not found`);
+        await tab.page.bringToFront();
+        this._currentTab = tab;
+        return tab;
     }
     async ensureTab() {
         const { browserContext } = await this._ensureBrowserContext();
@@ -86,140 +68,34 @@ export class Context {
             await browserContext.newPage();
         return this._currentTab;
     }
-    async listTabsMarkdown() {
-        if (!this._tabs.length)
-            return '### No tabs open';
+    async listTabsMarkdown(force = false) {
+        if (this._tabs.length === 1 && !force)
+            return [];
+        if (!this._tabs.length) {
+            return [
+                '### No open tabs',
+                'Use the "browser_navigate" tool to navigate to a page first.',
+                '',
+            ];
+        }
         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})`);
+            lines.push(`- ${i}:${current} [${title}] (${url})`);
         }
-        return lines.join('\n');
+        lines.push('');
+        return lines;
     }
     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;
+        const tab = index === undefined ? this._currentTab : this._tabs[index];
+        if (!tab)
+            throw new Error(`Tab ${index} not found`);
+        const url = tab.page.url();
+        await tab.page.close();
+        return url;
     }
     _onPageCreated(page) {
         const tab = new Tab(this, page, tab => this._onPageClosed(tab));
@@ -228,7 +104,6 @@ ${code.join('\n')}
             this._currentTab = tab;
     }
     _onPageClosed(tab) {
-        this._modalStates = this._modalStates.filter(state => state.tab !== tab);
         const index = this._tabs.indexOf(tab);
         if (index === -1)
             return;
@@ -236,9 +111,15 @@ ${code.join('\n')}
         if (this._currentTab === tab)
             this._currentTab = this._tabs[Math.min(index, this._tabs.length - 1)];
         if (!this._tabs.length)
-            void this.close();
+            void this.closeBrowserContext();
+    }
+    async closeBrowserContext() {
+        if (!this._closeBrowserContextPromise)
+            this._closeBrowserContextPromise = this._closeBrowserContextImpl().catch(logUnhandledError);
+        await this._closeBrowserContextPromise;
+        this._closeBrowserContextPromise = undefined;
     }
-    async close() {
+    async _closeBrowserContextImpl() {
         if (!this._browserContextPromise)
             return;
         testDebug('close context');
@@ -250,6 +131,10 @@ ${code.join('\n')}
             await close();
         });
     }
+    async dispose() {
+        await this.closeBrowserContext();
+        Context._allContexts.delete(this);
+    }
     async _setupRequestInterception(context) {
         if (this.config.network?.allowedOrigins?.length) {
             await context.route('**', route => route.abort('blockedbyclient'));
@@ -271,8 +156,10 @@ ${code.join('\n')}
         return this._browserContextPromise;
     }
     async _setupBrowserContext() {
+        if (this._closeBrowserContextPromise)
+            throw new Error('Another browser context is being closed.');
         // TODO: move to the browser context factory to make it based on isolation mode.
-        const result = await this._browserContextFactory.createContext();
+        const result = await this._browserContextFactory.createContext(this.clientVersion);
         const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         for (const page of browserContext.pages())