@playwright/mcp 0.0.30 → 0.0.32

package/lib/mcp/inProcessTransport.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+export class InProcessTransport {
+    _server;
+    _serverTransport;
+    _connected = false;
+    constructor(server) {
+        this._server = server;
+        this._serverTransport = new InProcessServerTransport(this);
+    }
+    async start() {
+        if (this._connected)
+            throw new Error('InprocessTransport already started!');
+        await this._server.connect(this._serverTransport);
+        this._connected = true;
+    }
+    async send(message, options) {
+        if (!this._connected)
+            throw new Error('Transport not connected');
+        this._serverTransport._receiveFromClient(message);
+    }
+    async close() {
+        if (this._connected) {
+            this._connected = false;
+            this.onclose?.();
+            this._serverTransport.onclose?.();
+        }
+    }
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    setProtocolVersion;
+    _receiveFromServer(message, extra) {
+        this.onmessage?.(message, extra);
+    }
+}
+class InProcessServerTransport {
+    _clientTransport;
+    constructor(clientTransport) {
+        this._clientTransport = clientTransport;
+    }
+    async start() {
+    }
+    async send(message, options) {
+        this._clientTransport._receiveFromServer(message);
+    }
+    async close() {
+        this.onclose?.();
+    }
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    setProtocolVersion;
+    _receiveFromClient(message) {
+        this.onmessage?.(message);
+    }
+}

