@wordbricks/playwright-mcp 0.1.3

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 '../utils/httpServer.js';
+import { logUnhandledError } from '../utils/log.js';
+import { ManualPromise } from '../utils/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 '../utils/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/frameworkPatterns.js

@@ -0,0 +1,35 @@
+/**
+ * Shared framework state patterns used by framework state detection hook
+ */
+export const FRAMEWORK_STATE_PATTERNS = [
+    // React/Next.js
+    '__NEXT_DATA__',
+    '__reactServerState',
+    // Remix
+    '__remixContext',
+    '__remixManifest',
+    '__remixRouteModules',
+    // Apollo GraphQL
+    '__APOLLO_STATE__',
+    '__APOLLO_CLIENT__',
+    // Redux/State Management
+    '__PRELOADED_STATE__',
+    '__INITIAL_STATE__',
+    '__REDUX_STATE__',
+    // Vue/Nuxt
+    '__NUXT__',
+    // Gatsby
+    '___gatsby',
+    '___loader',
+    // Generic SSR
+    '__SSR_DATA__',
+    '__APP_STATE__',
+    '__SERVER_STATE__',
+    // Others
+    '__QWIK_STATE__',
+    '__SVELTE__',
+    '__ANGULAR__',
+    '__SOLID__',
+    '__ASTRO_DATA__',
+];
+export const MAX_DISPLAY_ITEMS = 5;

package/lib/hooks/core.js

@@ -0,0 +1,144 @@
+import { reduce } from '@fxts/core';
+import { getEventStore, trackEvent } from './events.js';
+import { consumeEvents } from './eventConsumer.js';
+import { toolNameSchema } from './schema.js';
+export { Ok, Err } from '../utils/result.js';
+export const runHook = async (hook, ctx) => {
+    const result = await hook.handler(ctx);
+    if (!result.ok)
+        throw result.error;
+    return ctx;
+};
+export const hookRegistryMap = new WeakMap();
+export const createHookRegistry = () => ({
+    tools: new Map(),
+});
+export const setToolHooks = (registry, toolHooks) => ({
+    tools: new Map([...registry.tools, [toolHooks.toolName, toolHooks]]),
+});
+export const getToolHooks = (registry, toolName) => {
+    return registry.tools.get(toolName);
+};
+export const wrapToolWithHooks = (tool, registry) => {
+    const parsedName = toolNameSchema.safeParse(tool.schema.name);
+    if (!parsedName.success)
+        return tool; // Tool name not in our schema, don't apply hooks
+    // NOTE: This means tool call events won't be tracked for tools not in toolNameSchema.
+    // All tools exposed by this MCP server should be added to the schema.
+    const toolName = parsedName.data;
+    const toolHooks = getToolHooks(registry, toolName);
+    // Even if no hooks configured, we still need to consume events and track tool calls
+    if (!toolHooks || (toolHooks.preHooks.length === 0 && toolHooks.postHooks.length === 0)) {
+        return {
+            ...tool,
+            handle: async (context, params, response) => {
+                const eventStore = getEventStore(context);
+                // Consume pre-tool events
+                consumeEvents(context, eventStore, response);
+                // Track tool execution
+                const startTime = Date.now();
+                let success = true;
+                try {
+                    await tool.handle(context, params, response);
+                }
+                catch (error) {
+                    success = false;
+                    throw error;
+                }
+                finally {
+                    // Record tool call completion
+                    const executionTime = Date.now() - startTime;
+                    trackEvent(context, {
+                        type: 'tool-call',
+                        data: {
+                            toolName,
+                            params: params,
+                            executionTime,
+                            success,
+                        },
+                        timestamp: startTime,
+                    });
+                    // Consume post-tool events
+                    consumeEvents(context, eventStore, response);
+                }
+            },
+        };
+    }
+    return {
+        ...tool,
+        handle: async (context, params, response) => {
+            const eventStore = getEventStore(context);
+            // Consume pre-tool events
+            consumeEvents(context, eventStore, response);
+            // Track tool execution
+            const startTime = Date.now();
+            // Run pre-hooks
+            const hookContext = {
+                context,
+                tab: context.currentTab(),
+                params,
+                toolName,
+                response,
+                eventStore,
+            };
+            try {
+                await reduce(async (ctx, hook) => runHook(hook, await ctx), Promise.resolve(hookContext), toolHooks.preHooks);
+            }
+            catch (error) {
+                // Pre-hook already handled messaging (e.g., require-tab pre-hook sets tabs section)
+                // Avoid adding a duplicate error line in the Result section.
+                return;
+            }
+            // Run original tool
+            let success = true;
+            try {
+                await tool.handle(context, params, response);
+            }
+            catch (error) {
+                success = false;
+                throw error;
+            }
+            finally {
+                // Record tool call completion
+                const executionTime = Date.now() - startTime;
+                trackEvent(context, {
+                    type: 'tool-call',
+                    data: {
+                        toolName,
+                        params: params,
+                        executionTime,
+                        success,
+                    },
+                    timestamp: startTime,
+                });
+            }
+            // Run post-hooks
+            const postHookContext = {
+                context,
+                tab: context.currentTab(),
+                params,
+                toolName,
+                response,
+                eventStore: getEventStore(context),
+            };
+            try {
+                await reduce(async (ctx, hook) => runHook(hook, await ctx), Promise.resolve(postHookContext), toolHooks.postHooks);
+            }
+            catch (error) {
+                response.addError(error instanceof Error ? error.message : 'Post-hook failed');
+            }
+            // Consume post-tool events
+            consumeEvents(context, eventStore, response);
+        },
+    };
+};
+export const getHookRegistry = (context) => {
+    const registry = hookRegistryMap.get(context);
+    return registry || createHookRegistry();
+};
+export const applyHooksToTools = (tools, context) => {
+    const registry = getHookRegistry(context);
+    if (registry.tools.size === 0)
+        return tools;
+    return tools.map(tool => wrapToolWithHooks(tool, registry));
+};

