@wordbricks/playwright-mcp 0.1.25 → 0.1.27

package/lib/hooks/pageHeightHook.js

@@ -0,0 +1,75 @@
+import { Err, Ok } from "../utils/result.js";
+import { trackEvent } from "./events.js";
+import { hookNameSchema } from "./schema.js";
+const pageHeightStateMap = new WeakMap();
+const capturePageHeight = async (ctx) => {
+    const tab = ctx.tab || ctx.context.currentTab();
+    if (!tab)
+        return undefined;
+    try {
+        return await tab.page.evaluate(() => ({
+            pageHeight: document.documentElement.scrollHeight,
+            scrollY: window.scrollY,
+        }));
+    }
+    catch {
+        return undefined;
+    }
+};
+const pageHeightPreHook = {
+    name: hookNameSchema.enum["page-height-pre"],
+    handler: async (ctx) => {
+        try {
+            const initialState = await capturePageHeight(ctx);
+            if (!initialState)
+                return Ok(undefined);
+            // Store initial state for post-hook (keyed by Context)
+            pageHeightStateMap.set(ctx.context, initialState);
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+const pageHeightPostHook = {
+    name: hookNameSchema.enum["page-height-post"],
+    handler: async (ctx) => {
+        try {
+            const initialState = pageHeightStateMap.get(ctx.context);
+            if (!initialState)
+                return Ok(undefined);
+            const finalState = await capturePageHeight(ctx);
+            if (!finalState)
+                return Ok(undefined);
+            const heightChange = finalState.pageHeight - initialState.pageHeight;
+            const tab = ctx.tab || ctx.context.currentTab();
+            const url = tab ? tab.page.url() : "unknown";
+            trackEvent(ctx.context, {
+                type: "page-height-change",
+                data: {
+                    previousHeight: initialState.pageHeight,
+                    currentHeight: finalState.pageHeight,
+                    heightChange: heightChange,
+                    scrollY: finalState.scrollY,
+                    url: url,
+                },
+                timestamp: Date.now(),
+            });
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+export const pageHeightHooks = {
+    pre: pageHeightPreHook,
+    post: pageHeightPostHook,
+};
+export const formatPageHeightEvent = (event) => {
+    const { previousHeight, currentHeight, heightChange } = event.data;
+    if (heightChange === 0)
+        return `Page height unchanged.`;
+    return `Page height changed: ${previousHeight}px → ${currentHeight}px (${heightChange > 0 ? "+" : ""}${heightChange}px)`;
+};

package/lib/hooks/registry.js

@@ -0,0 +1,41 @@
+import { pipe, reduce, values } from "@fxts/core";
+import { antiBotDetectionHooks } from "./antiBotDetectionHook.js";
+import { createHookRegistry, setToolHooks } from "./core.js";
+import { frameworkStateHooks } from "./frameworkStateHook.js";
+import { registerGroupingRule } from "./grouping.js";
+import { jsonLdDetectionHooks } from "./jsonLdDetectionHook.js";
+import { networkGroupingRule, networkTrackingHooks, } from "./networkTrackingHook.js";
+import { pageHeightHooks } from "./pageHeightHook.js";
+import { requireTabHooks } from "./requireTabHook.js";
+import { toolNameSchema } from "./schema.js";
+import { waitHooks } from "./waitHook.js";
+const COMMON_HOOKS = {
+    preHooks: [
+        requireTabHooks.pre,
+        networkTrackingHooks.pre,
+        antiBotDetectionHooks.pre,
+        pageHeightHooks.pre,
+        frameworkStateHooks.pre,
+        jsonLdDetectionHooks.pre,
+    ],
+    postHooks: [
+        networkTrackingHooks.post,
+        antiBotDetectionHooks.post,
+        frameworkStateHooks.post,
+        jsonLdDetectionHooks.post,
+        pageHeightHooks.post,
+        waitHooks.post,
+    ],
+};
+const toolHooksConfig = [
+// Example hook registration
+// {
+//   toolName: toolNameSchema.enum.browser_click,
+//   preHooks: [],
+//   postHooks: [],
+// },
+];
+export const buildHookRegistry = () => {
+    registerGroupingRule("network-request", networkGroupingRule);
+    return pipe(createHookRegistry(), (registry) => reduce((acc, toolName) => setToolHooks(acc, { toolName, ...COMMON_HOOKS }), registry, values(toolNameSchema.enum)), (registry) => reduce(setToolHooks, registry, toolHooksConfig));
+};

package/lib/hooks/requireTabHook.js

@@ -0,0 +1,26 @@
+import { Err, Ok } from "../utils/result.js";
+import { hookNameSchema, toolNameSchema } from "./schema.js";
+const MESSAGE = 'No open tabs. Use the "browser_navigate" tool to navigate to a page first.';
+const requireTabPreHook = {
+    name: hookNameSchema.enum["require-tab-pre"],
+    handler: async (ctx) => {
+        try {
+            // Allow navigate tool to create/open a tab
+            if (ctx.toolName === toolNameSchema.enum.browser_navigate)
+                return Ok(undefined);
+            // If no current tab, emit a standardized error and stop execution
+            if (!ctx.context.currentTab()) {
+                // Include tabs section in response so the message is rendered consistently
+                ctx.response.setIncludeTabs();
+                return Err(new Error(MESSAGE));
+            }
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+export const requireTabHooks = {
+    pre: requireTabPreHook,
+};

package/lib/hooks/schema.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export const hookNameSchema = z.enum([
+    "network-tracking-pre",
+    "network-tracking-post",
+    "page-height-pre",
+    "page-height-post",
+    "wait-post",
+    "framework-state-pre",
+    "framework-state-post",
+    "json-ld-detection-pre",
+    "json-ld-detection-post",
+    "require-tab-pre",
+    "anti-bot-detection-pre",
+    "anti-bot-detection-post",
+]);
+// Tool names enum - should match actual tool names in
+export const toolNameSchema = z.enum([
+    "browser_click",
+    "browser_extract_framework_state",
+    "browser_fill_form",
+    "browser_get_snapshot",
+    // 'browser_get_visible_html',
+    "browser_navigate",
+    // 'browser_navigate_back',
+    // 'browser_navigate_forward',
+    "browser_network_detail",
+    "browser_network_search",
+    "browser_press_key",
+    "browser_reload",
+    "browser_repl",
+    "browser_scroll",
+    "browser_type",
+    "browser_wait",
+]);
+export const EventTypeSchema = z.enum([
+    "network-request",
+    "page-height-change",
+    "wait",
+    "tool-call",
+    "framework-state",
+    "json-ld",
+    "anti-bot",
+]);
+export const NetworkRequestEventDataSchema = z.object({
+    method: z.string(),
+    url: z.string(),
+    status: z.number(),
+    resourceType: z.string(),
+    postData: z.string().optional(),
+    setCookies: z.array(z.string()).optional(),
+    responseSize: z.number().optional(),
+});
+export const PageHeightChangeEventDataSchema = z.object({
+    previousHeight: z.number(),
+    currentHeight: z.number(),
+    heightChange: z.number(),
+    scrollY: z.number(),
+    url: z.string(),
+});
+export const WaitEventDataSchema = z.object({
+    duration: z.number(),
+});
+export const ToolCallEventDataSchema = z.object({
+    toolName: z.string(),
+    params: z.record(z.unknown()).optional(),
+    executionTime: z.number().optional(),
+    success: z.boolean().optional(),
+});
+export const FrameworkStateEventDataSchema = z.object({
+    state: z.record(z.any()),
+    changes: z.array(z.string()).optional(),
+    action: z.enum(["detected", "changed"]),
+});
+export const JsonLdEventDataSchema = z.object({
+    state: z.record(z.object({
+        count: z.number(),
+        indices: z.array(z.number()),
+    })),
+    changes: z.array(z.string()).optional(),
+    action: z.enum(["detected", "changed"]),
+});
+export const AntiBotEventDataSchema = z.object({
+    provider: z.enum(["cloudflare-turnstile", "aws-waf"]),
+    detectionMethod: z.literal("network-request"),
+    url: z.string(),
+    status: z.number(),
+    action: z.enum(["detected", "resolved", "still-blocked"]),
+    waitMs: z.number().optional(),
+});

package/lib/hooks/waitHook.js

@@ -0,0 +1,33 @@
+import ms from "ms";
+import { Err, Ok } from "../utils/result.js";
+import { trackEvent } from "./events.js";
+import { hookNameSchema } from "./schema.js";
+export const WAIT_TIME_STR = "0.5s";
+export const WAIT_TIME_MS = ms(WAIT_TIME_STR);
+const waitPostHook = {
+    name: hookNameSchema.enum["wait-post"],
+    handler: async (ctx) => {
+        try {
+            const tab = ctx.tab || ctx.context.currentTab();
+            if (!tab)
+                return Ok(undefined);
+            const startTime = Date.now();
+            await tab.page.waitForTimeout(WAIT_TIME_MS);
+            trackEvent(ctx.context, {
+                type: "wait",
+                data: {
+                    duration: WAIT_TIME_MS,
+                },
+                timestamp: startTime,
+            });
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+export const waitHooks = {
+    post: waitPostHook,
+};
+export const formatWaitEvent = (event) => `Waited ${event.data.duration}ms`;

package/lib/index.js

@@ -0,0 +1,41 @@
+/**
+ * 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 { contextFactory } from "./browserContextFactory.js";
+import { BrowserServerBackend } from "./browserServerBackend.js";
+import { resolveConfig } from "./config.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);
+    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;
+    }
+    async createContext() {
+        const browserContext = await this._contextGetter();
+        return {
+            browserContext,
+            close: () => browserContext.close(),
+        };
+    }
+}

package/lib/mcp/inProcessTransport.js

@@ -0,0 +1,71 @@
+/**
+ * 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/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;
+}