@wordbricks/playwright-mcp 0.1.24 → 0.1.26

package/lib/tools/dialogs.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { defineTabTool } from "./tool.js";
+export const handleDialog = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_handle_dialog",
+        title: "Handle a dialog",
+        description: "Handle a dialog",
+        inputSchema: z.object({
+            accept: z.boolean().describe("Whether to accept the dialog."),
+            promptText: z
+                .string()
+                .optional()
+                .describe("The text of the prompt in case of a prompt dialog."),
+        }),
+        type: "action",
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const dialogState = tab
+            .modalStates()
+            .find((state) => state.type === "dialog");
+        if (!dialogState)
+            throw new Error("No dialog visible");
+        tab.clearModalState(dialogState);
+        await tab.waitForCompletion(async () => {
+            if (params.accept)
+                await dialogState.dialog.accept(params.promptText);
+            else
+                await dialogState.dialog.dismiss();
+        });
+    },
+    clearsModalState: "dialog",
+});
+export default [handleDialog];

package/lib/tools/evaluate.js

@@ -0,0 +1,62 @@
+/**
+ * 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 * as javascript from "../utils/codegen.js";
+import { defineTabTool } from "./tool.js";
+import { generateLocator } from "./utils.js";
+const evaluateSchema = z.object({
+    function: z
+        .string()
+        .describe("() => { /* code */ } or (element) => { /* code */ } when element is provided"),
+    element: z
+        .string()
+        .optional()
+        .describe("Human-readable element description used to obtain permission to interact with the element"),
+    ref: z
+        .string()
+        .optional()
+        .describe("Exact target element reference from the page snapshot"),
+});
+const evaluate = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_evaluate",
+        title: "Evaluate JavaScript",
+        description: "Evaluate JavaScript expression on page or element",
+        inputSchema: evaluateSchema,
+        type: "action",
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        let locator;
+        if (params.ref && params.element) {
+            locator = await tab.refLocator({
+                ref: params.ref,
+                element: params.element,
+            });
+            response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+        }
+        else {
+            response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
+        }
+        await tab.waitForCompletion(async () => {
+            const receiver = locator ?? tab.page;
+            const result = await receiver._evaluateFunction(params.function);
+            response.addResult(JSON.stringify(result, null, 2) || "undefined");
+        });
+    },
+});
+export default [evaluate];

