@wordbricks/playwright-mcp 0.1.25 → 0.1.26

package/lib/mcp/proxyBackend.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ListRootsRequestSchema, PingRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { logUnhandledError } from "../utils/log.js";
+import { packageJSON } from "../utils/package.js";
+export class ProxyBackend {
+    name = "Playwright MCP Client Switcher";
+    version = packageJSON.version;
+    _mcpProviders;
+    _currentClient;
+    _contextSwitchTool;
+    _roots = [];
+    constructor(mcpProviders) {
+        this._mcpProviders = mcpProviders;
+        this._contextSwitchTool = this._defineContextSwitchTool();
+    }
+    async initialize(server) {
+        if (this._currentClient)
+            return;
+        const version = server.getClientVersion();
+        const capabilities = server.getClientCapabilities();
+        if (capabilities?.roots &&
+            version &&
+            clientsWithRoots.includes(version.name)) {
+            const { roots } = await server.listRoots();
+            this._roots = roots;
+        }
+        await this._setCurrentClient(this._mcpProviders[0]);
+    }
+    async listTools() {
+        const response = await this._currentClient.listTools();
+        if (this._mcpProviders.length === 1)
+            return response.tools;
+        return [...response.tools, this._contextSwitchTool];
+    }
+    async callTool(name, args) {
+        if (name === this._contextSwitchTool.name)
+            return this._callContextSwitchTool(args);
+        return (await this._currentClient.callTool({
+            name,
+            arguments: args,
+        }));
+    }
+    serverClosed() {
+        void this._currentClient?.close().catch(logUnhandledError);
+        this._currentClient = undefined;
+    }
+    async _callContextSwitchTool(params) {
+        try {
+            const factory = this._mcpProviders.find((factory) => factory.name === params.name);
+            if (!factory)
+                throw new Error("Unknown connection method: " + params.name);
+            await this._setCurrentClient(factory);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "### Result\nSuccessfully changed connection method.\n",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `### Result\nError: ${error}\n` }],
+                isError: true,
+            };
+        }
+    }
+    _defineContextSwitchTool() {
+        return {
+            name: "browser_connect",
+            description: [
+                "Connect to a browser using one of the available methods:",
+                ...this._mcpProviders.map((factory) => `- "${factory.name}": ${factory.description}`),
+            ].join("\n"),
+            inputSchema: zodToJsonSchema(z.object({
+                name: z
+                    .enum(this._mcpProviders.map((factory) => factory.name))
+                    .default(this._mcpProviders[0].name)
+                    .describe("The method to use to connect to the browser"),
+            }), { strictUnions: true }),
+            annotations: {
+                title: "Connect to a browser context",
+                readOnlyHint: true,
+                openWorldHint: false,
+            },
+        };
+    }
+    async _setCurrentClient(factory) {
+        await this._currentClient?.close();
+        this._currentClient = undefined;
+        const client = new Client({
+            name: "Playwright MCP Proxy",
+            version: packageJSON.version,
+        });
+        client.registerCapabilities({
+            roots: {
+                listChanged: true,
+            },
+        });
+        client.setRequestHandler(ListRootsRequestSchema, () => ({
+            roots: this._roots,
+        }));
+        client.setRequestHandler(PingRequestSchema, () => ({}));
+        const transport = await factory.connect();
+        await client.connect(transport);
+        this._currentClient = client;
+    }
+}
+const clientsWithRoots = [
+    "Visual Studio Code",
+    "Visual Studio Code - Insiders",
+];

package/lib/mcp/server.js

