@playwright/mcp 0.0.20 → 0.0.24

package/lib/context.js

@@ -13,6 +13,10 @@
  * 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 { waitForCompletion } from './tools/utils.js';
 import { ManualPromise } from './manualPromise.js';
@@ -96,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)
@@ -237,11 +241,23 @@ ${code.join('\n')}
             await browser?.close();
         }).catch(() => { });
     }
+    async _setupRequestInterception(context) {
+        if (this.config.network?.allowedOrigins?.length) {
+            await context.route('**', route => route.abort('blockedbyclient'));
+            for (const origin of this.config.network.allowedOrigins)
+                await context.route(`*://${origin}/**`, route => route.continue());
+        }
+        if (this.config.network?.blockedOrigins?.length) {
+            for (const origin of this.config.network.blockedOrigins)
+                await context.route(`*://${origin}/**`, route => route.abort('blockedbyclient'));
+        }
+    }
     async _ensureBrowserContext() {
         if (!this._browserContext) {
             const context = await this._createBrowserContext();
             this._browser = context.browser;
             this._browserContext = context.browserContext;
+            await this._setupRequestInterception(this._browserContext);
             for (const page of this._browserContext.pages())
                 this._onPageCreated(page);
             this._browserContext.on('page', page => this._onPageCreated(page));
@@ -279,8 +295,10 @@ ${code.join('\n')}
 }
 async function launchPersistentContext(browserConfig) {
     try {
-        const browserType = browserConfig?.browserName ? playwright[browserConfig.browserName] : playwright.chromium;
-        return await browserType.launchPersistentContext(browserConfig?.userDataDir || '', { ...browserConfig?.launchOptions, ...browserConfig?.contextOptions });
+        const browserName = browserConfig?.browserName ?? 'chromium';
+        const userDataDir = browserConfig?.userDataDir ?? await createUserDataDir({ ...browserConfig, browserName });
+        const browserType = playwright[browserName];
+        return await browserType.launchPersistentContext(userDataDir, { ...browserConfig?.launchOptions, ...browserConfig?.contextOptions });
     }
     catch (error) {
         if (error.message.includes('Executable doesn\'t exist'))
@@ -288,6 +306,22 @@ async function launchPersistentContext(browserConfig) {
         throw error;
     }
 }
+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;
+}
 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

@@ -13,55 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createServerWithTools } from './server.js';
-import common from './tools/common.js';
-import console from './tools/console.js';
-import dialogs from './tools/dialogs.js';
-import files from './tools/files.js';
-import install from './tools/install.js';
-import keyboard from './tools/keyboard.js';
-import navigate from './tools/navigate.js';
-import network from './tools/network.js';
-import pdf from './tools/pdf.js';
-import snapshot from './tools/snapshot.js';
-import tabs from './tools/tabs.js';
-import screen from './tools/screen.js';
-import testing from './tools/testing.js';
-const snapshotTools = [
-    ...common(true),
-    ...console,
-    ...dialogs(true),
-    ...files(true),
-    ...install,
-    ...keyboard(true),
-    ...navigate(true),
-    ...network,
-    ...pdf,
-    ...snapshot,
-    ...tabs(true),
-    ...testing,
-];
-const screenshotTools = [
-    ...common(false),
-    ...console,
-    ...dialogs(false),
-    ...files(false),
-    ...install,
-    ...keyboard(false),
-    ...navigate(false),
-    ...network,
-    ...pdf,
-    ...screen,
-    ...tabs(false),
-    ...testing,
-];
-import packageJSON from '../package.json' with { type: 'json' };
-export async function createServer(config = {}) {
-    const allTools = config.vision ? screenshotTools : snapshotTools;
-    const tools = allTools.filter(tool => !config.capabilities || tool.capability === 'core' || config.capabilities.includes(tool.capability));
-    return createServerWithTools({
-        name: 'Playwright',
-        version: packageJSON.version,
-        tools,
-    }, config);
+import { createConnection as createConnectionImpl } from './connection.js';
+export async function 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/program.js

@@ -14,11 +14,9 @@
  * limitations under the License.
  */
 import { program } from 'commander';
-import { createServer } from './index.js';
-import { ServerList } from './server.js';
 import { startHttpTransport, startStdioTransport } from './transport.js';
 import { resolveConfig } from './config.js';
-import packageJSON from '../package.json' with { type: 'json' };
+import { packageJSON } from './context.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -31,25 +29,33 @@ program
     .option('--user-data-dir <path>', 'Path to the user data directory')
     .option('--port <port>', 'Port to listen on for SSE transport.')
     .option('--host <host>', 'Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--allowed-origins <origins>', 'Semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
+    .option('--blocked-origins <origins>', 'Semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')
+    .option('--no-image-responses', 'Do not send image responses to the client.')
+    .option('--output-dir <path>', 'Path to the directory for output files.')
     .option('--config <path>', 'Path to the configuration file.')
     .action(async (options) => {
     const config = await resolveConfig(options);
-    const serverList = new ServerList(() => createServer(config));
-    setupExitWatchdog(serverList);
+    const connectionList = [];
+    setupExitWatchdog(connectionList);
     if (options.port)
-        startHttpTransport(+options.port, options.host, serverList);
+        startHttpTransport(config, +options.port, options.host, connectionList);
     else
-        await startStdioTransport(serverList);
+        await startStdioTransport(config, connectionList);
 });
-function setupExitWatchdog(serverList) {
+function setupExitWatchdog(connectionList) {
     const handleExit = async () => {
         setTimeout(() => process.exit(0), 15000);
-        await serverList.closeAll();
+        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);

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,7 +52,25 @@ export class Tab {
         this._onPageClose(this);
     }
     async navigate(url) {
-        await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+        this._clearCollectedArtifacts();
+        const downloadEvent = this.page.waitForEvent('download').catch(() => { });
+        try {
+            await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+        }
+        catch (_e) {
+            const e = _e;
+            const mightBeDownload = e.message.includes('net::ERR_ABORTED') // chromium
+                || e.message.includes('Download is starting'); // firefox + webkit
+            if (!mightBeDownload)
+                throw e;
+            // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
+            const download = await Promise.race([
+                downloadEvent,
+                new Promise(resolve => setTimeout(resolve, 500)),
+            ]);
+            if (!download)
+                throw e;
+        }
         // Cap load event to 5 seconds, the page is operational at this point.
         await this.page.waitForLoadState('load', { timeout: 5000 }).catch(() => { });
     }
@@ -68,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,16 +18,37 @@ import { defineTool } from './tool.js';
 const wait = captureSnapshot => defineTool({
     capability: 'wait',
     schema: {
-        name: 'browser_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,
         };
@@ -37,8 +58,10 @@ const close = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_close',
+        title: 'Close browser',
         description: 'Close the page',
         inputSchema: z.object({}),
+        type: 'readOnly',
     },
     handle: async (context) => {
         await context.close();
@@ -53,11 +76,13 @@ const resize = captureSnapshot => defineTool({
     capability: 'core',
     schema: {
         name: 'browser_resize',
+        title: 'Resize browser window',
         description: 'Resize the browser window',
         inputSchema: z.object({
             width: z.number().describe('Width of the browser window'),
             height: z.number().describe('Height of the browser window'),
         }),
+        type: 'readOnly',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();

package/lib/tools/console.js

@@ -19,11 +19,13 @@ const console = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_console_messages',
+        title: 'Get console messages',
         description: 'Returns all console messages',
         inputSchema: z.object({}),
+        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/dialogs.js

@@ -19,11 +19,13 @@ const handleDialog = captureSnapshot => defineTool({
     capability: 'core',
     schema: {
         name: 'browser_handle_dialog',
+        title: 'Handle a dialog',
         description: 'Handle a dialog',
         inputSchema: z.object({
             accept: z.boolean().describe('Whether to accept the dialog.'),
             promptText: z.string().optional().describe('The text of the prompt in case of a prompt dialog.'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const dialogState = context.modalStates().find(state => state.type === 'dialog');

package/lib/tools/files.js

@@ -19,10 +19,12 @@ const uploadFile = captureSnapshot => defineTool({
     capability: 'files',
     schema: {
         name: 'browser_file_upload',
+        title: 'Upload files',
         description: 'Upload one or multiple files',
         inputSchema: z.object({
             paths: z.array(z.string()).describe('The absolute paths to the files to upload. Can be a single file or multiple files.'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const modalState = context.modalStates().find(state => state.type === 'fileChooser');

package/lib/tools/install.js

@@ -17,19 +17,21 @@ import { fork } from 'child_process';
 import path from 'path';
 import { z } from 'zod';
 import { defineTool } from './tool.js';
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
+import { fileURLToPath } from 'node:url';
 const install = defineTool({
     capability: 'install',
     schema: {
         name: 'browser_install',
+        title: 'Install the browser specified in the config',
         description: 'Install the browser specified in the config. Call this if you get an error about the browser not being installed.',
         inputSchema: z.object({}),
+        type: 'destructive',
     },
     handle: async (context) => {
-        const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.launchOptions.browserName ?? 'chrome';
-        const cli = path.join(require.resolve('playwright/package.json'), '..', 'cli.js');
-        const child = fork(cli, ['install', channel], {
+        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], {
             stdio: 'pipe',
         });
         const output = [];

package/lib/tools/keyboard.js

@@ -19,10 +19,12 @@ const pressKey = captureSnapshot => defineTool({
     capability: 'core',
     schema: {
         name: 'browser_press_key',
+        title: 'Press a key',
         description: 'Press a key on the keyboard',
         inputSchema: z.object({
             key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();

package/lib/tools/navigate.js

@@ -19,10 +19,12 @@ const navigate = captureSnapshot => defineTool({
     capability: 'core',
     schema: {
         name: 'browser_navigate',
+        title: 'Navigate to a URL',
         description: 'Navigate to a URL',
         inputSchema: z.object({
             url: z.string().describe('The URL to navigate to'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = await context.ensureTab();
@@ -42,8 +44,10 @@ const goBack = captureSnapshot => defineTool({
     capability: 'history',
     schema: {
         name: 'browser_navigate_back',
+        title: 'Go back',
         description: 'Go back to the previous page',
         inputSchema: z.object({}),
+        type: 'readOnly',
     },
     handle: async (context) => {
         const tab = await context.ensureTab();
@@ -63,8 +67,10 @@ const goForward = captureSnapshot => defineTool({
     capability: 'history',
     schema: {
         name: 'browser_navigate_forward',
+        title: 'Go forward',
         description: 'Go forward to the next page',
         inputSchema: z.object({}),
+        type: 'readOnly',
     },
     handle: async (context) => {
         const tab = context.currentTabOrDie();

package/lib/tools/network.js

@@ -19,8 +19,10 @@ const requests = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_network_requests',
+        title: 'List network requests',
         description: 'Returns all network requests since loading the page',
         inputSchema: z.object({}),
+        type: 'readOnly',
     },
     handle: async (context) => {
         const requests = context.currentTabOrDie().requests();

package/lib/tools/pdf.js

@@ -17,16 +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/screen.js

@@ -23,8 +23,10 @@ const screenshot = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_screen_capture',
+        title: 'Take a screenshot',
         description: 'Take a screenshot of the current page',
         inputSchema: z.object({}),
+        type: 'readOnly',
     },
     handle: async (context) => {
         const tab = await context.ensureTab();
@@ -50,11 +52,13 @@ const moveMouse = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_screen_move_mouse',
+        title: 'Move mouse',
         description: 'Move mouse to a given position',
         inputSchema: elementSchema.extend({
             x: z.number().describe('X coordinate'),
             y: z.number().describe('Y coordinate'),
         }),
+        type: 'readOnly',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();
@@ -75,11 +79,13 @@ const click = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_screen_click',
+        title: 'Click',
         description: 'Click left mouse button',
         inputSchema: elementSchema.extend({
             x: z.number().describe('X coordinate'),
             y: z.number().describe('Y coordinate'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();
@@ -106,6 +112,7 @@ const drag = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_screen_drag',
+        title: 'Drag mouse',
         description: 'Drag left mouse button',
         inputSchema: elementSchema.extend({
             startX: z.number().describe('Start X coordinate'),
@@ -113,6 +120,7 @@ const drag = defineTool({
             endX: z.number().describe('End X coordinate'),
             endY: z.number().describe('End Y coordinate'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();
@@ -141,11 +149,13 @@ const type = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_screen_type',
+        title: 'Type text',
         description: 'Type text',
         inputSchema: z.object({
             text: z.string().describe('Text to type into the element'),
             submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
         }),
+        type: 'destructive',
     },
     handle: async (context, params) => {
         const tab = context.currentTabOrDie();