package/lib/tools/extractFrameworkState.js

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import { FRAMEWORK_STATE_PATTERNS, MAX_DISPLAY_ITEMS, } from "../frameworkPatterns.js";
+import { truncate } from "../utils/truncate.js";
+import { defineTabTool } from "./tool.js";
+const extractFrameworkStateSchema = z.object({
+    framework: z
+        .string()
+        .optional()
+        .describe('Optional: specific key to extract from (e.g., "__remixContext")'),
+    path: z
+        .string()
+        .optional()
+        .describe('Path to extract (e.g., "state.loaderData")'),
+});
+const extractFrameworkState = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_extract_framework_state",
+        title: "Extract framework state",
+        description: "Extract framework state data from web pages (React, Redux, Remix, etc.)",
+        inputSchema: extractFrameworkStateSchema,
+        type: "readOnly",
+    },
+    handle: async (tab, params, response) => {
+        const { framework, // Optional: specific key to extract from
+        path, // Path to extract
+         } = params;
+        const result = await tab.page.evaluate(({ targetKey, targetPath, patterns }) => {
+            const foundStates = [];
+            const errors = [];
+            // If specific key requested, only check that one
+            const keysToCheck = targetKey ? [targetKey] : patterns;
+            // Check each pattern
+            for (const key of keysToCheck) {
+                if (key in window) {
+                    try {
+                        let data = window[key];
+                        // If data is string, try to parse as JSON
+                        if (typeof data === "string") {
+                            try {
+                                data = JSON.parse(data);
+                            }
+                            catch (parseErr) {
+                                throw new Error(`Failed to parse string as JSON: ${parseErr.message}`);
+                            }
+                        }
+                        // Apply path if provided
+                        if (targetPath && data) {
+                            // Split path while respecting bracket-quoted segments like ['a.b']
+                            const splitPath = (p) => {
+                                const parts = [];
+                                let cur = "";
+                                let inBracket = false;
+                                let inQuote = null;
+                                for (let i = 0; i < p.length; i++) {
+                                    const ch = p[i];
+                                    if (inQuote) {
+                                        cur += ch;
+                                        if (ch === inQuote && p[i - 1] !== "\\")
+                                            inQuote = null;
+                                        continue;
+                                    }
+                                    if (inBracket) {
+                                        cur += ch;
+                                        if (ch === '"' || ch === "'") {
+                                            inQuote = ch;
+                                        }
+                                        else if (ch === "]") {
+                                            inBracket = false;
+                                            parts.push(cur);
+                                            cur = "";
+                                        }
+                                        continue;
+                                    }
+                                    if (ch === ".") {
+                                        if (cur) {
+                                            parts.push(cur);
+                                            cur = "";
+                                        }
+                                        continue;
+                                    }
+                                    if (ch === "[") {
+                                        if (cur) {
+                                            parts.push(cur);
+                                            cur = "";
+                                        }
+                                        cur = "[";
+                                        inBracket = true;
+                                        continue;
+                                    }
+                                    cur += ch;
+                                }
+                                if (cur)
+                                    parts.push(cur);
+                                return parts;
+                            };
+                            const pathParts = splitPath(targetPath);
+                            for (const part of pathParts) {
+                                if (data && typeof data === "object") {
+                                    // Handle array index with prop: prop[123]
+                                    const arrayMatch = part.match(/^(.+)\[(\d+)\]$/);
+                                    if (arrayMatch) {
+                                        const prop = arrayMatch[1];
+                                        const index = Number.parseInt(arrayMatch[2], 10);
+                                        const propData = data[prop];
+                                        data = Array.isArray(propData)
+                                            ? propData[index]
+                                            : undefined;
+                                    }
+                                    else if (part.match(/^\[(\d+)\]$/)) {
+                                        // Handle standalone array index: [123]
+                                        const indexMatch = part.match(/^\[(\d+)\]$/);
+                                        if (indexMatch) {
+                                            const index = Number.parseInt(indexMatch[1], 10);
+                                            data = data?.[index];
+                                        }
+                                    }
+                                    else {
+                                        // Handle quoted key: ['key.with.dot'] or ["key.with.dot"]
+                                        const bracketMatch = part.match(/^\[['"]([^'"]+)['"]\]$/);
+                                        if (bracketMatch)
+                                            data = data[bracketMatch[1]];
+                                        else
+                                            data = data[part];
+                                    }
+                                }
+                                else {
+                                    data = undefined;
+                                    break;
+                                }
+                            }
+                        }
+                        if (data !== undefined) {
+                            foundStates.push({
+                                key: key,
+                                data: data,
+                            });
+                        }
+                    }
+                    catch (e) {
+                        errors.push(`${key}: ${e instanceof Error ? e.message : String(e)}`);
+                    }
+                }
+            }
+            return {
+                count: foundStates.length,
+                states: foundStates,
+                errors: errors.length > 0 ? errors : undefined,
+            };
+        }, {
+            targetKey: framework,
+            targetPath: path,
+            patterns: FRAMEWORK_STATE_PATTERNS,
+        });
+        // Extract data from results
+        if (result.states.length === 0) {
+            if (framework) {
+                if (path) {
+                    throw new Error(`Path "${path}" not found in framework state '${framework}'.`);
+                }
+                throw new Error(`Key '${framework}' not found in window. ` +
+                    "Available framework states can be detected by the frameworkStateHook.");
+            }
+            throw new Error("No framework state found. " +
+                "Available framework states can be detected by the frameworkStateHook.");
+        }
+        // Prepare final data
+        let finalData;
+        const extractedKeys = result.states.map((s) => s.key);
+        if (result.states.length === 1) {
+            finalData = result.states[0].data;
+        }
+        else {
+            finalData = {};
+            for (const state of result.states)
+                finalData[state.key] = state.data;
+        }
+        // Limit to MAX_DISPLAY_ITEMS for display if array
+        const totalItems = Array.isArray(finalData)
+            ? finalData.length
+            : typeof finalData === "object" && finalData !== null
+                ? Object.keys(finalData).length
+                : 1;
+        let displayData = finalData;
+        let isTruncated = false;
+        if (Array.isArray(finalData) && finalData.length > MAX_DISPLAY_ITEMS) {
+            displayData = finalData.slice(0, MAX_DISPLAY_ITEMS);
+            isTruncated = true;
+        }
+        else if (typeof finalData === "object" &&
+            finalData !== null &&
+            !Array.isArray(finalData)) {
+            const keys = Object.keys(finalData);
+            if (keys.length > MAX_DISPLAY_ITEMS) {
+                displayData = {};
+                keys.slice(0, MAX_DISPLAY_ITEMS).forEach((key) => {
+                    displayData[key] = finalData[key];
+                });
+                isTruncated = true;
+            }
+        }
+        // Truncate for readability and cap output
+        const truncatedDisplay = truncate(displayData, {
+            maxStringLength: 1000,
+            maxItems: MAX_DISPLAY_ITEMS,
+        });
+        const outputStr = JSON.stringify(truncatedDisplay, null, 2);
+        const summary = [
+            `Found ${result.count} framework state(s)`,
+            result.states.length > 1
+                ? `Extracted from: ${extractedKeys.join(", ")}`
+                : `Using: ${result.states[0]?.key}`,
+            isTruncated
+                ? `Showing first ${MAX_DISPLAY_ITEMS} of ${totalItems} results`
+                : null,
+            path ? `Extracted path: ${path}` : null,
+            result.errors ? `Errors: ${result.errors.join("; ")}` : null,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        response.addResult(summary + "\n\n" + outputStr);
+        response.setIncludeSnapshot();
+    },
+});
+export default [extractFrameworkState];

