@wordbricks/playwright-mcp 0.1.24 → 0.1.26

package/lib/hooks/networkFilters.js

@@ -0,0 +1,82 @@
+const MEANINGFUL_RESOURCE_TYPES = ["document", "xhr", "fetch"];
+const ALLOWED_METHODS = ["GET", "POST"];
+const EXCLUDED_EXTENSIONS = [
+    ".svg",
+    ".css",
+    ".map", // JS files and source maps
+];
+const hasExcludedExtension = (url) => {
+    return EXCLUDED_EXTENSIONS.some((ext) => {
+        const extRegex = new RegExp(`${ext.replace(".", "\\.")}(\\?|#|$)`, "i");
+        return extRegex.test(url);
+    });
+};
+export const isAntiBotUrl = (url) => {
+    if (url.includes("challenges.cloudflare.com"))
+        return true;
+    if (url.includes(".awswaf.com"))
+        return true;
+    return false;
+};
+const isSuccessfulStatus = (status) => {
+    // Status 0 is for failed requests, which we want to capture
+    // 2xx status codes are successful
+    // Exclude 204 No Content
+    return status === 0 || (status >= 200 && status < 300 && status !== 204);
+};
+export const shouldCaptureRequest = (method, url, status, resourceType) => {
+    if (isAntiBotUrl(url))
+        return true;
+    return (!hasExcludedExtension(url) &&
+        MEANINGFUL_RESOURCE_TYPES.includes(resourceType) &&
+        ALLOWED_METHODS.includes(method) &&
+        isSuccessfulStatus(status));
+};
+/**
+ * Format URL with trimmed parameters
+ */
+export const formatUrlWithTrimmedParams = (url) => {
+    try {
+        const urlObj = new URL(url);
+        const params = urlObj.searchParams;
+        if (params.toString()) {
+            const trimmedParams = new URLSearchParams();
+            params.forEach((value, key) => {
+                if (value.length > 5)
+                    trimmedParams.set(key, value.substring(0, 5) + "...");
+                else
+                    trimmedParams.set(key, value);
+            });
+            return `${urlObj.origin}${urlObj.pathname}?${trimmedParams.toString()}`;
+        }
+        return url;
+    }
+    catch {
+        // If URL parsing fails, return as is
+        return url;
+    }
+};
+/**
+ * Normalize a pathname by removing trailing slashes (except root)
+ */
+export const normalizePathname = (pathname) => {
+    if (!pathname)
+        return "/";
+    if (pathname === "/")
+        return "/";
+    return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+};
+/**
+ * Normalize URL for grouping by ignoring query/hash and trailing slash
+ */
+export const normalizeUrlForGrouping = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${normalizePathname(u.pathname)}`;
+    }
+    catch {
+        // Fallback for non-standard/relative URLs: strip query/hash and trailing slash
+        const base = url.split(/[?#]/)[0] || "/";
+        return normalizePathname(base);
+    }
+};

package/lib/hooks/networkSetup.js

@@ -0,0 +1,61 @@
+import { trackEvent } from "./events.js";
+import { shouldCaptureRequest } from "./networkFilters.js";
+const eventIdToEntryMap = new WeakMap();
+const getEventIdMap = (context) => {
+    let map = eventIdToEntryMap.get(context);
+    if (!map) {
+        map = new Map();
+        eventIdToEntryMap.set(context, map);
+    }
+    return map;
+};
+export const getNetworkEventEntry = (context, id) => getEventIdMap(context).get(id);
+export const setupNetworkTracking = (context, page) => {
+    page.on("response", async (response) => {
+        const request = response.request();
+        const method = request.method();
+        const url = request.url();
+        const status = response.status();
+        const resourceType = request.resourceType();
+        // Apply filters before saving the event
+        if (shouldCaptureRequest(method, url, status, resourceType)) {
+            const setCookies = await response
+                .headerValues("set-cookie")
+                .catch(() => []);
+            const cookieValues = setCookies.length ? setCookies : undefined;
+            const networkData = {
+                method,
+                url,
+                status,
+                resourceType,
+                postData: request.postData() || undefined,
+                setCookies: cookieValues,
+            };
+            const id = trackEvent(context, {
+                type: "network-request",
+                data: networkData,
+            });
+            getEventIdMap(context).set(id, { request, response });
+        }
+    });
+    page.on("requestfailed", (request) => {
+        const method = request.method();
+        const url = request.url();
+        const status = 0; // Failed requests have status 0
+        const resourceType = request.resourceType();
+        if (shouldCaptureRequest(method, url, status, resourceType)) {
+            const networkData = {
+                method,
+                url,
+                status,
+                resourceType,
+                postData: request.postData() || undefined,
+            };
+            const id = trackEvent(context, {
+                type: "network-request",
+                data: networkData,
+            });
+            getEventIdMap(context).set(id, { request });
+        }
+    });
+};

package/lib/hooks/networkTrackingHook.js

@@ -0,0 +1,67 @@
+import { filter, pipe, toArray } from "@fxts/core";
+import { parseGraphQLRequestFromHttp } from "../utils/graphql.js";
+import { formatNetworkSummaryLine } from "../utils/networkFormat.js";
+import { Ok } from "../utils/result.js";
+import { getEventStore, isEventType } from "./events.js";
+import { defineGroupingRule } from "./grouping.js";
+import { normalizeUrlForGrouping } from "./networkFilters.js";
+import { hookNameSchema } from "./schema.js";
+const networkTrackingPreHook = {
+    name: hookNameSchema.enum["network-tracking-pre"],
+    handler: async (_ctx) => {
+        // Pre-hook now just acts as a marker, event consumption happens elsewhere
+        return Ok(undefined);
+    },
+};
+const networkTrackingPostHook = {
+    name: hookNameSchema.enum["network-tracking-post"],
+    handler: async (_ctx) => {
+        // Post-hook now just acts as a marker, network event collection happens automatically
+        return Ok(undefined);
+    },
+};
+export const networkTrackingHooks = {
+    pre: networkTrackingPreHook,
+    post: networkTrackingPostHook,
+};
+export const formatNetworkEvent = (event) => {
+    const { method, url, status, postData, setCookies } = event.data;
+    const summary = formatNetworkSummaryLine({ method, url, status, postData });
+    if (!setCookies || setCookies.length === 0)
+        return summary;
+    const names = setCookies
+        .map((cookie) => {
+        const firstPart = cookie.split(";", 1)[0];
+        const [name] = firstPart.split("=", 1);
+        return name?.trim();
+    })
+        .filter((name) => !!name);
+    if (!names.length)
+        return summary;
+    return `${summary} | Set-Cookie keys: ${names.join(", ")}`;
+};
+const computeNetworkGroupKey = (event) => {
+    const method = (event.data.method || "").toUpperCase();
+    const baseUrl = normalizeUrlForGrouping(event.data.url);
+    const gql = parseGraphQLRequestFromHttp(event.data.method, event.data.url, {}, event.data.postData);
+    if (gql) {
+        const type = gql.operationType === "unknown" ? "operation" : gql.operationType;
+        const op = gql.operationName ? `${type} ${gql.operationName}` : type;
+        return `${method} ${baseUrl} [GraphQL: ${op}]`;
+    }
+    return `${method} ${baseUrl}`;
+};
+export const networkGroupingRule = defineGroupingRule({
+    match: (e) => e.type === "network-request",
+    keyOf: (e) => computeNetworkGroupKey(e),
+    summaryOf: (first, run) => {
+        const key = computeNetworkGroupKey(first);
+        const count = run.length;
+        const firstStatus = first.data.status;
+        const allSameStatus = run.every((e) => e.data.status === firstStatus);
+        return allSameStatus
+            ? `${key} → ${firstStatus} (x${count})`
+            : `${key} (x${count})`;
+    },
+});
+export const listNetworkEvents = (context) => pipe(context, getEventStore, (store) => store.events.values(), filter(isEventType("network-request")), toArray);

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);
+    }
+}