@playwright/mcp 0.0.31 → 0.0.33

package/lib/extension/cdpRelay.js

@@ -0,0 +1,346 @@
+/**
+ * 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.
+ */
+/**
+ * WebSocket server that bridges Playwright MCP and Chrome Extension
+ *
+ * Endpoints:
+ * - /cdp/guid - Full CDP interface for Playwright MCP
+ * - /extension/guid - Extension connection for chrome.debugger forwarding
+ */
+import { spawn } from 'child_process';
+import debug from 'debug';
+import { WebSocket, WebSocketServer } from 'ws';
+import { httpAddressToString } from '../httpServer.js';
+import { logUnhandledError } from '../log.js';
+import { ManualPromise } from '../manualPromise.js';
+// @ts-ignore
+const { registry } = await import('playwright-core/lib/server/registry/index');
+const debugLogger = debug('pw:mcp:relay');
+export class CDPRelayServer {
+    _wsHost;
+    _browserChannel;
+    _userDataDir;
+    _cdpPath;
+    _extensionPath;
+    _wss;
+    _playwrightConnection = null;
+    _extensionConnection = null;
+    _connectedTabInfo;
+    _nextSessionId = 1;
+    _extensionConnectionPromise;
+    constructor(server, browserChannel, userDataDir) {
+        this._wsHost = httpAddressToString(server.address()).replace(/^http/, 'ws');
+        this._browserChannel = browserChannel;
+        this._userDataDir = userDataDir;
+        const uuid = crypto.randomUUID();
+        this._cdpPath = `/cdp/${uuid}`;
+        this._extensionPath = `/extension/${uuid}`;
+        this._resetExtensionConnection();
+        this._wss = new WebSocketServer({ server });
+        this._wss.on('connection', this._onConnection.bind(this));
+    }
+    cdpEndpoint() {
+        return `${this._wsHost}${this._cdpPath}`;
+    }
+    extensionEndpoint() {
+        return `${this._wsHost}${this._extensionPath}`;
+    }
+    async ensureExtensionConnectionForMCPContext(clientInfo, abortSignal) {
+        debugLogger('Ensuring extension connection for MCP context');
+        if (this._extensionConnection)
+            return;
+        this._connectBrowser(clientInfo);
+        debugLogger('Waiting for incoming extension connection');
+        await Promise.race([
+            this._extensionConnectionPromise,
+            new Promise((_, reject) => abortSignal.addEventListener('abort', reject))
+        ]);
+        debugLogger('Extension connection established');
+    }
+    _connectBrowser(clientInfo) {
+        const mcpRelayEndpoint = `${this._wsHost}${this._extensionPath}`;
+        // Need to specify "key" in the manifest.json to make the id stable when loading from file.
+        const url = new URL('chrome-extension://jakfalbnbhgkpmoaakfflhflbfpkailf/connect.html');
+        url.searchParams.set('mcpRelayUrl', mcpRelayEndpoint);
+        url.searchParams.set('client', JSON.stringify(clientInfo));
+        const href = url.toString();
+        const executableInfo = registry.findExecutable(this._browserChannel);
+        if (!executableInfo)
+            throw new Error(`Unsupported channel: "${this._browserChannel}"`);
+        const executablePath = executableInfo.executablePath();
+        if (!executablePath)
+            throw new Error(`"${this._browserChannel}" executable not found. Make sure it is installed at a standard location.`);
+        const args = [];
+        if (this._userDataDir)
+            args.push(`--user-data-dir=${this._userDataDir}`);
+        args.push(href);
+        spawn(executablePath, args, {
+            windowsHide: true,
+            detached: true,
+            shell: false,
+            stdio: 'ignore',
+        });
+    }
+    stop() {
+        this.closeConnections('Server stopped');
+        this._wss.close();
+    }
+    closeConnections(reason) {
+        this._closePlaywrightConnection(reason);
+        this._closeExtensionConnection(reason);
+    }
+    _onConnection(ws, request) {
+        const url = new URL(`http://localhost${request.url}`);
+        debugLogger(`New connection to ${url.pathname}`);
+        if (url.pathname === this._cdpPath) {
+            this._handlePlaywrightConnection(ws);
+        }
+        else if (url.pathname === this._extensionPath) {
+            this._handleExtensionConnection(ws);
+        }
+        else {
+            debugLogger(`Invalid path: ${url.pathname}`);
+            ws.close(4004, 'Invalid path');
+        }
+    }
+    _handlePlaywrightConnection(ws) {
+        if (this._playwrightConnection) {
+            debugLogger('Rejecting second Playwright connection');
+            ws.close(1000, 'Another CDP client already connected');
+            return;
+        }
+        this._playwrightConnection = ws;
+        ws.on('message', async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                await this._handlePlaywrightMessage(message);
+            }
+            catch (error) {
+                debugLogger(`Error while handling Playwright message\n${data.toString()}\n`, error);
+            }
+        });
+        ws.on('close', () => {
+            if (this._playwrightConnection !== ws)
+                return;
+            this._playwrightConnection = null;
+            this._closeExtensionConnection('Playwright client disconnected');
+            debugLogger('Playwright WebSocket closed');
+        });
+        ws.on('error', error => {
+            debugLogger('Playwright WebSocket error:', error);
+        });
+        debugLogger('Playwright MCP connected');
+    }
+    _closeExtensionConnection(reason) {
+        this._extensionConnection?.close(reason);
+        this._extensionConnectionPromise.reject(new Error(reason));
+        this._resetExtensionConnection();
+    }
+    _resetExtensionConnection() {
+        this._connectedTabInfo = undefined;
+        this._extensionConnection = null;
+        this._extensionConnectionPromise = new ManualPromise();
+        void this._extensionConnectionPromise.catch(logUnhandledError);
+    }
+    _closePlaywrightConnection(reason) {
+        if (this._playwrightConnection?.readyState === WebSocket.OPEN)
+            this._playwrightConnection.close(1000, reason);
+        this._playwrightConnection = null;
+    }
+    _handleExtensionConnection(ws) {
+        if (this._extensionConnection) {
+            ws.close(1000, 'Another extension connection already established');
+            return;
+        }
+        this._extensionConnection = new ExtensionConnection(ws);
+        this._extensionConnection.onclose = (c, reason) => {
+            debugLogger('Extension WebSocket closed:', reason, c === this._extensionConnection);
+            if (this._extensionConnection !== c)
+                return;
+            this._resetExtensionConnection();
+            this._closePlaywrightConnection(`Extension disconnected: ${reason}`);
+        };
+        this._extensionConnection.onmessage = this._handleExtensionMessage.bind(this);
+        this._extensionConnectionPromise.resolve();
+    }
+    _handleExtensionMessage(method, params) {
+        switch (method) {
+            case 'forwardCDPEvent':
+                const sessionId = params.sessionId || this._connectedTabInfo?.sessionId;
+                this._sendToPlaywright({
+                    sessionId,
+                    method: params.method,
+                    params: params.params
+                });
+                break;
+            case 'detachedFromTab':
+                debugLogger('← Debugger detached from tab:', params);
+                this._connectedTabInfo = undefined;
+                break;
+        }
+    }
+    async _handlePlaywrightMessage(message) {
+        debugLogger('← Playwright:', `${message.method} (id=${message.id})`);
+        const { id, sessionId, method, params } = message;
+        try {
+            const result = await this._handleCDPCommand(method, params, sessionId);
+            this._sendToPlaywright({ id, sessionId, result });
+        }
+        catch (e) {
+            debugLogger('Error in the extension:', e);
+            this._sendToPlaywright({
+                id,
+                sessionId,
+                error: { message: e.message }
+            });
+        }
+    }
+    async _handleCDPCommand(method, params, sessionId) {
+        switch (method) {
+            case 'Browser.getVersion': {
+                return {
+                    protocolVersion: '1.3',
+                    product: 'Chrome/Extension-Bridge',
+                    userAgent: 'CDP-Bridge-Server/1.0.0',
+                };
+            }
+            case 'Browser.setDownloadBehavior': {
+                return {};
+            }
+            case 'Target.setAutoAttach': {
+                // Forward child session handling.
+                if (sessionId)
+                    break;
+                // Simulate auto-attach behavior with real target info
+                const { targetInfo } = await this._extensionConnection.send('attachToTab');
+                this._connectedTabInfo = {
+                    targetInfo,
+                    sessionId: `pw-tab-${this._nextSessionId++}`,
+                };
+                debugLogger('Simulating auto-attach');
+                this._sendToPlaywright({
+                    method: 'Target.attachedToTarget',
+                    params: {
+                        sessionId: this._connectedTabInfo.sessionId,
+                        targetInfo: {
+                            ...this._connectedTabInfo.targetInfo,
+                            attached: true,
+                        },
+                        waitingForDebugger: false
+                    }
+                });
+                return {};
+            }
+            case 'Target.getTargetInfo': {
+                return this._connectedTabInfo?.targetInfo;
+            }
+        }
+        return await this._forwardToExtension(method, params, sessionId);
+    }
+    async _forwardToExtension(method, params, sessionId) {
+        if (!this._extensionConnection)
+            throw new Error('Extension not connected');
+        // Top level sessionId is only passed between the relay and the client.
+        if (this._connectedTabInfo?.sessionId === sessionId)
+            sessionId = undefined;
+        return await this._extensionConnection.send('forwardCDPCommand', { sessionId, method, params });
+    }
+    _sendToPlaywright(message) {
+        debugLogger('→ Playwright:', `${message.method ?? `response(id=${message.id})`}`);
+        this._playwrightConnection?.send(JSON.stringify(message));
+    }
+}
+class ExtensionConnection {
+    _ws;
+    _callbacks = new Map();
+    _lastId = 0;
+    onmessage;
+    onclose;
+    constructor(ws) {
+        this._ws = ws;
+        this._ws.on('message', this._onMessage.bind(this));
+        this._ws.on('close', this._onClose.bind(this));
+        this._ws.on('error', this._onError.bind(this));
+    }
+    async send(method, params, sessionId) {
+        if (this._ws.readyState !== WebSocket.OPEN)
+            throw new Error(`Unexpected WebSocket state: ${this._ws.readyState}`);
+        const id = ++this._lastId;
+        this._ws.send(JSON.stringify({ id, method, params, sessionId }));
+        const error = new Error(`Protocol error: ${method}`);
+        return new Promise((resolve, reject) => {
+            this._callbacks.set(id, { resolve, reject, error });
+        });
+    }
+    close(message) {
+        debugLogger('closing extension connection:', message);
+        if (this._ws.readyState === WebSocket.OPEN)
+            this._ws.close(1000, message);
+    }
+    _onMessage(event) {
+        const eventData = event.toString();
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(eventData);
+        }
+        catch (e) {
+            debugLogger(`<closing ws> Closing websocket due to malformed JSON. eventData=${eventData} e=${e?.message}`);
+            this._ws.close();
+            return;
+        }
+        try {
+            this._handleParsedMessage(parsedJson);
+        }
+        catch (e) {
+            debugLogger(`<closing ws> Closing websocket due to failed onmessage callback. eventData=${eventData} e=${e?.message}`);
+            this._ws.close();
+        }
+    }
+    _handleParsedMessage(object) {
+        if (object.id && this._callbacks.has(object.id)) {
+            const callback = this._callbacks.get(object.id);
+            this._callbacks.delete(object.id);
+            if (object.error) {
+                const error = callback.error;
+                error.message = object.error;
+                callback.reject(error);
+            }
+            else {
+                callback.resolve(object.result);
+            }
+        }
+        else if (object.id) {
+            debugLogger('← Extension: unexpected response', object);
+        }
+        else {
+            this.onmessage?.(object.method, object.params);
+        }
+    }
+    _onClose(event) {
+        debugLogger(`<ws closed> code=${event.code} reason=${event.reason}`);
+        this._dispose();
+        this.onclose?.(this, event.reason);
+    }
+    _onError(event) {
+        debugLogger(`<ws error> message=${event.message} type=${event.type} target=${event.target}`);
+        this._dispose();
+    }
+    _dispose() {
+        for (const callback of this._callbacks.values())
+            callback.reject(new Error('WebSocket closed'));
+        this._callbacks.clear();
+    }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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 { ExtensionContextFactory } from './extensionContextFactory.js';
+import { BrowserServerBackend } from '../browserServerBackend.js';
+import * as mcpTransport from '../mcp/transport.js';
+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/httpServer.js