package/lib/tools/files.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { defineTabTool } from "./tool.js";
+export const uploadFile = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_file_upload",
+        title: "Upload files",
+        description: "Upload one or multiple files",
+        inputSchema: z.object({
+            paths: z
+                .array(z.string())
+                .optional()
+                .describe("The absolute paths to the files to upload. Can be single file or multiple files. If omitted, file chooser is cancelled."),
+        }),
+        type: "action",
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const modalState = tab
+            .modalStates()
+            .find((state) => state.type === "fileChooser");
+        if (!modalState)
+            throw new Error("No file chooser visible");
+        response.addCode(`await fileChooser.setFiles(${JSON.stringify(params.paths)})`);
+        tab.clearModalState(modalState);
+        await tab.waitForCompletion(async () => {
+            if (params.paths)
+                await modalState.fileChooser.setFiles(params.paths);
+        });
+    },
+    clearsModalState: "fileChooser",
+});
+export default [uploadFile];

package/lib/tools/form.js

@@ -0,0 +1,66 @@
+/**
+ * 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 * as codegen from "../utils/codegen.js";
+import { defineTabTool } from "./tool.js";
+import { generateLocator } from "./utils.js";
+const fillForm = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_fill_form",
+        title: "Fill form",
+        description: "Fill multiple form fields",
+        inputSchema: z.object({
+            fields: z
+                .array(z.object({
+                name: z.string().describe("Human-readable field name"),
+                type: z
+                    .enum(["textbox", "checkbox", "radio", "combobox", "slider"])
+                    .describe("Type of the field"),
+                ref: z
+                    .string()
+                    .describe("Exact target field reference from the page snapshot"),
+                value: z
+                    .string()
+                    .describe("Value to fill in the field. If the field is a checkbox, the value should be `true` or `false`. If the field is a combobox, the value should be the text of the option."),
+            }))
+                .describe("Fields to fill in"),
+        }),
+        type: "input",
+    },
+    handle: async (tab, params, response) => {
+        for (const field of params.fields) {
+            const locator = await tab.refLocator({
+                element: field.name,
+                ref: field.ref,
+            });
+            if (field.type === "textbox" || field.type === "slider") {
+                const secret = tab.context.lookupSecret(field.value);
+                await locator.fill(secret.value);
+                response.addCode(`await page.${await generateLocator(locator)}.fill(${secret.code});`);
+            }
+            else if (field.type === "checkbox" || field.type === "radio") {
+                await locator.setChecked(field.value === "true");
+                response.addCode(`await page.${await generateLocator(locator)}.setChecked(${field.value});`);
+            }
+            else if (field.type === "combobox") {
+                await locator.selectOption({ label: field.value });
+                response.addCode(`await page.${await generateLocator(locator)}.selectOption(${codegen.quote(field.value)});`);
+            }
+        }
+    },
+});
+export default [fillForm];

package/lib/tools/getSnapshot.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { truncate } from "../utils/truncate.js";
+import { defineTool } from "./tool.js";
+const MAX_LENGTH = 100_000;
+const getSnapshotSchema = z.object({});
+const getSnapshot = defineTool({
+    capability: "core",
+    schema: {
+        name: "browser_get_snapshot",
+        title: "Get snapshot",
+        description: "Get accessibility snapshot of the current page",
+        inputSchema: getSnapshotSchema,
+        type: "readOnly",
+    },
+    handle: async (context, _params, response) => {
+        const tab = await context.ensureTab();
+        try {
+            const snapshot = await tab.captureSnapshot();
+            const lines = [];
+            lines.push(`### Page state`);
+            lines.push(`- Page URL: ${snapshot.url}`);
+            lines.push(`- Page Title: ${snapshot.title}`);
+            lines.push(`- Page Snapshot:`);
+            lines.push("```yaml");
+            let aria = snapshot.ariaSnapshot || "";
+            aria = String(truncate(aria, { maxStringLength: MAX_LENGTH }));
+            lines.push(aria);
+            lines.push("```");
+            response.addResult(lines.join("\n"));
+        }
+        catch (error) {
+            response.addResult(`Failed to get snapshot: ${String(error)}`);
+        }
+    },
+});
+export default [getSnapshot];

package/lib/tools/getVisibleHtml.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { sanitizeHtml } from "../utils/sanitizeHtml.js";
+import { defineTool } from "./tool.js";
+const getVisibleHtmlSchema = z.object({
+    selector: z
+        .string()
+        .optional()
+        .describe("CSS selector for a specific element (optional)"),
+    cleanHtml: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Clean HTML (true) or raw HTML (false)"),
+    removeScripts: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Remove scripts (true) or keep them (false)"),
+    removeStyles: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Remove styles (true) or keep them (false)"),
+});
+const getVisibleHtml = defineTool({
+    capability: "core",
+    schema: {
+        name: "browser_get_visible_html",
+        title: "Get visible HTML",
+        description: "Get HTML content of the page or a specific element",
+        inputSchema: getVisibleHtmlSchema,
+        type: "readOnly",
+    },
+    handle: async (context, params, response) => {
+        const tab = await context.ensureTab();
+        const page = tab.page;
+        try {
+            const { selector, cleanHtml, removeScripts, removeStyles } = params;
+            // Get the HTML content
+            let htmlContent;
+            if (selector) {
+                // If a selector is provided, get only the HTML for that element
+                const element = await page.$(selector);
+                if (!element)
+                    throw new Error(`Element with selector "${selector}" not found`);
+                htmlContent = await page.evaluate((el) => el.outerHTML, element);
+            }
+            else {
+                // Otherwise get the full page HTML
+                htmlContent = await page.content();
+            }
+            // Determine if we need to apply filters
+            const shouldRemoveScripts = removeScripts || cleanHtml;
+            const shouldRemoveStyles = removeStyles || cleanHtml;
+            // Apply filters server-side to avoid TrustedHTML/Trusted Types restrictions in page context
+            if (shouldRemoveScripts || shouldRemoveStyles)
+                htmlContent = sanitizeHtml(htmlContent, {
+                    shouldRemoveScripts,
+                    shouldRemoveStyles,
+                });
+            response.addResult(`HTML content:\n${htmlContent}`);
+        }
+        catch (error) {
+            response.addResult(`Failed to get visible HTML content: ${error.message}`);
+        }
+    },
+});
+export default [getVisibleHtml];

package/lib/tools/install.js

@@ -0,0 +1,51 @@
+/**
+ * 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 { fork } from "child_process";
+import path from "path";
+import { z } from "zod";
+import { defineTool } from "./tool.js";
+const install = defineTool({
+    capability: "core-install",
+    schema: {
+        name: "browser_install",
+        title: "Install the browser specified in the config",
+        description: "Install the browser specified in the config. Call this if you get an error about the browser not being installed.",
+        inputSchema: z.object({}),
+        type: "action",
+    },
+    handle: async (context, params, response) => {
+        const channel = context.config.browser?.launchOptions?.channel ??
+            context.config.browser?.browserName ??
+            "chrome";
+        const cliPath = path.join(require.resolve("playwright/package.json"), "../cli.js");
+        const child = fork(cliPath, ["install", channel], {
+            stdio: "pipe",
+        });
+        const output = [];
+        child.stdout?.on("data", (data) => output.push(data.toString()));
+        child.stderr?.on("data", (data) => output.push(data.toString()));
+        await new Promise((resolve, reject) => {
+            child.on("close", (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`Failed to install browser: ${output.join("")}`));
+            });
+        });
+        response.setIncludeTabs();
+    },
+});
+export default [install];