@playwright/mcp 0.0.34 → 0.0.35-alpha-2025-08-28

package/lib/mcp/mdb.js

@@ -0,0 +1,198 @@
+/**
+ * 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 debug from 'debug';
+import { z } from 'zod';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { defineToolSchema } from './tool.js';
+import * as mcpServer from './server.js';
+import * as mcpHttp from './http.js';
+import { wrapInProcess } from './server.js';
+import { ManualPromise } from './manualPromise.js';
+const mdbDebug = debug('pw:mcp:mdb');
+const errorsDebug = debug('pw:mcp:errors');
+export class MDBBackend {
+    _stack = [];
+    _interruptPromise;
+    _topLevelBackend;
+    _initialized = false;
+    constructor(topLevelBackend) {
+        this._topLevelBackend = topLevelBackend;
+    }
+    async initialize(server) {
+        if (this._initialized)
+            return;
+        this._initialized = true;
+        const transport = await wrapInProcess(this._topLevelBackend);
+        await this._pushClient(transport);
+    }
+    async listTools() {
+        const response = await this._client().listTools();
+        return response.tools;
+    }
+    async callTool(name, args) {
+        if (name === pushToolsSchema.name)
+            return await this._pushTools(pushToolsSchema.inputSchema.parse(args || {}));
+        const interruptPromise = new ManualPromise();
+        this._interruptPromise = interruptPromise;
+        let [entry] = this._stack;
+        // Pop the client while the tool is not found.
+        while (entry && !entry.toolNames.includes(name)) {
+            mdbDebug('popping client from stack for ', name);
+            this._stack.shift();
+            await entry.client.close();
+            entry = this._stack[0];
+        }
+        if (!entry)
+            throw new Error(`Tool ${name} not found in the tool stack`);
+        const resultPromise = new ManualPromise();
+        entry.resultPromise = resultPromise;
+        this._client().callTool({
+            name,
+            arguments: args,
+        }).then(result => {
+            resultPromise.resolve(result);
+        }).catch(e => {
+            mdbDebug('error in client call', e);
+            if (this._stack.length < 2)
+                throw e;
+            this._stack.shift();
+            const prevEntry = this._stack[0];
+            void prevEntry.resultPromise.then(result => resultPromise.resolve(result));
+        });
+        const result = await Promise.race([interruptPromise, resultPromise]);
+        if (interruptPromise.isDone())
+            mdbDebug('client call intercepted', result);
+        else
+            mdbDebug('client call result', result);
+        return result;
+    }
+    _client() {
+        const [entry] = this._stack;
+        if (!entry)
+            throw new Error('No debugging backend available');
+        return entry.client;
+    }
+    async _pushTools(params) {
+        mdbDebug('pushing tools to the stack', params.mcpUrl);
+        const transport = new StreamableHTTPClientTransport(new URL(params.mcpUrl));
+        await this._pushClient(transport, params.introMessage);
+        return { content: [{ type: 'text', text: 'Tools pushed' }] };
+    }
+    async _pushClient(transport, introMessage) {
+        mdbDebug('pushing client to the stack');
+        const client = new Client({ name: 'Internal client', version: '0.0.0' });
+        client.setRequestHandler(PingRequestSchema, () => ({}));
+        await client.connect(transport);
+        mdbDebug('connected to the new client');
+        const { tools } = await client.listTools();
+        this._stack.unshift({ client, toolNames: tools.map(tool => tool.name), resultPromise: undefined });
+        mdbDebug('new tools added to the stack:', tools.map(tool => tool.name));
+        mdbDebug('interrupting current call:', !!this._interruptPromise);
+        this._interruptPromise?.resolve({
+            content: [{
+                    type: 'text',
+                    text: introMessage || '',
+                }],
+        });
+        this._interruptPromise = undefined;
+        return { content: [{ type: 'text', text: 'Tools pushed' }] };
+    }
+}
+const pushToolsSchema = defineToolSchema({
+    name: 'mdb_push_tools',
+    title: 'Push MCP tools to the tools stack',
+    description: 'Push MCP tools to the tools stack',
+    inputSchema: z.object({
+        mcpUrl: z.string(),
+        introMessage: z.string().optional(),
+    }),
+    type: 'readOnly',
+});
+export async function runMainBackend(backendFactory, options) {
+    const mdbBackend = new MDBBackend(backendFactory.create());
+    // Start HTTP unconditionally.
+    const factory = {
+        ...backendFactory,
+        create: () => mdbBackend
+    };
+    const url = await startAsHttp(factory, { port: options?.port || 0 });
+    process.env.PLAYWRIGHT_DEBUGGER_MCP = url;
+    if (options?.port !== undefined)
+        return url;
+    // Start stdio conditionally.
+    await mcpServer.connect(factory, new StdioServerTransport(), false);
+}
+export async function runOnPauseBackendLoop(mdbUrl, backend, introMessage) {
+    const wrappedBackend = new OnceTimeServerBackendWrapper(backend);
+    const factory = {
+        name: 'on-pause-backend',
+        nameInConfig: 'on-pause-backend',
+        version: '0.0.0',
+        create: () => wrappedBackend,
+    };
+    const httpServer = await mcpHttp.startHttpServer({ port: 0 });
+    await mcpHttp.installHttpTransport(httpServer, factory);
+    const url = mcpHttp.httpAddressToString(httpServer.address());
+    const client = new Client({ name: 'Internal client', version: '0.0.0' });
+    client.setRequestHandler(PingRequestSchema, () => ({}));
+    const transport = new StreamableHTTPClientTransport(new URL(mdbUrl));
+    await client.connect(transport);
+    const pushToolsResult = await client.callTool({
+        name: pushToolsSchema.name,
+        arguments: {
+            mcpUrl: url,
+            introMessage,
+        },
+    });
+    if (pushToolsResult.isError)
+        errorsDebug('Failed to push tools', pushToolsResult.content);
+    await transport.terminateSession();
+    await client.close();
+    await wrappedBackend.waitForClosed();
+    httpServer.close();
+}
+async function startAsHttp(backendFactory, options) {
+    const httpServer = await mcpHttp.startHttpServer(options);
+    await mcpHttp.installHttpTransport(httpServer, backendFactory);
+    return mcpHttp.httpAddressToString(httpServer.address());
+}
+class OnceTimeServerBackendWrapper {
+    _backend;
+    _selfDestructPromise = new ManualPromise();
+    constructor(backend) {
+        this._backend = backend;
+        this._backend.requestSelfDestruct = () => this._selfDestructPromise.resolve();
+    }
+    async initialize(server, clientVersion, roots) {
+        await this._backend.initialize?.(server, clientVersion, roots);
+    }
+    async listTools() {
+        return this._backend.listTools();
+    }
+    async callTool(name, args) {
+        return this._backend.callTool(name, args);
+    }
+    serverClosed(server) {
+        this._backend.serverClosed?.(server);
+        this._selfDestructPromise.resolve();
+    }
+    async waitForClosed() {
+        await this._selfDestructPromise;
+    }
+}

package/lib/mcp/proxyBackend.js

@@ -13,15 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import debug from 'debug';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { ListRootsRequestSchema, PingRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { logUnhandledError } from '../utils/log.js';
-import { packageJSON } from '../utils/package.js';
+const errorsDebug = debug('pw:mcp:errors');
 export class ProxyBackend {
-    name = 'Playwright MCP Client Switcher';
-    version = packageJSON.version;
     _mcpProviders;
     _currentClient;
     _contextSwitchTool;
@@ -30,7 +28,7 @@ export class ProxyBackend {
         this._mcpProviders = mcpProviders;
         this._contextSwitchTool = this._defineContextSwitchTool();
     }
-    async initialize(clientVersion, roots) {
+    async initialize(server, clientVersion, roots) {
         this._roots = roots;
         await this._setCurrentClient(this._mcpProviders[0]);
     }
@@ -52,7 +50,7 @@ export class ProxyBackend {
         });
     }
     serverClosed() {
-        void this._currentClient?.close().catch(logUnhandledError);
+        void this._currentClient?.close().catch(errorsDebug);
     }
     async _callContextSwitchTool(params) {
         try {
@@ -91,7 +89,7 @@ export class ProxyBackend {
     async _setCurrentClient(factory) {
         await this._currentClient?.close();
         this._currentClient = undefined;
-        const client = new Client({ name: 'Playwright MCP Proxy', version: packageJSON.version });
+        const client = new Client({ name: 'Playwright MCP Proxy', version: '0.0.0' });
         client.registerCapabilities({
             roots: {
                 listRoots: true,

package/lib/mcp/server.js

@@ -16,17 +16,23 @@
 import debug from 'debug';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { ManualPromise } from '../utils/manualPromise.js';
-import { logUnhandledError } from '../utils/log.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { httpAddressToString, installHttpTransport, startHttpServer } from './http.js';
+import { InProcessTransport } from './inProcessTransport.js';
 const serverDebug = debug('pw:mcp:server');
-export async function connect(serverBackendFactory, transport, runHeartbeat) {
-    const backend = serverBackendFactory();
-    const server = createServer(backend, runHeartbeat);
+const errorsDebug = debug('pw:mcp:errors');
+export async function connect(factory, transport, runHeartbeat) {
+    const server = createServer(factory.name, factory.version, factory.create(), runHeartbeat);
     await server.connect(transport);
 }
-export function createServer(backend, runHeartbeat) {
-    const initializedPromise = new ManualPromise();
-    const server = new Server({ name: backend.name, version: backend.version }, {
+export async function wrapInProcess(backend) {
+    const server = createServer('Internal', '0.0.0', backend, false);
+    return new InProcessTransport(server);
+}
+export function createServer(name, version, backend, runHeartbeat) {
+    let initializedPromiseResolve = () => { };
+    const initializedPromise = new Promise(resolve => initializedPromiseResolve = resolve);
+    const server = new Server({ name, version }, {
         capabilities: {
             tools: {},
         }
@@ -64,14 +70,14 @@ export function createServer(backend, runHeartbeat) {
                 clientRoots = roots;
             }
             const clientVersion = server.getClientVersion() ?? { name: 'unknown', version: 'unknown' };
-            await backend.initialize?.(clientVersion, clientRoots);
-            initializedPromise.resolve();
+            await backend.initialize?.(server, clientVersion, clientRoots);
+            initializedPromiseResolve();
         }
         catch (e) {
-            logUnhandledError(e);
+            errorsDebug(e);
         }
     });
-    addServerListener(server, 'close', () => backend.serverClosed?.());
+    addServerListener(server, 'close', () => backend.serverClosed?.(server));
     return server;
 }
 const startHeartbeat = (server) => {
@@ -94,3 +100,24 @@ function addServerListener(server, event, listener) {
         listener();
     };
 }
+export async function start(serverBackendFactory, options) {
+    if (options.port === undefined) {
+        await connect(serverBackendFactory, new StdioServerTransport(), false);
+        return;
+    }
+    const httpServer = await startHttpServer(options);
+    await installHttpTransport(httpServer, serverBackendFactory);
+    const url = httpAddressToString(httpServer.address());
+    const mcpConfig = { mcpServers: {} };
+    mcpConfig.mcpServers[serverBackendFactory.nameInConfig] = {
+        url: `${url}/mcp`
+    };
+    const message = [
+        `Listening on ${url}`,
+        'Put this in your client config:',
+        JSON.stringify(mcpConfig, undefined, 2),
+        'For legacy SSE transport support, you can use the /sse endpoint instead.',
+    ].join('\n');
+    // eslint-disable-next-line no-console
+    console.error(message);
+}

package/lib/mcp/tool.js

@@ -27,3 +27,6 @@ export function toMcpTool(tool) {
         },
     };
 }
+export function defineToolSchema(tool) {
+    return tool;
+}

package/lib/program.js

@@ -15,7 +15,6 @@
  */
 import { program, Option } from 'commander';
 import * as mcpServer from './mcp/server.js';
