@playwright/mcp 0.0.26 → 0.0.28

package/README.md

@@ -137,7 +137,10 @@ Playwright MCP server supports following arguments. They can be provided in the
   --ignore-https-errors        ignore https errors
   --isolated                   keep the browser profile in memory, do not save
                                it to disk.
-  --no-image-responses         do not send image responses to the client.
+  --image-responses <mode>     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.
   --no-sandbox                 disable the sandbox for all process types that
                                are normally sandboxed.
   --output-dir <path>          path to the directory for output files.
@@ -196,7 +199,7 @@ state [here](https://playwright.dev/docs/auth).
       "args": [
         "@playwright/mcp@latest",
         "--isolated",
-        "--storage-state={path/to/storage.json}
+        "--storage-state={path/to/storage.json}"
       ]
     }
   }

package/config.d.ts

@@ -117,7 +117,7 @@ export type Config = {
   };
 
   /**
-   * Do not send image responses to the client.
+   * 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.
    */
-  noImageResponses?: boolean;
+  imageResponses?: 'allow' | 'omit' | 'auto';
 };

package/index.d.ts

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

package/index.js

@@ -15,5 +15,5 @@
  * limitations under the License.
  */
 
-import { createConnection } from './lib/index';
+import { createConnection } from './lib/index.js';
 export { createConnection };

package/lib/browserContextFactory.js

