@playwright/mcp 0.0.22 → 0.0.24

package/README.md

@@ -207,7 +207,7 @@ And then in MCP client config, set the `url` to the SSE endpoint:
   "mcpServers": {
     "playwright": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
+      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
     }
   }
 }
@@ -216,7 +216,7 @@ And then in MCP client config, set the `url` to the SSE endpoint:
 You can build the Docker image yourself.
 
 ```
-docker build -t mcp/playwright .
+docker build -t mcr.microsoft.com/playwright/mcp .
 ```
 
 ### Programmatic usage
@@ -224,14 +224,14 @@ docker build -t mcp/playwright .
 ```js
 import http from 'http';
 
-import { createServer } from '@playwright/mcp';
+import { createConnection } from '@playwright/mcp';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 
 http.createServer(async (req, res) => {
   // ...
 
   // Creates a headless Playwright MCP server with SSE transport
-  const connection = await createConnection({ headless: true });
+  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
   const transport = new SSEServerTransport('/messages', res);
   await connection.connect(transport);
 
@@ -341,6 +341,7 @@ X Y coordinate space, based on the provided screenshot.
   - Description: Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.
   - Parameters:
     - `raw` (boolean, optional): Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.
+    - `filename` (string, optional): File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.
     - `element` (string, optional): Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.
     - `ref` (string, optional): Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.
   - Read-only: **true**
@@ -501,7 +502,8 @@ X Y coordinate space, based on the provided screenshot.
 - **browser_pdf_save**
   - Title: Save as PDF
   - Description: Save page as PDF
-  - Parameters: None
+  - Parameters:
+    - `filename` (string, optional): File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.
   - Read-only: **true**
 
 ### Utilities
@@ -516,11 +518,13 @@ X Y coordinate space, based on the provided screenshot.
 
 <!-- NOTE: This has been generated via update-readme.js -->
 
-- **browser_wait**
-  - Title: Wait
-  - Description: Wait for a specified time in seconds
+- **browser_wait_for**
+  - Title: Wait for
+  - Description: Wait for text to appear or disappear or a specified time to pass
   - Parameters:
-    - `time` (number): The time to wait in seconds
+    - `time` (number, optional): The time to wait in seconds
+    - `text` (string, optional): The text to wait for
+    - `textGone` (string, optional): The text to wait for to disappear
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->

package/config.d.ts

@@ -40,7 +40,7 @@ export type Config = {
      *
      * This is useful for settings options like `channel`, `headless`, `executablePath`, etc.
      */
-    launchOptions?: playwright.BrowserLaunchOptions;
+    launchOptions?: playwright.LaunchOptions;
 
     /**
      * Context options for the browser context.

package/index.js

@@ -16,4 +16,4 @@
  */
 
 import { createConnection } from './lib/index';
-export default { createConnection };
+export { createConnection };

package/lib/config.js

@@ -72,7 +72,7 @@ export async function configFromCLIOptions(cliOptions) {
         headless: cliOptions.headless,
     };
     if (browserName === 'chromium')
-        launchOptions.webSocketPort = await findFreePort();
+        launchOptions.cdpPort = await findFreePort();
     const contextOptions = cliOptions.device ? devices[cliOptions.device] : undefined;
     return {
         browser: {
@@ -138,7 +138,7 @@ function mergeConfig(base, overrides) {
             ...pickDefined(overrides.browser?.contextOptions),
         },
     };
-    if (browser.browserName !== 'chromium')
+    if (browser.browserName !== 'chromium' && browser.launchOptions)
         delete browser.launchOptions.channel;
     return {
         ...pickDefined(base),

package/lib/context.js

@@ -100,7 +100,7 @@ export class Context {
     }
     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 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)
@@ -316,7 +316,7 @@ 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;
 }

package/lib/index.js

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { createConnection as createConnectionImpl } from './connection.js';
 export async function createConnection(config = {}) {
-    return createConnection(config);
+    return createConnectionImpl(config);
 }

package/lib/pageSnapshot.js

@@ -13,22 +13,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import yaml from 'yaml';
 export class PageSnapshot {
-    _frameLocators = [];
+    _page;
     _text;
-    constructor() {
+    constructor(page) {
+        this._page = page;
     }
     static async create(page) {
-        const snapshot = new PageSnapshot();
-        await snapshot._build(page);
+        const snapshot = new PageSnapshot(page);
+        await snapshot._build();
         return snapshot;
     }
     text() {
         return this._text;
     }
-    async _build(page) {
-        const yamlDocument = await this._snapshotFrame(page);
+    async _build() {
+        const yamlDocument = await this._page._snapshotForAI();
         this._text = [
             `- Page Snapshot`,
             '```yaml',