@@ -13,189 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import fs from 'fs';
-import path from 'path';
+import assert from 'assert';
 import http from 'http';
-import mime from 'mime';
-import { ManualPromise } from './manualPromise.js';
-export class HttpServer {
-    _server;
-    _urlPrefixPrecise = '';
-    _urlPrefixHumanReadable = '';
-    _port = 0;
-    _routes = [];
-    constructor() {
-        this._server = http.createServer(this._onRequest.bind(this));
-        decorateServer(this._server);
-    }
-    server() {
-        return this._server;
-    }
-    routePrefix(prefix, handler) {
-        this._routes.push({ prefix, handler });
-    }
-    routePath(path, handler) {
-        this._routes.push({ exact: path, handler });
-    }
-    port() {
-        return this._port;
-    }
-    async _tryStart(port, host) {
-        const errorPromise = new ManualPromise();
-        const errorListener = (error) => errorPromise.reject(error);
-        this._server.on('error', errorListener);
-        try {
-            this._server.listen(port, host);
-            await Promise.race([
-                new Promise(cb => this._server.once('listening', cb)),
-                errorPromise,
-            ]);
-        }
-        finally {
-            this._server.removeListener('error', errorListener);
-        }
-    }
-    async start(options = {}) {
-        const host = options.host || 'localhost';
-        if (options.preferredPort) {
-            try {
-                await this._tryStart(options.preferredPort, host);
-            }
-            catch (e) {
-                if (!e || !e.message || !e.message.includes('EADDRINUSE'))
-                    throw e;
-                await this._tryStart(undefined, host);
-            }
-        }
-        else {
-            await this._tryStart(options.port, host);
-        }
-        const address = this._server.address();
-        if (typeof address === 'string') {
-            this._urlPrefixPrecise = address;
-            this._urlPrefixHumanReadable = address;
-        }
-        else {
-            this._port = address.port;
-            const resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
-            this._urlPrefixPrecise = `http://${resolvedHost}:${address.port}`;
-            this._urlPrefixHumanReadable = `http://${host}:${address.port}`;
-        }
-    }
-    async stop() {
-        await new Promise(cb => this._server.close(cb));
-    }
-    urlPrefix(purpose) {
-        return purpose === 'human-readable' ? this._urlPrefixHumanReadable : this._urlPrefixPrecise;
-    }
-    serveFile(request, response, absoluteFilePath, headers) {
-        try {
-            for (const [name, value] of Object.entries(headers || {}))
-                response.setHeader(name, value);
-            if (request.headers.range)
-                this._serveRangeFile(request, response, absoluteFilePath);
-            else
-                this._serveFile(response, absoluteFilePath);
-            return true;
-        }
-        catch (e) {
-            return false;
-        }
-    }
-    _serveFile(response, absoluteFilePath) {
-        const content = fs.readFileSync(absoluteFilePath);
-        response.statusCode = 200;
-        const contentType = mime.getType(path.extname(absoluteFilePath)) || 'application/octet-stream';
-        response.setHeader('Content-Type', contentType);
-        response.setHeader('Content-Length', content.byteLength);
-        response.end(content);
-    }
-    _serveRangeFile(request, response, absoluteFilePath) {
-        const range = request.headers.range;
-        if (!range || !range.startsWith('bytes=') || range.includes(', ') || [...range].filter(char => char === '-').length !== 1) {
-            response.statusCode = 400;
-            return response.end('Bad request');
-        }
-        // Parse the range header: https://datatracker.ietf.org/doc/html/rfc7233#section-2.1
-        const [startStr, endStr] = range.replace(/bytes=/, '').split('-');
-        // Both start and end (when passing to fs.createReadStream) and the range header are inclusive and start counting at 0.
-        let start;
-        let end;
-        const size = fs.statSync(absoluteFilePath).size;
-        if (startStr !== '' && endStr === '') {
-            // No end specified: use the whole file
-            start = +startStr;
-            end = size - 1;
-        }
-        else if (startStr === '' && endStr !== '') {
-            // No start specified: calculate start manually
-            start = size - +endStr;
-            end = size - 1;
-        }
-        else {
-            start = +startStr;
-            end = +endStr;
-        }
-        // Handle unavailable range request
-        if (Number.isNaN(start) || Number.isNaN(end) || start >= size || end >= size || start > end) {
-            // Return the 416 Range Not Satisfiable: https://datatracker.ietf.org/doc/html/rfc7233#section-4.4
-            response.writeHead(416, {
-                'Content-Range': `bytes */${size}`
-            });
-            return response.end();
-        }
-        // Sending Partial Content: https://datatracker.ietf.org/doc/html/rfc7233#section-4.1
-        response.writeHead(206, {
-            'Content-Range': `bytes ${start}-${end}/${size}`,
-            'Accept-Ranges': 'bytes',
-            'Content-Length': end - start + 1,
-            'Content-Type': mime.getType(path.extname(absoluteFilePath)),
+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);
         });
-        const readable = fs.createReadStream(absoluteFilePath, { start, end });
-        readable.pipe(response);
-    }
-    _onRequest(request, response) {
-        if (request.method === 'OPTIONS') {
-            response.writeHead(200);
-            response.end();
-            return;
-        }
-        request.on('error', () => response.end());
-        try {
-            if (!request.url) {
-                response.end();
-                return;
-            }
-            const url = new URL('http://localhost' + request.url);
-            for (const route of this._routes) {
-                if (route.exact && url.pathname === route.exact) {
-                    route.handler(request, response);
-                    return;
-                }
-                if (route.prefix && url.pathname.startsWith(route.prefix)) {
-                    route.handler(request, response);
-                    return;
-                }
-            }
-            response.statusCode = 404;
-            response.end();
-        }
-        catch (e) {
-            response.end();
-        }
-    }
-}
-function decorateServer(server) {
-    const sockets = new Set();
-    server.on('connection', socket => {
-        sockets.add(socket);
-        socket.once('close', () => sockets.delete(socket));
     });
-    const close = server.close;
-    server.close = (callback) => {
-        for (const socket of sockets)
-            socket.destroy();
-        sockets.clear();
-        return close.call(server, callback);
-    };
+    return httpServer;
+}
+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/index.js

@@ -13,15 +13,18 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { createConnection as createConnectionImpl } from './connection.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
 import { resolveConfig } from './config.js';
 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 createConnectionImpl(config, factory);
+    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;