@playwright/mcp 0.0.32 → 0.0.33

package/lib/extension/extensionContextFactory.js

@@ -0,0 +1,56 @@
+/**
+ * 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 * as playwright from 'playwright';
+import { startHttpServer } from '../httpServer.js';
+import { CDPRelayServer } from './cdpRelay.js';
+const debugLogger = debug('pw:mcp:relay');
+export class ExtensionContextFactory {
+    name = 'extension';
+    description = 'Connect to a browser using the Playwright MCP extension';
+    _browserChannel;
+    _userDataDir;
+    constructor(browserChannel, userDataDir) {
+        this._browserChannel = browserChannel;
+        this._userDataDir = userDataDir;
+    }
+    async createContext(clientInfo, abortSignal) {
+        const browser = await this._obtainBrowser(clientInfo, abortSignal);
+        return {
+            browserContext: browser.contexts()[0],
+            close: async () => {
+                debugLogger('close() called for browser context');
+                await browser.close();
+            }
+        };
+    }
+    async _obtainBrowser(clientInfo, abortSignal) {
+        const relay = await this._startRelay(abortSignal);
+        await relay.ensureExtensionConnectionForMCPContext(clientInfo, abortSignal);
+        return await playwright.chromium.connectOverCDP(relay.cdpEndpoint());
+    }
+    async _startRelay(abortSignal) {
+        const httpServer = await startHttpServer({});
+        if (abortSignal.aborted) {
+            httpServer.close();
+            throw new Error(abortSignal.reason);
+        }
+        const cdpRelayServer = new CDPRelayServer(httpServer, this._browserChannel, this._userDataDir);
+        abortSignal.addEventListener('abort', () => cdpRelayServer.stop());
+        debugLogger(`CDP relay server started, extension endpoint: ${cdpRelayServer.extensionEndpoint()}.`);
+        return cdpRelayServer;
+    }
+}

package/lib/extension/main.js

@@ -13,21 +13,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { startCDPRelayServer } from './cdpRelay.js';
+import { ExtensionContextFactory } from './extensionContextFactory.js';
 import { BrowserServerBackend } from '../browserServerBackend.js';
 import * as mcpTransport from '../mcp/transport.js';
-export async function runWithExtension(config, abortController) {
-    const contextFactory = await startCDPRelayServer(config.browser.launchOptions.channel || 'chrome', abortController);
-    let backend;
-    const serverBackendFactory = () => {
-        if (backend)
-            throw new Error('Another MCP client is still connected. Only one connection at a time is allowed.');
-        backend = new BrowserServerBackend(config, contextFactory);
-        backend.onclose = () => {
-            contextFactory.clientDisconnected();
-            backend = undefined;
-        };
-        return backend;
-    };
+export async function runWithExtension(config) {
+    const contextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
+    const serverBackendFactory = () => new BrowserServerBackend(config, [contextFactory]);
     await mcpTransport.start(serverBackendFactory, config.server);
 }
+export function createExtensionContextFactory(config) {
+    return new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir);
+}

package/lib/index.js

@@ -19,10 +19,12 @@ import { contextFactory } from './browserContextFactory.js';
 import * as mcpServer from './mcp/server.js';
 export async function createConnection(userConfig = {}, contextGetter) {
     const config = await resolveConfig(userConfig);
-    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config.browser);
-    return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config);
+    return mcpServer.createServer(new BrowserServerBackend(config, [factory]), false);
 }
 class SimpleBrowserContextFactory {
+    name = 'custom';
+    description = 'Connect to a browser using a custom context getter';
     _contextGetter;
     constructor(contextGetter) {
         this._contextGetter = contextGetter;

package/lib/loopTools/context.js

@@ -38,8 +38,8 @@ export class Context {
     }
     static async create(config) {
         const client = new Client({ name: 'Playwright Proxy', version: '1.0.0' });
-        const browserContextFactory = contextFactory(config.browser);
-        const server = mcpServer.createServer(new BrowserServerBackend(config, browserContextFactory), false);
+        const browserContextFactory = contextFactory(config);
+        const server = mcpServer.createServer(new BrowserServerBackend(config, [browserContextFactory]), false);
         await client.connect(new InProcessTransport(server));
         await client.ping();
         return new Context(config, client);

package/lib/mcp/server.js

@@ -16,13 +16,15 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { zodToJsonSchema } from 'zod-to-json-schema';
+import { ManualPromise } from '../manualPromise.js';
+import { logUnhandledError } from '../log.js';
 export async function connect(serverBackendFactory, transport, runHeartbeat) {
     const backend = serverBackendFactory();
-    await backend.initialize?.();
     const server = createServer(backend, runHeartbeat);
     await server.connect(transport);
 }
 export function createServer(backend, runHeartbeat) {
+    const initializedPromise = new ManualPromise();
     const server = new Server({ name: backend.name, version: backend.version }, {
         capabilities: {
             tools: {},
@@ -44,17 +46,18 @@ export function createServer(backend, runHeartbeat) {
     });
     let heartbeatRunning = false;
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        await initializedPromise;
         if (runHeartbeat && !heartbeatRunning) {
             heartbeatRunning = true;
             startHeartbeat(server);
         }
         const errorResult = (...messages) => ({
-            content: [{ type: 'text', text: messages.join('\n') }],
+            content: [{ type: 'text', text: '### Result\n' + messages.join('\n') }],
             isError: true,
         });
         const tool = tools.find(tool => tool.name === request.params.name);
         if (!tool)
-            return errorResult(`Tool "${request.params.name}" not found`);
+            return errorResult(`Error: Tool "${request.params.name}" not found`);
         try {
             return await backend.callTool(tool, tool.inputSchema.parse(request.params.arguments || {}));
         }
@@ -62,7 +65,9 @@ export function createServer(backend, runHeartbeat) {
             return errorResult(String(error));
         }
     });
-    addServerListener(server, 'initialized', () => backend.serverInitialized?.(server.getClientVersion()));
+    addServerListener(server, 'initialized', () => {
+        backend.initialize?.(server).then(() => initializedPromise.resolve()).catch(logUnhandledError);
+    });
     addServerListener(server, 'close', () => backend.serverClosed?.());
     return server;
 }

package/lib/program.js

@@ -19,7 +19,7 @@ import { startTraceViewerServer } from 'playwright-core/lib/server';
 import * as mcpTransport from './mcp/transport.js';
 import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
 import { packageJSON } from './package.js';
-import { runWithExtension } from './extension/main.js';
+import { createExtensionContextFactory, runWithExtension } from './extension/main.js';
 import { BrowserServerBackend } from './browserServerBackend.js';
 import { Context } from './context.js';
 import { contextFactory } from './browserContextFactory.js';
@@ -53,10 +53,11 @@ 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('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp())
+    .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
     .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
     .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
     .action(async (options) => {
-    const abortController = setupExitWatchdog();
+    setupExitWatchdog();
     if (options.vision) {
         // eslint-disable-next-line no-console
         console.error('The --vision option is deprecated, use --caps=vision instead');
@@ -64,15 +65,18 @@ program
     }
     const config = await resolveCLIConfig(options);
     if (options.extension) {
-        await runWithExtension(config, abortController);
+        await runWithExtension(config);
         return;
     }
     if (options.loopTools) {
         await runLoopTools(config);
         return;
     }
-    const browserContextFactory = contextFactory(config.browser);
-    const serverBackendFactory = () => new BrowserServerBackend(config, browserContextFactory);
+    const browserContextFactory = contextFactory(config);
+    const factories = [browserContextFactory];
+    if (options.connectTool)
+        factories.push(createExtensionContextFactory(config));
+    const serverBackendFactory = () => new BrowserServerBackend(config, factories);
     await mcpTransport.start(serverBackendFactory, config.server);
     if (config.saveTrace) {
         const server = await startTraceViewerServer();
@@ -83,20 +87,17 @@ program
     }
 });
 function setupExitWatchdog() {
-    const abortController = new AbortController();
     let isExiting = false;
     const handleExit = async () => {
         if (isExiting)
             return;
         isExiting = true;
         setTimeout(() => process.exit(0), 15000);
-        abortController.abort('Process exiting');
         await Context.disposeAll();
         process.exit(0);
     };
     process.stdin.on('close', handleExit);
     process.on('SIGINT', handleExit);
     process.on('SIGTERM', handleExit);
-    return abortController;
 }
 void program.parseAsync(process.argv);

package/lib/response.js

@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { renderModalStates } from './tab.js';
 export class Response {
     _result = [];
     _code = [];
@@ -20,9 +21,10 @@ export class Response {
     _context;
     _includeSnapshot = false;
     _includeTabs = false;
-    _snapshot;
+    _tabSnapshot;
     toolName;
     toolArgs;
+    _isError;
     constructor(context, toolName, toolArgs) {
         this._context = context;
         this.toolName = toolName;
@@ -31,6 +33,13 @@ export class Response {
     addResult(result) {
         this._result.push(result);
     }
+    addError(error) {
+        this._result.push(error);
+        this._isError = true;
+    }
+    isError() {
+        return this._isError;
+    }
     result() {
         return this._result.join('\n');
     }
@@ -52,16 +61,18 @@ export class Response {
     setIncludeTabs() {
         this._includeTabs = true;
     }
-    async snapshot() {
-        if (this._snapshot !== undefined)
-            return this._snapshot;
+    async finish() {
+        // All the async snapshotting post-action is happening here.
+        // Everything below should race against modal states.
         if (this._includeSnapshot && this._context.currentTab())
-            this._snapshot = await this._context.currentTabOrDie().captureSnapshot();
-        else
-            this._snapshot = '';
-        return this._snapshot;
+            this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+        for (const tab of this._context.tabs())
+            await tab.updateTitle();
     }
-    async serialize() {
+    tabSnapshot() {
+        return this._tabSnapshot;
+    }
+    serialize() {
         const response = [];
         // Start with command result.
         if (this._result.length) {
@@ -79,11 +90,16 @@ ${this._code.join('\n')}
         }
         // List browser tabs.
         if (this._includeSnapshot || this._includeTabs)
-            response.push(...(await this._context.listTabsMarkdown(this._includeTabs)));
+            response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
         // Add snapshot if provided.
-        const snapshot = await this.snapshot();
-        if (snapshot)
-            response.push(snapshot, '');
+        if (this._tabSnapshot?.modalStates.length) {
+            response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
+            response.push('');
+        }
+        else if (this._tabSnapshot) {
+            response.push(renderTabSnapshot(this._tabSnapshot));
+            response.push('');
+        }
         // Main response part
         const content = [
             { type: 'text', text: response.join('\n') },
@@ -93,6 +109,57 @@ ${this._code.join('\n')}
             for (const image of this._images)
                 content.push({ type: 'image', data: image.data.toString('base64'), mimeType: image.contentType });
         }
-        return { content };
+        return { content, isError: this._isError };
+    }
+}
+function renderTabSnapshot(tabSnapshot) {
+    const lines = [];
+    if (tabSnapshot.consoleMessages.length) {
+        lines.push(`### New console messages`);
+        for (const message of tabSnapshot.consoleMessages)
+            lines.push(`- ${trim(message.toString(), 100)}`);
+        lines.push('');
+    }
+    if (tabSnapshot.downloads.length) {
+        lines.push(`### Downloads`);
+        for (const entry of tabSnapshot.downloads) {
+            if (entry.finished)
+                lines.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+            else
+                lines.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+        }
+        lines.push('');
+    }
+    lines.push(`### Page state`);
+    lines.push(`- Page URL: ${tabSnapshot.url}`);
+    lines.push(`- Page Title: ${tabSnapshot.title}`);
+    lines.push(`- Page Snapshot:`);
+    lines.push('```yaml');
+    lines.push(tabSnapshot.ariaSnapshot);
+    lines.push('```');
+    return lines.join('\n');
+}
+function renderTabsMarkdown(tabs, force = false) {
+    if (tabs.length === 1 && !force)
+        return [];
+    if (!tabs.length) {
+        return [
+            '### Open tabs',
+            'No open tabs. Use the "browser_navigate" tool to navigate to a page first.',
+            '',
+        ];
     }
+    const lines = ['### Open tabs'];
+    for (let i = 0; i < tabs.length; i++) {
+        const tab = tabs[i];
+        const current = tab.isCurrentTab() ? ' (current)' : '';
+        lines.push(`- ${i}:${current} [${tab.lastTitle()}] (${tab.page.url()})`);
+    }
+    lines.push('');
+    return lines;
+}
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + '...';
 }

package/lib/sessionLog.js

@@ -15,56 +15,107 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { logUnhandledError } from './log.js';
 import { outputFile } from './config.js';
-let sessionOrdinal = 0;
 export class SessionLog {
     _folder;
     _file;
     _ordinal = 0;
+    _pendingEntries = [];
+    _sessionFileQueue = Promise.resolve();
+    _flushEntriesTimeout;
     constructor(sessionFolder) {
         this._folder = sessionFolder;
         this._file = path.join(this._folder, 'session.md');
     }
-    static async create(config) {
-        const sessionFolder = await outputFile(config, `session-${(++sessionOrdinal).toString().padStart(3, '0')}`);
+    static async create(config, rootPath) {
+        const sessionFolder = await outputFile(config, rootPath, `session-${Date.now()}`);
         await fs.promises.mkdir(sessionFolder, { recursive: true });
         // eslint-disable-next-line no-console
         console.error(`Session: ${sessionFolder}`);
         return new SessionLog(sessionFolder);
     }
-    async log(response) {
-        const prefix = `${(++this._ordinal).toString().padStart(3, '0')}`;
-        const lines = [
-            `### Tool: ${response.toolName}`,
-            ``,
-            `- Args`,
-            '```json',
-            JSON.stringify(response.toolArgs, null, 2),
-            '```',
-        ];
-        if (response.result()) {
-            lines.push(`- Result`, '```', response.result(), '```');
-        }
-        if (response.code()) {
-            lines.push(`- Code`, '```js', response.code(), '```');
+    logResponse(response) {
+        const entry = {
+            timestamp: performance.now(),
+            toolCall: {
+                toolName: response.toolName,
+                toolArgs: response.toolArgs,
+                result: response.result(),
+                isError: response.isError(),
+            },
+            code: response.code(),
+            tabSnapshot: response.tabSnapshot(),
+        };
+        this._appendEntry(entry);
+    }
+    logUserAction(action, tab, code, isUpdate) {
+        code = code.trim();
+        if (isUpdate) {
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry.userAction?.name === action.name) {
+                lastEntry.userAction = action;
+                lastEntry.code = code;
+                return;
+            }
         }
-        const snapshot = await response.snapshot();
-        if (snapshot) {
-            const fileName = `${prefix}.snapshot.yml`;
-            await fs.promises.writeFile(path.join(this._folder, fileName), snapshot);
-            lines.push(`- Snapshot: ${fileName}`);
+        if (action.name === 'navigate') {
+            // Already logged at this location.
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry?.tabSnapshot?.url === action.url)
+                return;
         }
-        for (const image of response.images()) {
-            const fileName = `${prefix}.screenshot.${extension(image.contentType)}`;
-            await fs.promises.writeFile(path.join(this._folder, fileName), image.data);
-            lines.push(`- Screenshot: ${fileName}`);
+        const entry = {
+            timestamp: performance.now(),
+            userAction: action,
+            code,
+            tabSnapshot: {
+                url: tab.page.url(),
+                title: '',
+                ariaSnapshot: action.ariaSnapshot || '',
+                modalStates: [],
+                consoleMessages: [],
+                downloads: [],
+            },
+        };
+        this._appendEntry(entry);
+    }
+    _appendEntry(entry) {
+        this._pendingEntries.push(entry);
+        if (this._flushEntriesTimeout)
+            clearTimeout(this._flushEntriesTimeout);
+        this._flushEntriesTimeout = setTimeout(() => this._flushEntries(), 1000);
+    }
+    async _flushEntries() {
+        clearTimeout(this._flushEntriesTimeout);
+        const entries = this._pendingEntries;
+        this._pendingEntries = [];
+        const lines = [''];
+        for (const entry of entries) {
+            const ordinal = (++this._ordinal).toString().padStart(3, '0');
+            if (entry.toolCall) {
+                lines.push(`### Tool call: ${entry.toolCall.toolName}`, `- Args`, '```json', JSON.stringify(entry.toolCall.toolArgs, null, 2), '```');
+                if (entry.toolCall.result) {
+                    lines.push(entry.toolCall.isError ? `- Error` : `- Result`, '```', entry.toolCall.result, '```');
+                }
+            }
+            if (entry.userAction) {
+                const actionData = { ...entry.userAction };
+                delete actionData.ariaSnapshot;
+                delete actionData.selector;
+                delete actionData.signals;
+                lines.push(`### User action: ${entry.userAction.name}`, `- Args`, '```json', JSON.stringify(actionData, null, 2), '```');
+            }
+            if (entry.code) {
+                lines.push(`- Code`, '```js', entry.code, '```');
+            }
+            if (entry.tabSnapshot) {
+                const fileName = `${ordinal}.snapshot.yml`;
+                fs.promises.writeFile(path.join(this._folder, fileName), entry.tabSnapshot.ariaSnapshot).catch(logUnhandledError);
+                lines.push(`- Snapshot: ${fileName}`);
+            }
+            lines.push('', '');
         }
-        lines.push('', '');
-        await fs.promises.appendFile(this._file, lines.join('\n'));
+        this._sessionFileQueue = this._sessionFileQueue.then(() => fs.promises.appendFile(this._file, lines.join('\n')));
     }
 }
-function extension(contentType) {
-    if (contentType === 'image/jpeg')
-        return 'jpg';
-    return 'png';
-}