package/lib/hooks/eventConsumer.js

@@ -0,0 +1,39 @@
+import { getEventsAfter, updateLastSeenId } from './events.js';
+import { formatWaitEvent } from './waitHook.js';
+import { formatPageHeightEvent } from './pageHeightHook.js';
+import { formatNetworkEvent } from './networkTrackingHook.js';
+import { planGroupedMessages } from './grouping.js';
+import { formatToolCallEvent } from './formatToolCallEvent.js';
+import { formatFrameworkStateEvent } from './frameworkStateHook.js';
+import { formatJsonLdEvent } from './jsonLdDetectionHook.js';
+const eventFormatters = {
+    'wait': formatWaitEvent,
+    'page-height-change': formatPageHeightEvent,
+    'network-request': formatNetworkEvent,
+    'tool-call': formatToolCallEvent,
+    'framework-state': formatFrameworkStateEvent,
+    'json-ld': formatJsonLdEvent,
+};
+const formatEvent = (event) => {
+    const formatter = eventFormatters[event.type];
+    return formatter(event);
+};
+const consumeEvent = (event, response, plan) => {
+    if (plan.skipIds.has(event.id))
+        return;
+    const replacement = plan.replacementById.get(event.id);
+    const formattedMessage = replacement ?? formatEvent(event);
+    response.addEvent(`[${event.id}] ${formattedMessage}`);
+};
+export const consumeEvents = (context, eventStore, response) => {
+    const unconsumedEvents = getEventsAfter(eventStore, eventStore.lastSeenEventId);
+    if (unconsumedEvents.length === 0)
+        return;
+    const plan = planGroupedMessages(unconsumedEvents);
+    // Consume all events in chronological order
+    for (const event of unconsumedEvents)
+        consumeEvent(event, response, plan);
+    // Update last seen event ID
+    const latestEvent = unconsumedEvents[unconsumedEvents.length - 1];
+    updateLastSeenId(context, latestEvent.id);
+};

package/lib/hooks/events.js

@@ -0,0 +1,42 @@
+import { pipe, filter, toArray } from '@fxts/core';
+export const isEventType = (type) => (event) => event.type === type;
+export const createEventStore = () => ({
+    events: new Map(),
+    lastSeenEventId: undefined,
+    nextEventId: 1,
+});
+export const trackEvent = (context, params) => {
+    const store = getEventStore(context);
+    const eventId = store.nextEventId++;
+    const event = {
+        id: eventId,
+        type: params.type,
+        data: params.data,
+        timestamp: params.timestamp ?? Date.now()
+    };
+    store.events.set(eventId, event);
+    return eventId;
+};
+export const updateLastSeenId = (context, eventId) => {
+    const store = getEventStore(context);
+    store.lastSeenEventId = eventId;
+    return context;
+};
+export const getEventsAfter = (store, afterEventId) => {
+    if (!afterEventId) {
+        return pipe(store.events.values(), toArray);
+    }
+    return pipe(store.events.values(), filter(event => event.id > afterEventId), toArray);
+};
+const eventStoreMap = new WeakMap();
+export const getEventStore = (context) => {
+    let store = eventStoreMap.get(context);
+    if (!store) {
+        store = createEventStore();
+        eventStoreMap.set(context, store);
+    }
+    return store;
+};
+export const setEventStore = (context, store) => {
+    eventStoreMap.set(context, store);
+};

package/lib/hooks/formatToolCallEvent.js

@@ -0,0 +1,16 @@
+export const formatToolCallEvent = (event) => {
+    const { toolName, params, executionTime, success } = event.data;
+    // Format parameters (truncate if too long)
+    const paramStr = params && Object.keys(params).length > 0
+        ? ` with params: ${JSON.stringify(params, null, 0).slice(0, 100)}`
+        : '';
+    // Format execution time if available
+    const timeStr = executionTime !== undefined
+        ? ` (${executionTime}ms)`
+        : '';
+    // Format success status if available
+    const statusStr = success !== undefined
+        ? success ? ' ✓' : ' ✗'
+        : '';
+    return `Tool ${toolName}${paramStr}${timeStr}${statusStr}`;
+};