@playwright/mcp 0.0.25 → 0.0.27

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.
@@ -146,6 +149,8 @@ Playwright MCP server supports following arguments. They can be provided in the
                                example ".com,chromium.org,.domain.com"
   --proxy-server <proxy>       specify proxy server, for example
                                "http://myproxy:3128" or "socks5://myproxy:8080"
+  --save-trace                 Whether to save the Playwright Trace of the
+                               session into the output directory.
   --storage-state <path>       path to the storage state file for isolated
                                sessions.
   --user-agent <ua string>     specify user agent string

package/config.d.ts

@@ -94,6 +94,11 @@ export type Config = {
    */
   vision?: boolean;
 
+  /**
+   * Whether to save the Playwright trace of the session into the output directory.
+   */
+  saveTrace?: boolean;
+
   /**
    * The directory to save output files.
    */
@@ -112,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.js

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

package/lib/config.js

@@ -35,11 +35,21 @@ const defaultConfig = {
         allowedOrigins: undefined,
         blockedOrigins: undefined,
     },
+    outputDir: path.join(os.tmpdir(), 'playwright-mcp-output', sanitizeForFilePath(new Date().toISOString())),
 };
-export async function resolveConfig(cliOptions) {
-    const config = await loadConfig(cliOptions.config);
+export async function resolveConfig(config) {
+    return mergeConfig(defaultConfig, config);
+}
+export async function resolveCLIConfig(cliOptions) {
+    const configInFile = await loadConfig(cliOptions.config);
     const cliOverrides = await configFromCLIOptions(cliOptions);
-    return mergeConfig(defaultConfig, mergeConfig(config, cliOverrides));
+    const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+    // 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) {
     let browserName;
@@ -63,9 +73,6 @@ export async function configFromCLIOptions(cliOptions) {
         case 'webkit':
             browserName = 'webkit';
             break;
-        default:
-            browserName = 'chromium';
-            channel = 'chrome';
     }
     // Launch options
     const launchOptions = {
@@ -73,13 +80,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
@@ -127,12 +130,10 @@ export async function configFromCLIOptions(cliOptions) {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
         },
+        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() {
@@ -156,18 +157,17 @@ async function loadConfig(configFile) {
     }
 }
 export async function outputFile(config, name) {
-    const result = config.outputDir ?? os.tmpdir();
-    await fs.promises.mkdir(result, { recursive: true });
+    await fs.promises.mkdir(config.outputDir, { recursive: true });
     const fileName = sanitizeForFilePath(name);
-    return path.join(result, fileName);
+    return path.join(config.outputDir, fileName);
 }
 function pickDefined(obj) {
     return Object.fromEntries(Object.entries(obj ?? {}).filter(([_, v]) => v !== undefined));
 }
 function mergeConfig(base, overrides) {
     const browser = {
-        ...pickDefined(base.browser),
-        ...pickDefined(overrides.browser),
+        browserName: overrides.browser?.browserName ?? base.browser?.browserName ?? 'chromium',
+        isolated: overrides.browser?.isolated ?? base.browser?.isolated ?? false,
         launchOptions: {
             ...pickDefined(base.browser?.launchOptions),
             ...pickDefined(overrides.browser?.launchOptions),
@@ -177,6 +177,9 @@ function mergeConfig(base, overrides) {
             ...pickDefined(base.browser?.contextOptions),
             ...pickDefined(overrides.browser?.contextOptions),
         },
+        userDataDir: overrides.browser?.userDataDir ?? base.browser?.userDataDir,
+        cdpEndpoint: overrides.browser?.cdpEndpoint ?? base.browser?.cdpEndpoint,
+        remoteEndpoint: overrides.browser?.remoteEndpoint ?? base.browser?.remoteEndpoint,
     };
     if (browser.browserName !== 'chromium' && browser.launchOptions)
         delete browser.launchOptions.channel;
@@ -187,6 +190,6 @@ function mergeConfig(base, overrides) {
         network: {
             ...pickDefined(base.network),
             ...pickDefined(overrides.network),
-        },
+        }
     };
 }

package/lib/connection.js

@@ -77,8 +77,7 @@ export class Connection {
         await new Promise(resolve => {
             this.server.oninitialized = () => resolve();
         });
-        if (this.server.getClientVersion()?.name.includes('cursor'))
-            this.context.config.noImageResponses = true;
+        this.context.clientVersion = this.server.getClientVersion();
     }
     async close() {
         await this.server.close();

package/lib/context.js

@@ -18,7 +18,7 @@ import url from 'node:url';
 import os from 'node:os';
 import path from 'node:path';
 import * as playwright from 'playwright';
-import { waitForCompletion } from './tools/utils.js';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
 import { Tab } from './tab.js';
 import { outputFile } from './config.js';
@@ -31,10 +31,18 @@ export class Context {
     _modalStates = [];
     _pendingAction;
     _downloads = [];
+    clientVersion;
     constructor(tools, config) {
         this.tools = tools;
         this.config = config;
     }
+    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;
     }
@@ -84,7 +92,7 @@ export class Context {
         const lines = ['### Open tabs'];
         for (let i = 0; i < this._tabs.length; i++) {
             const tab = this._tabs[i];
-            const title = await tab.page.title();
+            const title = await tab.title();
             const url = tab.page.url();
             const current = tab === this._currentTab ? ' (current)' : '';
             lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
@@ -116,7 +124,7 @@ export class Context {
         let actionResult;
         try {
             if (waitForNetwork)
-                actionResult = await waitForCompletion(this, tab.page, async () => racingAction?.()) ?? undefined;
+                actionResult = await waitForCompletion(this, tab, async () => racingAction?.()) ?? undefined;
             else
                 actionResult = await racingAction?.() ?? undefined;
         }
@@ -153,7 +161,7 @@ ${code.join('\n')}
             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.page.title()}`);
+        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 ?? [];
@@ -168,10 +176,13 @@ ${code.join('\n')}
         };
     }
     async waitForTimeout(time) {
-        if (this._currentTab && !this._javaScriptBlocked())
-            await this._currentTab.page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
-        else
+        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 = {
@@ -233,6 +244,8 @@ ${code.join('\n')}
         const promise = this._browserContextPromise;
         this._browserContextPromise = undefined;
         await promise.then(async ({ browserContext, browser }) => {
+            if (this.config.saveTrace)
+                await browserContext.tracing.stop();
             await browserContext.close().then(async () => {
                 await browser?.close();
             }).catch(() => { });
@@ -264,6 +277,14 @@ ${code.join('\n')}
         for (const page of browserContext.pages())
             this._onPageCreated(page);
         browserContext.on('page', page => this._onPageCreated(page));
+        if (this.config.saveTrace) {
+            await browserContext.tracing.start({
+                name: 'trace',
+                screenshots: false,
+                snapshots: true,
+                sources: false,
+            });
+        }
         return { browser, browserContext };
     }
     async _createBrowserContext() {
@@ -291,8 +312,8 @@ 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);
+        const browser = await browserType.launch(browserConfig.launchOptions);
+        const browserContext = await browser.newContext(browserConfig.contextOptions);
         return { browser, browserContext };
     }
     catch (error) {
@@ -303,10 +324,10 @@ async function createIsolatedContext(browserConfig) {
 }
 async function launchPersistentContext(browserConfig) {
     try {
-        const browserName = browserConfig?.browserName ?? 'chromium';
-        const userDataDir = browserConfig?.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
+        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 });
+        const browserContext = await browserType.launchPersistentContext(userDataDir, { ...browserConfig.launchOptions, ...browserConfig.contextOptions });
         return { browserContext };
     }
     catch (error) {
@@ -325,12 +346,9 @@ async function createUserDataDir(browserConfig) {
         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`);
+    const result = path.join(cacheDirectory, 'ms-playwright', `mcp-${browserConfig.launchOptions?.channel ?? browserConfig?.browserName}-profile`);
     await fs.promises.mkdir(result, { recursive: true });
     return result;
 }
-export async function generateLocator(locator) {
-    return locator._generateLocatorString();
-}
 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

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 import { createConnection as createConnectionImpl } from './connection.js';
-export async function createConnection(config = {}) {
+import { resolveConfig } from './config.js';
+export async function createConnection(userConfig = {}) {
+    const config = await resolveConfig(userConfig);
     return createConnectionImpl(config);
 }

package/lib/pageSnapshot.js

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { callOnPageNoTrace } from './tools/utils.js';
 export class PageSnapshot {
     _page;
     _text;
@@ -28,15 +29,15 @@ export class PageSnapshot {
         return this._text;
     }
     async _build() {
-        const yamlDocument = await this._page._snapshotForAI();
+        const snapshot = await callOnPageNoTrace(this._page, page => page._snapshotForAI());
         this._text = [
             `- Page Snapshot`,
             '```yaml',
-            yamlDocument.toString({ indentSeq: false }).trim(),
+            snapshot,
             '```',
         ].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

@@ -15,7 +15,9 @@
  */
 import { program } from 'commander';
 import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveConfig } from './config.js';
+import { resolveCLIConfig } from './config.js';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
 import { packageJSON } from './context.js';
 program
     .version('Version ' + packageJSON.version)
@@ -33,25 +35,33 @@ 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.')
     .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
     .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
     .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
     .option('--user-agent <ua string>', 'specify user agent string')
     .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
     .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
     .action(async (options) => {
-    const config = await resolveConfig(options);
+    const config = await resolveCLIConfig(options);
     const connectionList = [];
     setupExitWatchdog(connectionList);
     if (options.port)
         startHttpTransport(config, +options.port, options.host, connectionList);
     else
         await startStdioTransport(config, connectionList);
+    if (config.saveTrace) {
+        const server = await startTraceViewerServer();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+    }
 });
 function setupExitWatchdog(connectionList) {
     const handleExit = async () => {

package/lib/tab.js

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 import { PageSnapshot } from './pageSnapshot.js';
+import { callOnPageNoTrace } from './tools/utils.js';
 export class Tab {
     context;
     page;
@@ -51,9 +52,15 @@ export class Tab {
         this._clearCollectedArtifacts();
         this._onPageClose(this);
     }
+    async title() {
+        return await callOnPageNoTrace(this.page, page => page.title());
+    }
+    async waitForLoadState(state, options) {
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => { }));
+    }
     async navigate(url) {
         this._clearCollectedArtifacts();
-        const downloadEvent = this.page.waitForEvent('download').catch(() => { });
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => { }));
         try {
             await this.page.goto(url, { waitUntil: 'domcontentloaded' });
         }
@@ -72,7 +79,7 @@ export class Tab {
                 throw e;
         }
         // Cap load event to 5 seconds, the page is operational at this point.
-        await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => { });
+        await this.waitForLoadState('load', { timeout: 5000 });
     }
     hasSnapshot() {
         return !!this._snapshot;

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

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export async function waitForCompletion(context, page, callback) {
+export async function waitForCompletion(context, tab, callback) {
     const requests = new Set();
     let frameNavigated = false;
     let waitCallback = () => { };
@@ -30,22 +30,20 @@ export async function waitForCompletion(context, page, callback) {
         frameNavigated = true;
         dispose();
         clearTimeout(timeout);
-        void frame.waitForLoadState('load').then(() => {
-            waitCallback();
-        });
+        void tab.waitForLoadState('load').then(waitCallback);
     };
     const onTimeout = () => {
         dispose();
         waitCallback();
     };
-    page.on('request', requestListener);
-    page.on('requestfinished', requestFinishedListener);
-    page.on('framenavigated', frameNavigateListener);
+    tab.page.on('request', requestListener);
+    tab.page.on('requestfinished', requestFinishedListener);
+    tab.page.on('framenavigated', frameNavigateListener);
     const timeout = setTimeout(onTimeout, 10000);
     const dispose = () => {
-        page.off('request', requestListener);
-        page.off('requestfinished', requestFinishedListener);
-        page.off('framenavigated', frameNavigateListener);
+        tab.page.off('request', requestListener);
+        tab.page.off('requestfinished', requestFinishedListener);
+        tab.page.off('framenavigated', frameNavigateListener);
         clearTimeout(timeout);
     };
     try {
@@ -70,3 +68,6 @@ export function sanitizeForFilePath(s) {
 export async function generateLocator(locator) {
     return locator._generateLocatorString();
 }
+export async function callOnPageNoTrace(page, callback) {
+    return await page._wrapApiCall(() => callback(page), { internal: true });
+}

package/lib/transport.js

@@ -127,6 +127,6 @@ export function startHttpTransport(config, port, hostname, connectionList) {
             'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
         ].join('\n');
         // eslint-disable-next-line no-console
-        console.log(message);
+        console.error(message);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -37,13 +37,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-1746832516000",
+    "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/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",