@@ -0,0 +1,179 @@
+/**
+ * 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';
+import os from 'node:os';
+import path from 'node:path';
+import debug from 'debug';
+import * as playwright from 'playwright';
+const testDebug = debug('pw:mcp:test');
+export function contextFactory(browserConfig) {
+    if (browserConfig.remoteEndpoint)
+        return new RemoteContextFactory(browserConfig);
+    if (browserConfig.cdpEndpoint)
+        return new CdpContextFactory(browserConfig);
+    if (browserConfig.isolated)
+        return new IsolatedContextFactory(browserConfig);
+    return new PersistentContextFactory(browserConfig);
+}
+class BaseContextFactory {
+    browserConfig;
+    _browserPromise;
+    name;
+    constructor(name, browserConfig) {
+        this.name = name;
+        this.browserConfig = browserConfig;
+    }
+    async _obtainBrowser() {
+        if (this._browserPromise)
+            return this._browserPromise;
+        testDebug(`obtain browser (${this.name})`);
+        this._browserPromise = this._doObtainBrowser();
+        void this._browserPromise.then(browser => {
+            browser.on('disconnected', () => {
+                this._browserPromise = undefined;
+            });
+        }).catch(() => {
+            this._browserPromise = undefined;
+        });
+        return this._browserPromise;
+    }
+    async _doObtainBrowser() {
+        throw new Error('Not implemented');
+    }
+    async createContext() {
+        testDebug(`create browser context (${this.name})`);
+        const browser = await this._obtainBrowser();
+        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;
+        await browserContext.close().catch(() => { });
+        if (browser.contexts().length === 0) {
+            testDebug(`close browser (${this.name})`);
+            await browser.close().catch(() => { });
+        }
+    }
+}
+class IsolatedContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('isolated', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const browserType = playwright[this.browserConfig.browserName];
+        return browserType.launch({
+            ...this.browserConfig.launchOptions,
+            handleSIGINT: false,
+            handleSIGTERM: false,
+        }).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.browserConfig.contextOptions);
+    }
+}
+class CdpContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('cdp', browserConfig);
+    }
+    async _doObtainBrowser() {
+        return playwright.chromium.connectOverCDP(this.browserConfig.cdpEndpoint);
+    }
+    async _doCreateContext(browser) {
+        return this.browserConfig.isolated ? await browser.newContext() : browser.contexts()[0];
+    }
+}
+class RemoteContextFactory extends BaseContextFactory {
+    constructor(browserConfig) {
+        super('remote', browserConfig);
+    }
+    async _doObtainBrowser() {
+        const url = new URL(this.browserConfig.remoteEndpoint);
+        url.searchParams.set('browser', this.browserConfig.browserName);
+        if (this.browserConfig.launchOptions)
+            url.searchParams.set('launch-options', JSON.stringify(this.browserConfig.launchOptions));
+        return playwright[this.browserConfig.browserName].connect(String(url));
+    }
+    async _doCreateContext(browser) {
+        return browser.newContext();
+    }
+}
+class PersistentContextFactory {
+    browserConfig;
+    _userDataDirs = new Set();
+    constructor(browserConfig) {
+        this.browserConfig = browserConfig;
+    }
+    async createContext() {
+        testDebug('create browser context (persistent)');
+        const userDataDir = this.browserConfig.userDataDir ?? await this._createUserDataDir();
+        this._userDataDirs.add(userDataDir);
+        testDebug('lock user data dir', userDataDir);
+        const browserType = playwright[this.browserConfig.browserName];
+        for (let i = 0; i < 5; i++) {
+            try {
+                const browserContext = await browserType.launchPersistentContext(userDataDir, {
+                    ...this.browserConfig.launchOptions,
+                    ...this.browserConfig.contextOptions,
+                    handleSIGINT: false,
+                    handleSIGTERM: false,
+                });
+                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`);
+    }
+    async _closeBrowserContext(browserContext, userDataDir) {
+        testDebug('close browser context (persistent)');
+        testDebug('release user data dir', userDataDir);
+        await browserContext.close().catch(() => { });
+        this._userDataDirs.delete(userDataDir);
+        testDebug('close browser context complete (persistent)');
+    }
+    async _createUserDataDir() {
+        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);
+        const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${this.browserConfig.launchOptions?.channel ?? this.browserConfig?.browserName}-profile`);
+        await fs.promises.mkdir(result, { recursive: true });
+        return result;
+    }
+}

package/lib/config.js

@@ -35,6 +35,7 @@ const defaultConfig = {
         allowedOrigins: undefined,
         blockedOrigins: undefined,
     },
+    server: {},
     outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };
 export async function resolveConfig(config) {
@@ -47,6 +48,8 @@ export async function resolveCLIConfig(cliOptions) {
     // Derive artifact output directory from config.outputDir
     if (result.saveTrace)
         result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
+    if (result.browser.browserName === 'chromium')
+        result.browser.launchOptions.cdpPort = await findFreePort();
     return result;
 }
 export async function configFromCLIOptions(cliOptions) {
@@ -71,9 +74,6 @@ export async function configFromCLIOptions(cliOptions) {
         case 'webkit':
             browserName = 'webkit';
             break;
-        default:
-            browserName = 'chromium';
-            channel = 'chrome';
     }
     // Launch options
     const launchOptions = {
@@ -81,13 +81,9 @@ export async function configFromCLIOptions(cliOptions) {
         executablePath: cliOptions.executablePath,
         headless: cliOptions.headless,
     };
-    if (browserName === 'chromium') {
-        launchOptions.cdpPort = await findFreePort();
-        if (!cliOptions.sandbox) {
-            // --no-sandbox was passed, disable the sandbox
-            launchOptions.chromiumSandbox = false;
-        }
-    }
+    // --no-sandbox was passed, disable the sandbox
+    if (!cliOptions.sandbox)
+        launchOptions.chromiumSandbox = false;
     if (cliOptions.proxyServer) {
         launchOptions.proxy = {
             server: cliOptions.proxyServer
@@ -137,11 +133,8 @@ export async function configFromCLIOptions(cliOptions) {
         },
         saveTrace: cliOptions.saveTrace,
         outputDir: cliOptions.outputDir,
+        imageResponses: cliOptions.imageResponses,
     };
-    if (!cliOptions.imageResponses) {
-        // --no-image-responses was passed, disable image responses
-        result.noImageResponses = true;
-    }
     return result;
 }
 async function findFreePort() {
@@ -198,6 +191,10 @@ function mergeConfig(base, overrides) {
         network: {
             ...pickDefined(base.network),
             ...pickDefined(overrides.network),
-        }
+        },
+        server: {
+            ...pickDefined(base.server),
+            ...pickDefined(overrides.server),
+        },
     };
 }

package/lib/connection.js

@@ -13,16 +13,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { Context, packageJSON } from './context.js';
+import { Context } from './context.js';
 import { snapshotTools, visionTools } from './tools.js';
-export async function createConnection(config) {
+import { packageJSON } from './package.js';
+export function createConnection(config, browserContextFactory) {
     const allTools = config.vision ? visionTools : snapshotTools;
     const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
-    const context = new Context(tools, config);
-    const server = new Server({ name: 'Playwright', version: packageJSON.version }, {
+    const context = new Context(tools, config, browserContextFactory);
+    const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
         capabilities: {
             tools: {},
         }
@@ -62,8 +63,7 @@ export async function createConnection(config) {
             return errorResult(String(error));
         }
     });
-    const connection = new Connection(server, context);
-    return connection;
+    return new Connection(server, context);
 }
 export class Connection {
     server;
@@ -71,14 +71,9 @@ export class Connection {
     constructor(server, context) {
         this.server = server;
         this.context = context;
-    }
-    async connect(transport) {
-        await this.server.connect(transport);
-        await new Promise(resolve => {
-            this.server.oninitialized = () => resolve();
-        });
-        if (this.server.getClientVersion()?.name.includes('cursor'))
-            this.context.config.noImageResponses = true;
+        this.server.oninitialized = () => {
+            this.context.clientVersion = this.server.getClientVersion();
+        };
     }
     async close() {
         await this.server.close();

package/lib/context.js

@@ -13,27 +13,35 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import fs from 'node:fs';
-import url from 'node:url';
-import os from 'node:os';
-import path from 'node:path';
-import * as playwright from 'playwright';
+import debug from 'debug';
 import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
+const testDebug = debug('pw:mcp:test');
 export class Context {
     tools;
     config;
     _browserContextPromise;
+    _browserContextFactory;
     _tabs = [];
     _currentTab;
     _modalStates = [];
     _pendingAction;
     _downloads = [];
-    constructor(tools, config) {
+    clientVersion;
+    constructor(tools, config, browserContextFactory) {
         this.tools = tools;
         this.config = config;
+        this._browserContextFactory = browserContextFactory;
+        testDebug('create context');
+    }
+    clientSupportsImages() {
+        if (this.config.imageResponses === 'allow')
+            return true;
+        if (this.config.imageResponses === 'omit')
+            return false;
+        return !this.clientVersion?.name.includes('cursor');
     }
     modalStates() {
         return this._modalStates;
@@ -233,14 +241,13 @@ ${code.join('\n')}
     async close() {
         if (!this._browserContextPromise)
             return;
+        testDebug('close context');
         const promise = this._browserContextPromise;
         this._browserContextPromise = undefined;
-        await promise.then(async ({ browserContext, browser }) => {
+        await promise.then(async ({ browserContext, close }) => {
             if (this.config.saveTrace)
                 await browserContext.tracing.stop();
-            await browserContext.close().then(async () => {
-                await browser?.close();
-            }).catch(() => { });
+            await close();
         });
     }
     async _setupRequestInterception(context) {
@@ -264,7 +271,9 @@ ${code.join('\n')}
         return this._browserContextPromise;
     }
     async _setupBrowserContext() {
-        const { browser, browserContext } = await this._createBrowserContext();
+        // TODO: move to the browser context factory to make it based on isolation mode.
+        const result = await this._browserContextFactory.createContext();
+        const { browserContext } = result;
         await this._setupRequestInterception(browserContext);
         for (const page of browserContext.pages())
             this._onPageCreated(page);
@@ -277,70 +286,6 @@ ${code.join('\n')}
                 sources: false,
             });
         }
-        return { browser, browserContext };
-    }
-    async _createBrowserContext() {
-        if (this.config.browser?.remoteEndpoint) {
-            const url = new URL(this.config.browser?.remoteEndpoint);
-            if (this.config.browser.browserName)
-                url.searchParams.set('browser', this.config.browser.browserName);
-            if (this.config.browser.launchOptions)
-                url.searchParams.set('launch-options', JSON.stringify(this.config.browser.launchOptions));
-            const browser = await playwright[this.config.browser?.browserName ?? 'chromium'].connect(String(url));
-            const browserContext = await browser.newContext();
-            return { browser, browserContext };
-        }
-        if (this.config.browser?.cdpEndpoint) {
-            const browser = await playwright.chromium.connectOverCDP(this.config.browser.cdpEndpoint);
-            const browserContext = this.config.browser.isolated ? await browser.newContext() : browser.contexts()[0];
-            return { browser, browserContext };
-        }
-        return this.config.browser?.isolated ?
-            await createIsolatedContext(this.config.browser) :
-            await launchPersistentContext(this.config.browser);
-    }
-}
-async function createIsolatedContext(browserConfig) {
-    try {
-        const browserName = browserConfig?.browserName ?? 'chromium';
-        const browserType = playwright[browserName];
-        const browser = await browserType.launch(browserConfig.launchOptions);
-        const browserContext = await browser.newContext(browserConfig.contextOptions);
-        return { browser, browserContext };
-    }
-    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 function launchPersistentContext(browserConfig) {
-    try {
-        const browserName = browserConfig.browserName ?? 'chromium';
-        const userDataDir = browserConfig.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
-        const browserType = playwright[browserName];
-        const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig.launchOptions, ...browserConfig.contextOptions });
-        return { browserContext };
-    }
-    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;
+        return result;
     }
 }
-async function createUserDataDir(browserConfig) {
-    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);
-    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
-    await fs.promises.mkdir(result, { recursive: true });
-    return result;
-}
-const __filename = url.fileURLToPath(import.meta.url);
-export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/index.js

@@ -15,7 +15,22 @@
  */
 import { createConnection as createConnectionImpl } from './connection.js';
 import { resolveConfig } from './config.js';
