@playwright/mcp 0.0.29 → 0.0.31

package/config.d.ts

@@ -16,18 +16,13 @@
 
 import type * as playwright from 'playwright';
 
-export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files' | 'install' | 'testing';
+export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf';
 
 export type Config = {
   /**
    * The browser to use.
    */
   browser?: {
-    /**
-     * Use browser agent (experimental).
-     */
-    browserAgent?: string;
-
     /**
      * The type of browser to use.
      */
@@ -85,20 +80,11 @@ export type Config = {
   /**
    * List of enabled tool capabilities. Possible values:
    *   - 'core': Core browser automation features.
-   *   - 'tabs': Tab management features.
    *   - 'pdf': PDF generation and manipulation.
-   *   - 'history': Browser history access.
-   *   - 'wait': Wait and timing utilities.
-   *   - 'files': File upload/download support.
-   *   - 'install': Browser installation utilities.
+   *   - 'vision': Coordinate-based interactions.
    */
   capabilities?: ToolCapability[];
 
-  /**
-   * Run server that uses screenshots (Aria snapshots are used by default).
-   */
-  vision?: boolean;
-
   /**
    * Whether to save the Playwright trace of the session into the output directory.
    */
@@ -124,5 +110,5 @@ export type Config = {
   /**
    * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
    */
-  imageResponses?: 'allow' | 'omit' | 'auto';
+  imageResponses?: 'allow' | 'omit';
 };

package/lib/browserContextFactory.js

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

package/lib/config.js

@@ -42,14 +42,18 @@ export async function resolveConfig(config) {
 }
 export async function resolveCLIConfig(cliOptions) {
     const configInFile = await loadConfig(cliOptions.config);
-    const cliOverrides = await configFromCLIOptions(cliOptions);
-    const result = mergeConfig(mergeConfig(defaultConfig, configInFile), cliOverrides);
+    const envOverrides = configFromEnv();
+    const cliOverrides = configFromCLIOptions(cliOptions);
+    let result = defaultConfig;
+    result = mergeConfig(result, configInFile);
+    result = mergeConfig(result, envOverrides);
+    result = mergeConfig(result, cliOverrides);
     // Derive artifact output directory from config.outputDir
     if (result.saveTrace)
         result.browser.launchOptions.tracesDir = path.join(result.outputDir, 'traces');
     return result;
 }
-export async function configFromCLIOptions(cliOptions) {
+export function configFromCLIOptions(cliOptions) {
     let browserName;
     let channel;
     switch (cliOptions.browser) {
@@ -88,6 +92,8 @@ export async function configFromCLIOptions(cliOptions) {
         if (cliOptions.proxyBypass)
             launchOptions.proxy.bypass = cliOptions.proxyBypass;
     }
+    if (cliOptions.device && cliOptions.cdpEndpoint)
+        throw new Error('Device emulation is not supported with cdpEndpoint.');
     // Context options
     const contextOptions = cliOptions.device ? devices[cliOptions.device] : {};
     if (cliOptions.storageState)
@@ -111,7 +117,6 @@ export async function configFromCLIOptions(cliOptions) {
         contextOptions.serviceWorkers = 'block';
     const result = {
         browser: {
-            browserAgent: cliOptions.browserAgent ?? process.env.PW_BROWSER_AGENT,
             browserName,
             isolated: cliOptions.isolated,
             userDataDir: cliOptions.userDataDir,
@@ -123,8 +128,7 @@ export async function configFromCLIOptions(cliOptions) {
             port: cliOptions.port,
             host: cliOptions.host,
         },
-        capabilities: cliOptions.caps?.split(',').map((c) => c.trim()),
-        vision: !!cliOptions.vision,
+        capabilities: cliOptions.caps,
         network: {
             allowedOrigins: cliOptions.allowedOrigins,
             blockedOrigins: cliOptions.blockedOrigins,
@@ -135,6 +139,35 @@ export async function configFromCLIOptions(cliOptions) {
     };
     return result;
 }
+function configFromEnv() {
+    const options = {};
+    options.allowedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_ALLOWED_ORIGINS);
+    options.blockedOrigins = semicolonSeparatedList(process.env.PLAYWRIGHT_MCP_BLOCKED_ORIGINS);
+    options.blockServiceWorkers = envToBoolean(process.env.PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS);
+    options.browser = envToString(process.env.PLAYWRIGHT_MCP_BROWSER);
+    options.caps = commaSeparatedList(process.env.PLAYWRIGHT_MCP_CAPS);
+    options.cdpEndpoint = envToString(process.env.PLAYWRIGHT_MCP_CDP_ENDPOINT);
+    options.config = envToString(process.env.PLAYWRIGHT_MCP_CONFIG);
+    options.device = envToString(process.env.PLAYWRIGHT_MCP_DEVICE);
+    options.executablePath = envToString(process.env.PLAYWRIGHT_MCP_EXECUTABLE_PATH);
+    options.headless = envToBoolean(process.env.PLAYWRIGHT_MCP_HEADLESS);
+    options.host = envToString(process.env.PLAYWRIGHT_MCP_HOST);
+    options.ignoreHttpsErrors = envToBoolean(process.env.PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS);
+    options.isolated = envToBoolean(process.env.PLAYWRIGHT_MCP_ISOLATED);
+    if (process.env.PLAYWRIGHT_MCP_IMAGE_RESPONSES === 'omit')
+        options.imageResponses = 'omit';
+    options.sandbox = envToBoolean(process.env.PLAYWRIGHT_MCP_SANDBOX);
+    options.outputDir = envToString(process.env.PLAYWRIGHT_MCP_OUTPUT_DIR);
+    options.port = envToNumber(process.env.PLAYWRIGHT_MCP_PORT);
+    options.proxyBypass = envToString(process.env.PLAYWRIGHT_MCP_PROXY_BYPASS);
+    options.proxyServer = envToString(process.env.PLAYWRIGHT_MCP_PROXY_SERVER);
+    options.saveTrace = envToBoolean(process.env.PLAYWRIGHT_MCP_SAVE_TRACE);
+    options.storageState = envToString(process.env.PLAYWRIGHT_MCP_STORAGE_STATE);
+    options.userAgent = envToString(process.env.PLAYWRIGHT_MCP_USER_AGENT);
+    options.userDataDir = envToString(process.env.PLAYWRIGHT_MCP_USER_DATA_DIR);
+    options.viewportSize = envToString(process.env.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
+    return configFromCLIOptions(options);
+}
 async function loadConfig(configFile) {
     if (!configFile)
         return {};
@@ -185,3 +218,28 @@ function mergeConfig(base, overrides) {
         },
     };
 }
+export function semicolonSeparatedList(value) {
+    if (!value)
+        return undefined;
+    return value.split(';').map(v => v.trim());
+}
+export function commaSeparatedList(value) {
+    if (!value)
+        return undefined;
+    return value.split(',').map(v => v.trim());
+}
+function envToNumber(value) {
+    if (!value)
+        return undefined;
+    return +value;
+}
+function envToBoolean(value) {
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
+function envToString(value) {
+    return value ? value.trim() : undefined;
+}

package/lib/connection.js

@@ -17,11 +17,10 @@ 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 } from './context.js';
-import { snapshotTools, visionTools } from './tools.js';
+import { allTools } from './tools.js';
 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 tools = allTools.filter(tool => tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability));
     const context = new Context(tools, config, browserContextFactory);
     const server = new McpServer({ name: 'Playwright', version: packageJSON.version }, {
         capabilities: {

package/lib/context.js

@@ -37,11 +37,9 @@ export class Context {
         testDebug('create context');
     }
     clientSupportsImages() {
-        if (this.config.imageResponses === 'allow')
-            return true;
         if (this.config.imageResponses === 'omit')
             return false;
-        return !this.clientVersion?.name.includes('cursor');
+        return true;
     }
     modalStates() {
         return this._modalStates;
@@ -77,7 +75,7 @@ export class Context {
         return this._currentTab;
     }
     async selectTab(index) {
-        this._currentTab = this._tabs[index - 1];
+        this._currentTab = this._tabs[index];
         await this._currentTab.page.bringToFront();
     }
     async ensureTab() {
@@ -95,12 +93,12 @@ export class Context {
             const title = await tab.title();
             const url = tab.page.url();
             const current = tab === this._currentTab ? ' (current)' : '';
-            lines.push(`- ${i + 1}:${current} [${title}] (${url})`);
+            lines.push(`- ${i}:${current} [${title}] (${url})`);
         }
         return lines.join('\n');
     }
     async closeTab(index) {
-        const tab = index === undefined ? this._currentTab : this._tabs[index - 1];
+        const tab = index === undefined ? this._currentTab : this._tabs[index];
         await tab?.page.close();
         return await this.listTabsMarkdown();
     }
@@ -108,7 +106,6 @@ export class Context {
         // Tab management is done outside of the action() call.
         const toolResult = await tool.handle(this, tool.schema.inputSchema.parse(params || {}));
         const { code, action, waitForNetwork, captureSnapshot, resultOverride } = toolResult;
-        const racingAction = action ? () => this._raceAgainstModalDialogs(action) : undefined;
         if (resultOverride)
             return resultOverride;
         if (!this._currentTab) {
@@ -121,25 +118,25 @@ export class Context {
         }
         const tab = this.currentTabOrDie();
         // TODO: race against modal dialogs to resolve clicks.
-        let actionResult;
-        try {
-            if (waitForNetwork)
-                actionResult = await waitForCompletion(this, tab, async () => racingAction?.()) ?? undefined;
-            else
-                actionResult = await racingAction?.() ?? undefined;
-        }
-        finally {
-            if (captureSnapshot && !this._javaScriptBlocked())
-                await tab.captureSnapshot();
-        }
+        const actionResult = await this._raceAgainstModalDialogs(async () => {
+            try {
+                if (waitForNetwork)
+                    return await waitForCompletion(this, tab, async () => action?.()) ?? undefined;
+                else
+                    return await action?.() ?? undefined;
+            }
+            finally {
+                if (captureSnapshot && !this._javaScriptBlocked())
+                    await tab.captureSnapshot();
+            }
+        });
         const result = [];
-        result.push(`- Ran Playwright code:
+        result.push(`### Ran Playwright code
 \`\`\`js
 ${code.join('\n')}
-\`\`\`
-`);
+\`\`\``);
         if (this.modalStates().length) {
-            result.push(...this.modalStatesMarkdown());
+            result.push('', ...this.modalStatesMarkdown());
             return {
                 content: [{
                         type: 'text',
@@ -147,6 +144,12 @@ ${code.join('\n')}
                     }],
             };
         }
+        const messages = tab.takeRecentConsoleMessages();
+        if (messages.length) {
+            result.push('', `### New console messages`);
+            for (const message of messages)
+                result.push(`- ${trim(message.toString(), 100)}`);
+        }
         if (this._downloads.length) {
             result.push('', '### Downloads');
             for (const entry of this._downloads) {
@@ -155,15 +158,17 @@ ${code.join('\n')}
                 else
                     result.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
             }
-            result.push('');
         }
-        if (this.tabs().length > 1)
-            result.push(await this.listTabsMarkdown(), '');
-        if (this.tabs().length > 1)
-            result.push('### Current tab');
-        result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.title()}`);
-        if (captureSnapshot && tab.hasSnapshot())
+        if (captureSnapshot && tab.hasSnapshot()) {
+            if (this.tabs().length > 1)
+                result.push('', await this.listTabsMarkdown());
+            if (this.tabs().length > 1)
+                result.push('', '### Current tab');
+            else
+                result.push('', '### Page state');
+            result.push(`- Page URL: ${tab.page.url()}`, `- Page Title: ${await tab.title()}`);
             result.push(tab.snapshotOrDie().text());
+        }
         const content = actionResult?.content ?? [];
         return {
             content: [
@@ -289,3 +294,8 @@ ${code.join('\n')}
         return result;
     }
 }
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + '...';
+}

package/lib/{resources/resource.js → log.js}

@@ -13,4 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export {};
+import debug from 'debug';
+const errorsDebug = debug('pw:mcp:errors');
+export function logUnhandledError(error) {
+    errorsDebug(error);
+}
+export const testDebug = debug('pw:mcp:test');

package/lib/pageSnapshot.js

@@ -31,7 +31,7 @@ export class PageSnapshot {
     async _build() {
         const snapshot = await callOnPageNoTrace(this._page, page => page._snapshotForAI());
         this._text = [
-            `- Page Snapshot`,
+            `- Page Snapshot:`,
             '```yaml',
             snapshot,
             '```',

package/lib/program.js

@@ -13,11 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { program } from 'commander';
+import { program, Option } from 'commander';
 // @ts-ignore
 import { startTraceViewerServer } from 'playwright-core/lib/server';
-import { startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveCLIConfig } from './config.js';
+import { startHttpServer, startHttpTransport, startStdioTransport } from './transport.js';
+import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
 import { Server } from './server.js';
 import { packageJSON } from './package.js';
 program
@@ -27,8 +27,7 @@ program
     .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('--block-service-workers', 'block service workers')
     .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
-    .option('--browser-agent <endpoint>', 'Use browser agent (experimental).')
-    .option('--caps <caps>', 'comma-separated list of capabilities to enable, possible values: tabs, pdf, history, wait, files, install. Default is all.')
+    .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)
     .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
     .option('--config <path>', 'path to the configuration file.')
     .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
@@ -37,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('--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('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".')
     .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.')
@@ -48,13 +47,19 @@ program
     .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)')
+    .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
     .action(async (options) => {
+    if (options.vision) {
+        // eslint-disable-next-line no-console
+        console.error('The --vision option is deprecated, use --caps=vision instead');
+        options.caps = 'vision';
+    }
     const config = await resolveCLIConfig(options);
+    const httpServer = config.server.port !== undefined ? await startHttpServer(config.server) : undefined;
     const server = new Server(config);
     server.setupExitWatchdog();
-    if (config.server.port !== undefined)
-        startHttpTransport(server);
+    if (httpServer)
+        startHttpTransport(httpServer, server);
     else
         await startStdioTransport(server);
     if (config.saveTrace) {
@@ -65,7 +70,4 @@ program
         console.error('\nTrace viewer listening on ' + url);
     }
 });
-function semicolonSeparatedList(value) {
-    return value.split(';').map(v => v.trim());
-}
 void program.parseAsync(process.argv);

package/lib/tab.js

@@ -15,10 +15,12 @@
  */
 import { PageSnapshot } from './pageSnapshot.js';
 import { callOnPageNoTrace } from './tools/utils.js';
+import { logUnhandledError } from './log.js';
 export class Tab {
     context;
     page;
     _consoleMessages = [];
+    _recentConsoleMessages = [];
     _requests = new Map();
     _snapshot;
     _onPageClose;
@@ -26,7 +28,8 @@ export class Tab {
         this.context = context;
         this.page = page;
         this._onPageClose = onPageClose;
-        page.on('console', event => this._consoleMessages.push(event));
+        page.on('console', event => this._handleConsoleMessage(messageToConsoleMessage(event)));
+        page.on('pageerror', error => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
         page.on('request', request => this._requests.set(request, null));
         page.on('response', response => this._requests.set(response.request(), response));
         page.on('close', () => this._onClose());
@@ -46,8 +49,13 @@ export class Tab {
     }
     _clearCollectedArtifacts() {
         this._consoleMessages.length = 0;
+        this._recentConsoleMessages.length = 0;
         this._requests.clear();
     }
+    _handleConsoleMessage(message) {
+        this._consoleMessages.push(message);
+        this._recentConsoleMessages.push(message);
+    }
     _onClose() {
         this._clearCollectedArtifacts();
         this._onPageClose(this);
@@ -56,11 +64,11 @@ export class Tab {
         return await callOnPageNoTrace(this.page, page => page.title());
     }
     async waitForLoadState(state, options) {
-        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(() => { }));
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(logUnhandledError));
     }
     async navigate(url) {
         this._clearCollectedArtifacts();
-        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(() => { }));
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(logUnhandledError));
         try {
             await this.page.goto(url, { waitUntil: 'domcontentloaded' });
         }
@@ -98,4 +106,30 @@ export class Tab {
     async captureSnapshot() {
         this._snapshot = await PageSnapshot.create(this.page);
     }
+    takeRecentConsoleMessages() {
+        const result = this._recentConsoleMessages.slice();
+        this._recentConsoleMessages.length = 0;
+        return result;
+    }
+}
+function messageToConsoleMessage(message) {
+    return {
+        type: message.type(),
+        text: message.text(),
+        toString: () => `[${message.type().toUpperCase()}] ${message.text()} @ ${message.location().url}:${message.location().lineNumber}`,
+    };
+}
+function pageErrorToConsoleMessage(errorOrValue) {
+    if (errorOrValue instanceof Error) {
+        return {
+            type: undefined,
+            text: errorOrValue.message,
+            toString: () => errorOrValue.stack || errorOrValue.message,
+        };
+    }
+    return {
+        type: undefined,
+        text: String(errorOrValue),
+        toString: () => String(errorOrValue),
+    };
 }

package/lib/tools/common.js

@@ -33,7 +33,7 @@ const close = defineTool({
         };
     },
 });
-const resize = captureSnapshot => defineTool({
+const resize = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_resize',
@@ -57,12 +57,12 @@ const resize = captureSnapshot => defineTool({
         return {
             code,
             action,
-            captureSnapshot,
+            captureSnapshot: true,
             waitForNetwork: true
         };
     },
 });
-export default (captureSnapshot) => [
+export default [
     close,
-    resize(captureSnapshot)
+    resize
 ];

package/lib/tools/console.js

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

package/lib/tools/dialogs.js

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { defineTool } from './tool.js';
-const handleDialog = captureSnapshot => defineTool({
+const handleDialog = defineTool({
     capability: 'core',
     schema: {
         name: 'browser_handle_dialog',
@@ -41,12 +41,12 @@ const handleDialog = captureSnapshot => defineTool({
         ];
         return {
             code,
-            captureSnapshot,
+            captureSnapshot: true,
             waitForNetwork: false,
         };
     },
     clearsModalState: 'dialog',
 });
-export default (captureSnapshot) => [
-    handleDialog(captureSnapshot),
+export default [
+    handleDialog,
 ];

package/lib/tools/evaluate.js

@@ -0,0 +1,62 @@
+/**
+ * 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 { z } from 'zod';
+import { defineTool } from './tool.js';
+import * as javascript from '../javascript.js';
+import { generateLocator } from './utils.js';
+const evaluateSchema = z.object({
+    function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
+    element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+    ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
+});
+const evaluate = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_evaluate',
+        title: 'Evaluate JavaScript',
+        description: 'Evaluate JavaScript expression on page or element',
+        inputSchema: evaluateSchema,
+        type: 'destructive',
+    },
+    handle: async (context, params) => {
+        const tab = context.currentTabOrDie();
+        const code = [];
+        let locator;
+        if (params.ref && params.element) {
+            const snapshot = tab.snapshotOrDie();
+            locator = snapshot.refLocator({ ref: params.ref, element: params.element });
+            code.push(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+        }
+        else {
+            code.push(`await page.evaluate(${javascript.quote(params.function)});`);
+        }
+        return {
+            code,
+            action: async () => {
+                const receiver = locator ?? tab.page;
+                const result = await receiver._evaluateFunction(params.function);
+                return {
+                    content: [{ type: 'text', text: '- Result: ' + (JSON.stringify(result, null, 2) || 'undefined') }],
+                };
+            },
+            captureSnapshot: false,
+            waitForNetwork: false,
+        };
+    },
+});
+export default [
+    evaluate,
+];