@@ -36,54 +36,7 @@ export class PageSnapshot {
             '```',
         ].join('\n');
     }
-    async _snapshotFrame(frame) {
-        const frameIndex = this._frameLocators.push(frame) - 1;
-        const snapshotString = await frame.locator('body').ariaSnapshot({ ref: true, emitGeneric: true });
-        const snapshot = yaml.parseDocument(snapshotString);
-        const visit = async (node) => {
-            if (yaml.isPair(node)) {
-                await Promise.all([
-                    visit(node.key).then(k => node.key = k),
-                    visit(node.value).then(v => node.value = v)
-                ]);
-            }
-            else if (yaml.isSeq(node) || yaml.isMap(node)) {
-                node.items = await Promise.all(node.items.map(visit));
-            }
-            else if (yaml.isScalar(node)) {
-                if (typeof node.value === 'string') {
-                    const value = node.value;
-                    if (frameIndex > 0)
-                        node.value = value.replace('[ref=', `[ref=f${frameIndex}`);
-                    if (value.startsWith('iframe ')) {
-                        const ref = value.match(/\[ref=(.*)\]/)?.[1];
-                        if (ref) {
-                            try {
-                                const childSnapshot = await this._snapshotFrame(frame.frameLocator(`aria-ref=${ref}`));
-                                return snapshot.createPair(node.value, childSnapshot);
-                            }
-                            catch (error) {
-                                return snapshot.createPair(node.value, '<could not take iframe snapshot>');
-                            }
-                        }
-                    }
-                }
-            }
-            return node;
-        };
-        await visit(snapshot.contents);
-        return snapshot;
-    }
     refLocator(ref) {
-        let frame = this._frameLocators[0];
-        const match = ref.match(/^f(\d+)(.*)/);
-        if (match) {
-            const frameIndex = parseInt(match[1], 10);
-            frame = this._frameLocators[frameIndex];
-            ref = match[2];
-        }
-        if (!frame)
-            throw new Error(`Frame does not exist. Provide ref from the most current snapshot.`);
-        return frame.locator(`aria-ref=${ref}`);
+        return this._page.locator(`aria-ref=${ref}`);
     }
 }

package/lib/tab.js