-import * as mcpTransport from './mcp/transport.js';
 import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
 import { packageJSON } from './utils/package.js';
 import { Context } from './context.js';
@@ -24,7 +23,7 @@ import { runLoopTools } from './loopTools/main.js';
 import { ProxyBackend } from './mcp/proxyBackend.js';
 import { BrowserServerBackend } from './browserServerBackend.js';
 import { ExtensionContextFactory } from './extension/extensionContextFactory.js';
-import { InProcessTransport } from './mcp/inProcessTransport.js';
+import { runVSCodeTools } from './vscode/host.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -55,6 +54,7 @@ program
     .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"')
     .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
+    .addOption(new Option('--vscode', 'VS Code tools.').hideHelp())
     .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
     .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
     .action(async (options) => {
@@ -65,21 +65,55 @@ program
         options.caps = 'vision';
     }
     const config = await resolveCLIConfig(options);
+    const browserContextFactory = contextFactory(config);
+    const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir, config.browser.launchOptions.executablePath);
     if (options.extension) {
-        const contextFactory = createExtensionContextFactory(config);
-        const serverBackendFactory = () => new BrowserServerBackend(config, contextFactory);
-        await mcpTransport.start(serverBackendFactory, config.server);
+        const serverBackendFactory = {
+            name: 'Playwright w/ extension',
+            nameInConfig: 'playwright-extension',
+            version: packageJSON.version,
+            create: () => new BrowserServerBackend(config, extensionContextFactory)
+        };
+        await mcpServer.start(serverBackendFactory, config.server);
+        return;
+    }
+    if (options.vscode) {
+        await runVSCodeTools(config);
         return;
     }
     if (options.loopTools) {
         await runLoopTools(config);
         return;
     }