@@ -0,0 +1,91 @@
+/**
+ * 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 debug from "debug";
+import ms from "ms";
+import { logUnhandledError } from "../utils/log.js";
+import { ManualPromise } from "../utils/manualPromise.js";
+const serverDebug = debug("pw:mcp:server");
+export async function connect(serverBackendFactory, transport, runHeartbeat) {
+    const backend = serverBackendFactory();
+    const server = createServer(backend, runHeartbeat);
+    await server.connect(transport);
+    return { name: backend.name, version: backend.version };
+}
+export function createServer(backend, runHeartbeat) {
+    const initializedPromise = new ManualPromise();
+    const server = new Server({ name: backend.name, version: backend.version }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        serverDebug("listTools");
+        await initializedPromise;
+        const tools = await backend.listTools();
+        return { tools };
+    });
+    let heartbeatRunning = false;
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        serverDebug("callTool", request);
+        await initializedPromise;
+        if (runHeartbeat && !heartbeatRunning) {
+            heartbeatRunning = true;
+            startHeartbeat(server);
+        }
+        try {
+            return await backend.callTool(request.params.name, request.params.arguments || {});
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: "### Result\n" + String(error) }],
+                isError: true,
+            };
+        }
+    });
+    addServerListener(server, "initialized", () => {
+        backend
+            .initialize?.(server)
+            .then(() => initializedPromise.resolve())
+            .catch(logUnhandledError);
+    });
+    addServerListener(server, "close", () => backend.serverClosed?.());
+    return server;
+}
+const startHeartbeat = (server) => {
+    const beat = () => {
+        serverDebug("Health check...");
+        Promise.race([
+            server.ping(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("ping timeout")), ms("5s"))),
+        ])
+            .then(() => {
+            setTimeout(beat, ms("3s"));
+        })
+            .catch(() => {
+            void server.close();
+        });
+    };
+    beat();
+};
+function addServerListener(server, event, listener) {
+    const oldListener = server[`on${event}`];
+    server[`on${event}`] = () => {
+        oldListener?.();
+        listener();
+    };
+}

package/lib/mcp/tool.js

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+const typesWithIntent = ["action", "assertion", "input"];
+export function toMcpTool(tool, options) {
+    const inputSchema = options?.addIntent && typesWithIntent.includes(tool.type)
+        ? tool.inputSchema.extend({
+            intent: z
+                .string()
+                .describe("The intent of the call, for example the test step description plan idea"),
+        })
+        : tool.inputSchema;
+    const readOnly = tool.type === "readOnly" || tool.type === "assertion";
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: zodToJsonSchema(inputSchema, {
+            strictUnions: true,
+        }),
+        annotations: {
+            title: tool.title,
+            readOnlyHint: readOnly,
+            destructiveHint: !readOnly,
+            openWorldHint: true,
+        },
+    };
+}
+export function defineToolSchema(tool) {
+    return tool;
+}

package/lib/mcp/transport.js

@@ -0,0 +1,188 @@
+/**
+ * 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 { pipe } from "@fxts/core";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest, isJSONRPCRequest, LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/sdk/types.js";
+import contentType from "content-type";
+import crypto from "crypto";
+import debug from "debug";
+import getRawBody from "raw-body";
+import { httpAddressToString, startHttpServer } from "../utils/httpServer.js";
+import * as mcpServer from "./server.js";
+// @see node_modules/@modelcontextprotocol/sdk/dist/esm/server/streamableHttp.js
+const MAXIMUM_MESSAGE_SIZE = "4mb";
+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 handleStreamableReinitiate(req, res, transport, serverBackendFactory, sessionId, serverInfos) {
+    const ct = req.headers["content-type"];
+    if (!ct || !ct.includes("application/json")) {
+        res.writeHead(415).end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Unsupported Media Type: Content-Type must be application/json",
+            },
+            id: null,
+        }));
+        return;
+    }
+    const parsedCt = contentType.parse(ct);
+    const encoding = parsedCt.parameters.charset;
+    const body = await pipe(getRawBody(req, {
+        limit: MAXIMUM_MESSAGE_SIZE,
+        encoding,
+    }), (raw) => raw.toString(), JSON.parse);
+    const msg = Array.isArray(body)
+        ? body.length === 1
+            ? body[0]
+            : undefined
+        : body;
+    if (body && isJSONRPCRequest(msg) && isInitializeRequest(msg)) {
+        const requestedVersion = msg.params.protocolVersion;
+        const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.includes(requestedVersion)
+            ? requestedVersion
+            : LATEST_PROTOCOL_VERSION;
+        const headers = {
+            "Content-Type": "text/event-stream",
+            "Mcp-Session-Id": transport.sessionId,
+        };
+        res.writeHead(200, headers);
+        const info = serverInfos.get(sessionId) ||
+            (() => {
+                const backend = serverBackendFactory();
+                return { name: backend.name, version: backend.version };
+            })();
+        const response = {
+            jsonrpc: "2.0",
+            id: msg.id,
+            result: {
+                protocolVersion,
+                capabilities: { tools: {} },
+                serverInfo: info,
+            },
+        };
+        res.write(`event: message\n`);
+        res.write(`data: ${JSON.stringify(response)}\n\n`);
+        res.end();
+        return;
+    }
+    return await transport.handleRequest(req, res, body);
+}
+async function handleSSE(serverBackendFactory, req, res, url, sessions) {
+    if (req.method === "POST") {
+        const sessionId = url.searchParams.get("sessionId");
+        if (!sessionId) {
+            res.statusCode = 400;
+            return res.end("Missing sessionId");
+        }
+        const transport = sessions.get(sessionId);
+        if (!transport) {
+            res.statusCode = 404;
+            return res.end("Session not found");
+        }
+        return await transport.handlePostMessage(req, res);
+    }
+    else if (req.method === "GET") {
+        const transport = new SSEServerTransport("/sse", res);
+        sessions.set(transport.sessionId, transport);
+        testDebug(`create SSE session: ${transport.sessionId}`);
+        await mcpServer.connect(serverBackendFactory, transport, false);
+        res.on("close", () => {
+            testDebug(`delete SSE session: ${transport.sessionId}`);
+            sessions.delete(transport.sessionId);
+        });
+        return;
+    }
+    res.statusCode = 405;
+    res.end("Method not allowed");
+}
+// Streamable transport: 'initialize' handling per MCP Lifecycle (Initialization) https://modelcontextprotocol.io/specification/draft/basic/lifecycle#initialization
+async function handleStreamable(serverBackendFactory, req, res, sessions, serverInfos) {
+    const sessionId = req.headers["mcp-session-id"];
+    if (sessionId) {
+        const transport = sessions.get(sessionId);
+        if (!transport) {
+            res.statusCode = 404;
+            res.end("Session not found");
+            return;
+        }
+        if (req.method === "POST")
+            return await handleStreamableReinitiate(req, res, transport, serverBackendFactory, sessionId, serverInfos);
+        return await transport.handleRequest(req, res);
+    }
+    if (req.method === "POST") {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+            onsessioninitialized: async (sessionId) => {
+                testDebug(`create http session: ${transport.sessionId}`);
+                const serverInfo = await mcpServer.connect(serverBackendFactory, transport, false);
+                sessions.set(sessionId, transport);
+                serverInfos.set(sessionId, serverInfo);
+            },
+        });
+        transport.onclose = () => {
+            if (!transport.sessionId)
+                return;
+            sessions.delete(transport.sessionId);
+            serverInfos.delete(transport.sessionId);
+            testDebug(`delete http session: ${transport.sessionId}`);
+        };
+        await transport.handleRequest(req, res);
+        return;
+    }
+    res.statusCode = 400;
+    res.end("Invalid request");
+}
+function startHttpTransport(httpServer, serverBackendFactory) {
+    const sseSessions = new Map();
+    const streamableSessions = new Map();
+    const streamableServerInfos = new Map();
+    httpServer.on("request", async (req, res) => {
+        const url = new URL(`http://localhost${req.url}`);
+        if (url.pathname.startsWith("/sse"))
+            await handleSSE(serverBackendFactory, req, res, url, sseSessions);
+        else
+            await handleStreamable(serverBackendFactory, req, res, streamableSessions, streamableServerInfos);
+    });
+    const url = httpAddressToString(httpServer.address());
+    const message = [
+        `Listening on ${url}`,
+        "Put this in your client config:",
+        JSON.stringify({
+            mcpServers: {
+                playwright: {
+                    url: `${url}/mcp`,
+                },
+            },
+        }, undefined, 2),
+        "For legacy SSE transport support, you can use the /sse endpoint instead.",
+    ].join("\n");
+    // eslint-disable-next-line no-console
+    console.error(message);
+}