package/lib/mcp/server.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+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 server = new Server({ name: backend.name, version: backend.version }, {
+        capabilities: {
+            tools: {},
+        }
+    });
+    const tools = backend.tools();
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: tools.map(tool => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: zodToJsonSchema(tool.inputSchema),
+                annotations: {
+                    title: tool.title,
+                    readOnlyHint: tool.type === 'readOnly',
+                    destructiveHint: tool.type === 'destructive',
+                    openWorldHint: true,
+                },
+            })) };
+    });
+    let heartbeatRunning = false;
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (runHeartbeat && !heartbeatRunning) {
+            heartbeatRunning = true;
+            startHeartbeat(server);
+        }
+        const errorResult = (...messages) => ({
+            content: [{ type: 'text', text: 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`);
+        try {
+            return await backend.callTool(tool, tool.inputSchema.parse(request.params.arguments || {}));
+        }
+        catch (error) {
+            return errorResult(String(error));
+        }
+    });
+    addServerListener(server, 'initialized', () => backend.serverInitialized?.(server.getClientVersion()));
+    addServerListener(server, 'close', () => backend.serverClosed?.());
+    return server;
+}
+const startHeartbeat = (server) => {
+    const beat = () => {
+        Promise.race([
+            server.ping(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('ping timeout')), 5000)),
+        ]).then(() => {
+            setTimeout(beat, 3000);
+        }).catch(() => {
+            void server.close();
+        });
+    };
+    beat();
+};
+function addServerListener(server, event, listener) {
+    const oldListener = server[`on${event}`];
+    server[`on${event}`] = () => {
+        oldListener?.();
+        listener();
+    };
+}

package/lib/{transport.js → mcp/transport.js}

@@ -13,18 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import http from 'node:http';
-import assert from 'node:assert';
-import crypto from 'node:crypto';
+import crypto from 'crypto';
 import debug from 'debug';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-export async function startStdioTransport(server) {
-    await server.createConnection(new StdioServerTransport());
+import { httpAddressToString, startHttpServer } from '../httpServer.js';
+import * as mcpServer from './server.js';
+export async function start(serverBackendFactory, options) {
+    if (options.port !== undefined) {
+        const httpServer = await startHttpServer(options);
+        startHttpTransport(httpServer, serverBackendFactory);
+    }
+    else {
+        await startStdioTransport(serverBackendFactory);
+    }
+}
+async function startStdioTransport(serverBackendFactory) {
+    await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
 }
 const testDebug = debug('pw:mcp:test');
-async function handleSSE(server, req, res, url, sessions) {
+async function handleSSE(serverBackendFactory, req, res, url, sessions) {
     if (req.method === 'POST') {
         const sessionId = url.searchParams.get('sessionId');
         if (!sessionId) {
@@ -42,19 +51,17 @@ async function handleSSE(server, req, res, url, sessions) {
         const transport = new SSEServerTransport('/sse', res);
         sessions.set(transport.sessionId, transport);
         testDebug(`create SSE session: ${transport.sessionId}`);
-        const connection = await server.createConnection(transport);
+        await mcpServer.connect(serverBackendFactory, transport, false);
         res.on('close', () => {
             testDebug(`delete SSE session: ${transport.sessionId}`);
             sessions.delete(transport.sessionId);
-            // eslint-disable-next-line no-console
-            void connection.close().catch(e => console.error(e));
         });
         return;
     }
     res.statusCode = 405;
     res.end('Method not allowed');
 }
-async function handleStreamable(server, req, res, sessions) {
+async function handleStreamable(serverBackendFactory, req, res, sessions) {
     const sessionId = req.headers['mcp-session-id'];
     if (sessionId) {
         const transport = sessions.get(sessionId);
@@ -68,42 +75,33 @@ async function handleStreamable(server, req, res, sessions) {
     if (req.method === 'POST') {
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => crypto.randomUUID(),
-            onsessioninitialized: sessionId => {
+            onsessioninitialized: async (sessionId) => {
+                testDebug(`create http session: ${transport.sessionId}`);
+                await mcpServer.connect(serverBackendFactory, transport, true);
                 sessions.set(sessionId, transport);
             }
         });
         transport.onclose = () => {
-            if (transport.sessionId)
-                sessions.delete(transport.sessionId);
+            if (!transport.sessionId)
+                return;
+            sessions.delete(transport.sessionId);
+            testDebug(`delete http session: ${transport.sessionId}`);
         };
-        await server.createConnection(transport);
         await transport.handleRequest(req, res);
         return;
     }
     res.statusCode = 400;
     res.end('Invalid request');
 }
-export async function startHttpServer(config) {
-    const { host, port } = config;
-    const httpServer = http.createServer();
-    await new Promise((resolve, reject) => {
-        httpServer.on('error', reject);
-        httpServer.listen(port, host, () => {
-            resolve();
-            httpServer.removeListener('error', reject);
-        });
-    });
-    return httpServer;
-}
-export function startHttpTransport(httpServer, mcpServer) {
+function startHttpTransport(httpServer, serverBackendFactory) {
     const sseSessions = new Map();
     const streamableSessions = new Map();
     httpServer.on('request', async (req, res) => {
         const url = new URL(`http://localhost${req.url}`);
-        if (url.pathname.startsWith('/mcp'))
-            await handleStreamable(mcpServer, req, res, streamableSessions);
+        if (url.pathname.startsWith('/sse'))
+            await handleSSE(serverBackendFactory, req, res, url, sseSessions);
         else
-            await handleSSE(mcpServer, req, res, url, sseSessions);
+            await handleStreamable(serverBackendFactory, req, res, streamableSessions);
     });
     const url = httpAddressToString(httpServer.address());
     const message = [
@@ -112,22 +110,12 @@ export function startHttpTransport(httpServer, mcpServer) {
         JSON.stringify({
             'mcpServers': {
                 'playwright': {
-                    'url': `${url}/sse`
+                    'url': `${url}/mcp`
                 }
             }
         }, undefined, 2),
-        'If your client supports streamable HTTP, you can use the /mcp endpoint instead.',
+        'For legacy SSE transport support, you can use the /sse endpoint instead.',
     ].join('\n');
     // eslint-disable-next-line no-console
     console.error(message);
 }
-export function httpAddressToString(address) {
-    assert(address, 'Could not bind server socket');
-    if (typeof address === 'string')
-        return address;
-    const resolvedPort = address.port;
-    let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-    if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
-        resolvedHost = 'localhost';
-    return `http://${resolvedHost}:${resolvedPort}`;
-}

package/lib/package.js

@@ -13,8 +13,8 @@
  * 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 path from 'node:path';
+import fs from 'fs';
+import path from 'path';
+import url from 'url';
 const __filename = url.fileURLToPath(import.meta.url);
 export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/program.js

@@ -13,13 +13,17 @@
  * 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 { startHttpServer, startHttpTransport, startStdioTransport } from './transport.js';
-import { resolveCLIConfig } from './config.js';
-import { Server } from './server.js';
+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 { BrowserServerBackend } from './browserServerBackend.js';
+import { Context } from './context.js';
+import { contextFactory } from './browserContextFactory.js';
+import { runLoopTools } from './loopTools/main.js';
 program
     .version('Version ' + packageJSON.version)
     .name(packageJSON.name)
@@ -27,8 +31,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,27 +40,40 @@ 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.')
     .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
     .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.')
     .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
     .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
     .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('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').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();
+    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 (httpServer)
-        startHttpTransport(httpServer, server);
-    else
-        await startStdioTransport(server);
+    if (options.extension) {
+        await runWithExtension(config, abortController);
+        return;
+    }
+    if (options.loopTools) {
+        await runLoopTools(config);
+        return;
+    }
+    const browserContextFactory = contextFactory(config.browser);
+    const serverBackendFactory = () => new BrowserServerBackend(config, browserContextFactory);
+    await mcpTransport.start(serverBackendFactory, config.server);
     if (config.saveTrace) {
         const server = await startTraceViewerServer();
         const urlPrefix = server.urlPrefix('human-readable');
@@ -66,7 +82,21 @@ program
         console.error('\nTrace viewer listening on ' + url);
     }
 });