-    const browserContextFactory = contextFactory(config);
-    const providers = [mcpProviderForBrowserContextFactory(config, browserContextFactory)];
-    if (options.connectTool)
-        providers.push(mcpProviderForBrowserContextFactory(config, createExtensionContextFactory(config)));
-    await mcpTransport.start(() => new ProxyBackend(providers), config.server);
+    if (options.connectTool) {
+        const providers = [
+            {
+                name: 'default',
+                description: 'Starts standalone browser',
+                connect: () => mcpServer.wrapInProcess(new BrowserServerBackend(config, browserContextFactory)),
+            },
+            {
+                name: 'extension',
+                description: 'Connect to a browser using the Playwright MCP extension',
+                connect: () => mcpServer.wrapInProcess(new BrowserServerBackend(config, extensionContextFactory)),
+            },
+        ];
+        const factory = {
+            name: 'Playwright w/ switch',
+            nameInConfig: 'playwright-switch',
+            version: packageJSON.version,
+            create: () => new ProxyBackend(providers),
+        };
+        await mcpServer.start(factory, config.server);
+        return;
+    }
+    const factory = {
+        name: 'Playwright',
+        nameInConfig: 'playwright',
+        version: packageJSON.version,
+        create: () => new BrowserServerBackend(config, browserContextFactory)
+    };
+    await mcpServer.start(factory, config.server);
 });
 function setupExitWatchdog() {
     let isExiting = false;
@@ -95,17 +129,4 @@ function setupExitWatchdog() {
     process.on('SIGINT', handleExit);
     process.on('SIGTERM', handleExit);
 }
-function createExtensionContextFactory(config) {
-    return new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
-}
-function mcpProviderForBrowserContextFactory(config, browserContextFactory) {
-    return {
-        name: browserContextFactory.name,
-        description: browserContextFactory.description,
-        connect: async () => {
-            const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
-            return new InProcessTransport(server);
-        },
-    };
-}
 void program.parseAsync(process.argv);

package/lib/tab.js

@@ -16,7 +16,7 @@
 import { EventEmitter } from 'events';
 import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
 import { logUnhandledError } from './utils/log.js';
-import { ManualPromise } from './utils/manualPromise.js';
+import { ManualPromise } from './mcp/manualPromise.js';
 export const TabEvents = {
     modalState: 'modalState'
 };

package/lib/tools/form.js

@@ -0,0 +1,57 @@
+/**
+ * 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 { defineTabTool } from './tool.js';
+import { generateLocator } from './utils.js';
+import * as javascript from '../utils/codegen.js';
+const fillForm = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_fill_form',
+        title: 'Fill form',
+        description: 'Fill multiple form fields',
+        inputSchema: z.object({
+            fields: z.array(z.object({
+                name: z.string().describe('Human-readable field name'),
+                type: z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider']).describe('Type of the field'),
+                ref: z.string().describe('Exact target field reference from the page snapshot'),
+                value: z.string().describe('Value to fill in the field. If the field is a checkbox, the value should be `true` or `false`. If the field is a combobox, the value should be the text of the option.'),
+            })).describe('Fields to fill in'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        for (const field of params.fields) {
+            const locator = await tab.refLocator({ element: field.name, ref: field.ref });
+            const locatorSource = `await page.${await generateLocator(locator)}`;
+            if (field.type === 'textbox' || field.type === 'slider') {
+                await locator.fill(field.value);
+                response.addCode(`${locatorSource}.fill(${javascript.quote(field.value)});`);
+            }
+            else if (field.type === 'checkbox' || field.type === 'radio') {
+                await locator.setChecked(field.value === 'true');
+                response.addCode(`${locatorSource}.setChecked(${javascript.quote(field.value)});`);
+            }
+            else if (field.type === 'combobox') {
+                await locator.selectOption({ label: field.value });
+                response.addCode(`${locatorSource}.selectOption(${javascript.quote(field.value)});`);
+            }
+        }
+    },
+});
+export default [
+    fillForm,
+];

package/lib/tools/navigate.js

@@ -48,23 +48,7 @@ const goBack = defineTabTool({
         response.addCode(`await page.goBack();`);
     },
 });
-const goForward = defineTabTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_navigate_forward',
-        title: 'Go forward',
-        description: 'Go forward to the next page',
-        inputSchema: z.object({}),
-        type: 'readOnly',
-    },
-    handle: async (tab, params, response) => {
-        await tab.page.goForward();
-        response.setIncludeSnapshot();
-        response.addCode(`await page.goForward();`);
-    },
-});
 export default [
     navigate,
     goBack,
-    goForward,
 ];

package/lib/tools/tabs.js

@@ -15,73 +15,45 @@
  */
 import { z } from 'zod';
 import { defineTool } from './tool.js';
-const listTabs = defineTool({
+const browserTabs = defineTool({
     capability: 'core-tabs',
     schema: {
-        name: 'browser_tab_list',
-        title: 'List tabs',
-        description: 'List browser tabs',
-        inputSchema: z.object({}),
-        type: 'readOnly',
-    },
-    handle: async (context, params, response) => {
-        await context.ensureTab();
-        response.setIncludeTabs();
-    },
-});
-const selectTab = defineTool({
-    capability: 'core-tabs',
-    schema: {
-        name: 'browser_tab_select',
-        title: 'Select a tab',
-        description: 'Select a tab by index',
-        inputSchema: z.object({
-            index: z.number().describe('The index of the tab to select'),
-        }),
-        type: 'readOnly',
-    },
-    handle: async (context, params, response) => {
-        await context.selectTab(params.index);
-        response.setIncludeSnapshot();
-    },
-});
-const newTab = defineTool({
-    capability: 'core-tabs',
-    schema: {
-        name: 'browser_tab_new',
-        title: 'Open a new tab',
-        description: 'Open a new tab',
-        inputSchema: z.object({
-            url: z.string().optional().describe('The URL to navigate to in the new tab. If not provided, the new tab will be blank.'),
-        }),
-        type: 'readOnly',
-    },
-    handle: async (context, params, response) => {
-        const tab = await context.newTab();
-        if (params.url)
-            await tab.navigate(params.url);
-        response.setIncludeSnapshot();
-    },
-});
-const closeTab = defineTool({
-    capability: 'core-tabs',
-    schema: {
-        name: 'browser_tab_close',
-        title: 'Close a tab',
-        description: 'Close a tab',
+        name: 'browser_tabs',
+        title: 'Manage tabs',
+        description: 'List, create, close, or select a browser tab.',
         inputSchema: z.object({
-            index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
+            action: z.enum(['list', 'new', 'close', 'select']).describe('Operation to perform'),
+            index: z.number().optional().describe('Tab index, used for close/select. If omitted for close, current tab is closed.'),
         }),
         type: 'destructive',
     },
     handle: async (context, params, response) => {
-        await context.closeTab(params.index);
-        response.setIncludeSnapshot();
+        switch (params.action) {
+            case 'list': {
+                await context.ensureTab();
+                response.setIncludeTabs();
+                return;
+            }
+            case 'new': {
+                await context.newTab();
+                response.setIncludeTabs();
+                return;
+            }
+            case 'close': {
+                await context.closeTab(params.index);
+                response.setIncludeSnapshot();
+                return;
+            }
+            case 'select': {
+                if (!params.index)
+                    throw new Error('Tab index is required');
+                await context.selectTab(params.index);
+                response.setIncludeSnapshot();
+                return;
+            }
+        }
     },
 });
 export default [
-    listTabs,
-    newTab,
-    selectTab,
-    closeTab,
+    browserTabs,
 ];