-export async function createConnection(userConfig = {}) {
+import { contextFactory } from './browserContextFactory.js';
+export async function createConnection(userConfig = {}, contextGetter) {
     const config = await resolveConfig(userConfig);
-    return createConnectionImpl(config);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
+    return createConnectionImpl(config, factory);
+}
+class SimpleBrowserContextFactory {
+    _contextGetter;
+    constructor(contextGetter) {
+        this._contextGetter = contextGetter;
+    }
+    async createContext() {
+        const browserContext = await this._contextGetter();
+        return {
+            browserContext,
+            close: () => browserContext.close()
+        };
+    }
 }

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

package/lib/pageSnapshot.js

@@ -29,9 +29,6 @@ export class PageSnapshot {
         return this._text;
     }
     async _build() {
-        // FIXME: Rountrip evaluate to ensure _snapshotForAI works.
-        // This probably broke once we moved off locator snapshots
-        await this._page.evaluate(() => 1);
         const snapshot = await callOnPageNoTrace(this._page, page => page._snapshotForAI());
         this._text = [
             `- Page Snapshot`,
@@ -40,7 +37,7 @@ export class PageSnapshot {
             '```',
         ].join('\n');
     }
-    refLocator(ref) {
-        return this._page.locator(`aria-ref=${ref}`);
+    refLocator(params) {
+        return this._page.locator(`aria-ref=${params.ref}`).describe(params.element);
     }
 }

package/lib/program.js

@@ -14,11 +14,12 @@
  * limitations under the License.
  */
 import { program } from 'commander';
-import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveCLIConfig } from './config.js';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { packageJSON } from './context.js';
+import { startHttpTransport, startStdioTransport } from './transport.js';
+import { resolveCLIConfig } from './config.js';
+import { Server } from './server.js';
+import { packageJSON } from './package.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -35,7 +36,7 @@ program
     .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
     .option('--ignore-https-errors', 'ignore https errors')
     .option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
-    .option('--no-image-responses', 'do not send image responses to the client.')
+    .option('--image-responses <mode>', '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.')
     .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
     .option('--output-dir <path>', 'path to the directory for output files.')
     .option('--port <port>', 'port to listen on for SSE transport.')
@@ -49,12 +50,12 @@ program
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
     .action(async (options) => {
     const config = await resolveCLIConfig(options);
-    const connectionList = [];
-    setupExitWatchdog(connectionList);
-    if (options.port)
-        startHttpTransport(config, +options.port, options.host, connectionList);
+    const server = new Server(config);
+    server.setupExitWatchdog();
+    if (config.server.port !== undefined)
+        startHttpTransport(server);
     else
-        await startStdioTransport(config, connectionList);
+        await startStdioTransport(server);
     if (config.saveTrace) {
         const server = await startTraceViewerServer();
         const urlPrefix = server.urlPrefix('human-readable');
@@ -63,18 +64,7 @@ program
         console.error('\nTrace viewer listening on ' + url);
     }
 });
-function setupExitWatchdog(connectionList) {
-    const handleExit = async () => {
-        setTimeout(() => process.exit(0), 15000);
-        for (const connection of connectionList)
-            await connection.close();
-        process.exit(0);
-    };
-    process.stdin.on('close', handleExit);
-    process.on('SIGINT', handleExit);
-    process.on('SIGTERM', handleExit);
-}
 function semicolonSeparatedList(value) {
     return value.split(';').map(v => v.trim());
 }
-program.parse(process.argv);
+void program.parseAsync(process.argv);

package/lib/server.js

@@ -0,0 +1,48 @@
+/**
+ * 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 './connection.js';
+import { contextFactory } from './browserContextFactory.js';
+export class Server {
+    config;
+    _connectionList = [];
+    _browserConfig;
+    _contextFactory;
+    constructor(config) {
+        this.config = config;
+        this._browserConfig = config.browser;
+        this._contextFactory = contextFactory(this._browserConfig);
+    }
+    async createConnection(transport) {
+        const connection = createConnection(this.config, this._contextFactory);
+        this._connectionList.push(connection);
+        await connection.server.connect(transport);
+        return connection;
+    }
+    setupExitWatchdog() {
+        let isExiting = false;
+        const handleExit = async () => {
+            if (isExiting)
+                return;
+            isExiting = true;
+            setTimeout(() => process.exit(0), 15000);
+            await Promise.all(this._connectionList.map(connection => connection.close()));
+            process.exit(0);
+        };
+        process.stdin.on('close', handleExit);
+        process.on('SIGINT', handleExit);
+        process.on('SIGTERM', handleExit);
+    }
+}

package/lib/tools/screenshot.js

@@ -48,12 +48,12 @@ const screenshot = defineTool({
         const code = [
             `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
         ];
-        const locator = params.ref ? snapshot.refLocator(params.ref) : null;
+        const locator = params.ref ? snapshot.refLocator({ element: params.element || '', ref: params.ref }) : null;
         if (locator)
             code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
         else
             code.push(`await page.screenshot(${javascript.formatObject(options)});`);
-        const includeBase64 = !context.config.noImageResponses;
+        const includeBase64 = context.clientSupportsImages();
         const action = async () => {
             const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
             return {

package/lib/tools/snapshot.js

@@ -50,7 +50,7 @@ const click = defineTool({
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();
-        const locator = tab.snapshotOrDie().refLocator(params.ref);
+        const locator = tab.snapshotOrDie().refLocator(params);
         const code = [
             `// Click ${params.element}`,
             `await page.${await generateLocator(locator)}.click();`
@@ -79,8 +79,8 @@ const drag = defineTool({
     },
     handle: async (context, params) => {
         const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const startLocator = snapshot.refLocator(params.startRef);
-        const endLocator = snapshot.refLocator(params.endRef);
+        const startLocator = snapshot.refLocator({ ref: params.startRef, element: params.startElement });
+        const endLocator = snapshot.refLocator({ ref: params.endRef, element: params.endElement });
         const code = [
             `// Drag ${params.startElement} to ${params.endElement}`,
             `await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`
@@ -104,7 +104,7 @@ const hover = defineTool({
     },
     handle: async (context, params) => {
         const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params.ref);
+        const locator = snapshot.refLocator(params);
         const code = [
             `// Hover over ${params.element}`,
             `await page.${await generateLocator(locator)}.hover();`
@@ -133,7 +133,7 @@ const type = defineTool({
     },
     handle: async (context, params) => {
         const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params.ref);
+        const locator = snapshot.refLocator(params);
         const code = [];
         const steps = [];
         if (params.slowly) {
@@ -173,7 +173,7 @@ const selectOption = defineTool({
     },
     handle: async (context, params) => {
         const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params.ref);
+        const locator = snapshot.refLocator(params);
         const code = [
             `// Select options [${params.values.join(', ')}] in ${params.element}`,
             `await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`

package/lib/tools/utils.js

@@ -66,8 +66,8 @@ export function sanitizeForFilePath(s) {
     return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
 }
 export async function generateLocator(locator) {
-    return locator._frame._wrapApiCall(() => locator._generateLocatorString(), true);
+    return locator._generateLocatorString();
 }
 export async function callOnPageNoTrace(page, callback) {
-    return await page._wrapApiCall(() => callback(page), true);
+    return await page._wrapApiCall(() => callback(page), { internal: true });
 }

package/lib/transport.js

@@ -16,16 +16,15 @@
 import http from 'node:http';
 import assert from 'node:assert';
 import crypto from 'node:crypto';
+import debug from 'debug';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createConnection } from './connection.js';
-export async function startStdioTransport(config, connectionList) {
-    const connection = await createConnection(config);
-    await connection.connect(new StdioServerTransport());
-    connectionList.push(connection);
+export async function startStdioTransport(server) {
+    await server.createConnection(new StdioServerTransport());
 }
-async function handleSSE(config, req, res, url, sessions, connectionList) {
+const testDebug = debug('pw:mcp:test');
+async function handleSSE(server, req, res, url, sessions) {
     if (req.method === 'POST') {
         const sessionId = url.searchParams.get('sessionId');
         if (!sessionId) {
@@ -42,22 +41,20 @@ async function handleSSE(config, req, res, url, sessions, connectionList) {
     else if (req.method === 'GET') {
         const transport = new SSEServerTransport('/sse', res);
         sessions.set(transport.sessionId, transport);
-        const connection = await createConnection(config);
-        await connection.connect(transport);
-        connectionList.push(connection);
+        testDebug(`create SSE session: ${transport.sessionId}`);
+        const connection = await server.createConnection(transport);
         res.on('close', () => {
+            testDebug(`delete SSE session: ${transport.sessionId}`);
             sessions.delete(transport.sessionId);
-            connection.close().catch(e => {
-                // eslint-disable-next-line no-console
-                console.error(e);
-            });
+            // eslint-disable-next-line no-console
+            void connection.close().catch(e => console.error(e));
         });
         return;
     }
     res.statusCode = 405;
     res.end('Method not allowed');
 }
-async function handleStreamable(config, req, res, sessions, connectionList) {
+async function handleStreamable(server, req, res, sessions) {
     const sessionId = req.headers['mcp-session-id'];
     if (sessionId) {
         const transport = sessions.get(sessionId);
@@ -79,28 +76,25 @@ async function handleStreamable(config, req, res, sessions, connectionList) {
             if (transport.sessionId)
                 sessions.delete(transport.sessionId);
         };
-        const connection = await createConnection(config);
-        connectionList.push(connection);
-        await Promise.all([
-            connection.connect(transport),
-            transport.handleRequest(req, res),
-        ]);
+        await server.createConnection(transport);
+        await transport.handleRequest(req, res);
         return;
     }
     res.statusCode = 400;
     res.end('Invalid request');
 }
-export function startHttpTransport(config, port, hostname, connectionList) {
+export function startHttpTransport(server) {
     const sseSessions = new Map();
     const streamableSessions = new Map();
     const httpServer = http.createServer(async (req, res) => {
         const url = new URL(`http://localhost${req.url}`);
         if (url.pathname.startsWith('/mcp'))
-            await handleStreamable(config, req, res, streamableSessions, connectionList);
+            await handleStreamable(server, req, res, streamableSessions);
         else
-            await handleSSE(config, req, res, url, sseSessions, connectionList);
+            await handleSSE(server, req, res, url, sseSessions);
     });
-    httpServer.listen(port, hostname, () => {
+    const { host, port } = server.config.server;
+    httpServer.listen(port, host, () => {
         const address = httpServer.address();
         assert(address, 'Could not bind server socket');
         let url;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -37,14 +37,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-1746832516000",
+    "debug": "^4.4.1",
+    "playwright": "1.53.0-alpha-2025-05-27",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.53.0-alpha-1746832516000",
+    "@playwright/test": "1.53.0-alpha-2025-05-27",
     "@stylistic/eslint-plugin": "^3.0.1",
+    "@types/debug": "^4.1.12",
     "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",
     "@typescript-eslint/parser": "^8.26.1",