-function semicolonSeparatedList(value) {
-    return value.split(';').map(v => v.trim());
+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

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+export class Response {
+    _result = [];
+    _code = [];
+    _images = [];
+    _context;
+    _includeSnapshot = false;
+    _includeTabs = false;
+    _snapshot;
+    toolName;
+    toolArgs;
+    constructor(context, toolName, toolArgs) {
+        this._context = context;
+        this.toolName = toolName;
+        this.toolArgs = toolArgs;
+    }
+    addResult(result) {
+        this._result.push(result);
+    }
+    result() {
+        return this._result.join('\n');
+    }
+    addCode(code) {
+        this._code.push(code);
+    }
+    code() {
+        return this._code.join('\n');
+    }
+    addImage(image) {
+        this._images.push(image);
+    }
+    images() {
+        return this._images;
+    }
+    setIncludeSnapshot() {
+        this._includeSnapshot = true;
+    }
+    setIncludeTabs() {
+        this._includeTabs = true;
+    }
+    async snapshot() {
+        if (this._snapshot !== undefined)
+            return this._snapshot;
+        if (this._includeSnapshot && this._context.currentTab())
+            this._snapshot = await this._context.currentTabOrDie().captureSnapshot();
+        else
+            this._snapshot = '';
+        return this._snapshot;
+    }
+    async serialize() {
+        const response = [];
+        // Start with command result.
+        if (this._result.length) {
+            response.push('### Result');
+            response.push(this._result.join('\n'));
+            response.push('');
+        }
+        // Add code if it exists.
+        if (this._code.length) {
+            response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join('\n')}
+\`\`\``);
+            response.push('');
+        }
+        // List browser tabs.
+        if (this._includeSnapshot || this._includeTabs)
+            response.push(...(await this._context.listTabsMarkdown(this._includeTabs)));
+        // Add snapshot if provided.
+        const snapshot = await this.snapshot();
+        if (snapshot)
+            response.push(snapshot, '');
+        // Main response part
+        const content = [
+            { type: 'text', text: response.join('\n') },
+        ];
+        // Image attachments.
+        if (this._context.config.imageResponses !== 'omit') {
+            for (const image of this._images)
+                content.push({ type: 'image', data: image.data.toString('base64'), mimeType: image.contentType });
+        }
+        return { content };
+    }
+}

package/lib/sessionLog.js

@@ -0,0 +1,70 @@
+/**
+ * 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 fs from 'fs';
+import path from 'path';
+import { outputFile } from './config.js';
+let sessionOrdinal = 0;
+export class SessionLog {
+    _folder;
+    _file;
+    _ordinal = 0;
+    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')}`);
+        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(), '```');
+        }
+        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}`);
+        }
+        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}`);
+        }
+        lines.push('', '');
+        await fs.promises.appendFile(this._file, lines.join('\n'));
+    }
+}
+function extension(contentType) {
+    if (contentType === 'image/jpeg')
+        return 'jpg';
+    return 'png';
+}