@@ -17,7 +17,7 @@ import { PageSnapshot } from './pageSnapshot.js';
 export class Tab {
     context;
     page;
-    _console = [];
+    _consoleMessages = [];
     _requests = new Map();
     _snapshot;
     _onPageClose;
@@ -25,13 +25,9 @@ export class Tab {
         this.context = context;
         this.page = page;
         this._onPageClose = onPageClose;
-        page.on('console', event => this._console.push(event));
+        page.on('console', event => this._consoleMessages.push(event));
         page.on('request', request => this._requests.set(request, null));
         page.on('response', response => this._requests.set(response.request(), response));
-        page.on('framenavigated', frame => {
-            if (!frame.parentFrame())
-                this._clearCollectedArtifacts();
-        });
         page.on('close', () => this._onClose());
         page.on('filechooser', chooser => {
             this.context.setModalState({
@@ -48,7 +44,7 @@ export class Tab {
         page.setDefaultTimeout(5000);
     }
     _clearCollectedArtifacts() {
-        this._console.length = 0;
+        this._consoleMessages.length = 0;
         this._requests.clear();
     }
     _onClose() {
@@ -56,6 +52,7 @@ export class Tab {
         this._onPageClose(this);
     }
     async navigate(url) {
+        this._clearCollectedArtifacts();
         const downloadEvent = this.page.waitForEvent('download').catch(() => { });
         try {
             await this.page.goto(url, { waitUntil: 'domcontentloaded' });
@@ -85,8 +82,8 @@ export class Tab {
             throw new Error('No snapshot available');
         return this._snapshot;
     }
-    console() {
-        return this._console;
+    consoleMessages() {
+        return this._consoleMessages;
     }
     requests() {
         return this._requests;

package/lib/tools/common.js

@@ -18,18 +18,37 @@ import { defineTool } from './tool.js';
 const wait = captureSnapshot => defineTool({
     capability: 'wait',
     schema: {
-        name: 'browser_wait',
-        title: 'Wait',
-        description: 'Wait for a specified time in seconds',
+        name: 'browser_wait_for',
+        title: 'Wait for',
+        description: 'Wait for text to appear or disappear or a specified time to pass',
         inputSchema: z.object({
-            time: z.number().describe('The time to wait in seconds'),
+            time: z.number().optional().describe('The time to wait in seconds'),
+            text: z.string().optional().describe('The text to wait for'),
+            textGone: z.string().optional().describe('The text to wait for to disappear'),
         }),
         type: 'readOnly',
     },
     handle: async (context, params) => {
-        await new Promise(f => setTimeout(f, Math.min(10000, params.time * 1000)));
+        if (!params.text && !params.textGone && !params.time)
+            throw new Error('Either time, text or textGone must be provided');
+        const code = [];
+        if (params.time) {
+            code.push(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
+            await new Promise(f => setTimeout(f, Math.min(10000, params.time * 1000)));
+        }
+        const tab = context.currentTabOrDie();
+        const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
+        const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
+        if (goneLocator) {
+            code.push(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+            await goneLocator.waitFor({ state: 'hidden' });
+        }
+        if (locator) {
+            code.push(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+            await locator.waitFor({ state: 'visible' });
+        }
         return {
-            code: [`// Waited for ${params.time} seconds`],
+            code,
             captureSnapshot,
             waitForNetwork: false,
         };

package/lib/tools/console.js

@@ -25,7 +25,7 @@ const console = defineTool({
         type: 'readOnly',
     },
     handle: async (context) => {
-        const messages = context.currentTabOrDie().console();
+        const messages = context.currentTabOrDie().consoleMessages();
         const log = messages.map(message => `[${message.type().toUpperCase()}] ${message.text()}`).join('\n');
         return {
             code: [`// <internal code to get console messages>`],

package/lib/tools/install.js

@@ -28,7 +28,7 @@ const install = defineTool({
         type: 'destructive',
     },
     handle: async (context) => {
-        const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.launchOptions.browserName ?? 'chrome';
+        const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'chrome';
         const cliUrl = import.meta.resolve('playwright/package.json');
         const cliPath = path.join(fileURLToPath(cliUrl), '..', 'cli.js');
         const child = fork(cliPath, ['install', channel], {

package/lib/tools/pdf.js

@@ -17,18 +17,21 @@ import { z } from 'zod';
 import { defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { outputFile } from '../config.js';
+const pdfSchema = z.object({
+    filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
+});
 const pdf = defineTool({
     capability: 'pdf',
     schema: {
         name: 'browser_pdf_save',
         title: 'Save as PDF',
         description: 'Save page as PDF',
-        inputSchema: z.object({}),
+        inputSchema: pdfSchema,
         type: 'readOnly',
     },
-    handle: async (context) => {
+    handle: async (context, params) => {
         const tab = context.currentTabOrDie();
-        const fileName = await outputFile(context.config, `page-${new Date().toISOString()}.pdf`);
+        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
         const code = [
             `// Save page as ${fileName}`,
             `await page.pdf(${javascript.formatObject({ path: fileName })});`,

package/lib/tools/snapshot.js

@@ -188,6 +188,7 @@ const selectOption = defineTool({
 });
 const screenshotSchema = z.object({
     raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+    filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
     element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
     ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
 }).refine(data => {
@@ -209,7 +210,7 @@ const screenshot = defineTool({
         const tab = context.currentTabOrDie();
         const snapshot = tab.snapshotOrDie();
         const fileType = params.raw ? 'png' : 'jpeg';
-        const fileName = await outputFile(context.config, `page-${new Date().toISOString()}.${fileType}`);
+        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
         const options = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
         const isElementScreenshot = params.element && params.ref;
         const code = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playwright/mcp",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Playwright Tools for MCP",
   "type": "module",
   "repository": {
@@ -37,14 +37,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
     "commander": "^13.1.0",
-    "playwright": "1.53.0-alpha-1746218818000",
-    "yaml": "^2.7.1",
+    "playwright": "1.53.0-alpha-1746832516000",
     "zod-to-json-schema": "^3.24.4"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.2.0",
     "@eslint/js": "^9.19.0",
-    "@playwright/test": "1.53.0-alpha-1746218818000",
+    "@playwright/test": "1.53.0-alpha-1746832516000",
     "@stylistic/eslint-plugin": "^3.0.1",
     "@types/node": "^22.13.10",
     "@typescript-eslint/eslint-plugin": "^8.26.1",