@wordbricks/playwright-mcp 0.1.3

package/lib/tools/evaluate.js

@@ -0,0 +1,53 @@
+/**
+ * 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';
+import * as javascript from '../utils/codegen.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: 'destructive',
+    },
+    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,214 @@
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+import { FRAMEWORK_STATE_PATTERNS, MAX_DISPLAY_ITEMS } from '../frameworkPatterns.js';
+import { truncate } from '../utils/truncate.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 = 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 = 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,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 { defineTabTool } from './tool.js';
+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()).describe('The absolute paths to the files to upload. Can be a single file or multiple files.'),
+        }),
+        type: 'destructive',
+    },
+    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 () => {
+            await modalState.fileChooser.setFiles(params.paths);
+        });
+    },
+    clearsModalState: 'fileChooser',
+});
+export default [
+    uploadFile,
+];

package/lib/tools/getSnapshot.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+import { truncate } from '../utils/truncate.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,52 @@
+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,53 @@
+/**
+ * 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 { fileURLToPath } from 'url';
+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: 'destructive',
+    },
+    handle: async (context, params, response) => {
+        const channel = context.config.browser?.launchOptions?.channel ?? context.config.browser?.browserName ?? 'chrome';
+        const cliUrl = import.meta.resolve('playwright/package.json');
+        const cliPath = path.join(fileURLToPath(cliUrl), '..', '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,
+];

package/lib/tools/keyboard.js

@@ -0,0 +1,78 @@
+/**
+ * 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';
+import { elementSchema } from './snapshot.js';
+import { generateLocator } from './utils.js';
+import * as javascript from '../utils/codegen.js';
+const pressKey = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_press_key',
+        title: 'Press a key',
+        description: 'Press a key on the keyboard',
+        inputSchema: z.object({
+            key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Press ${params.key}`);
+        response.addCode(`await page.keyboard.press('${params.key}');`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.keyboard.press(params.key);
+        });
+    },
+});
+const typeSchema = elementSchema.extend({
+    text: z.string().describe('Text to type into the element'),
+    submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
+    slowly: z.boolean().optional().describe('Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'),
+});
+const type = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_type',
+        title: 'Type text',
+        description: 'Type text into editable element',
+        inputSchema: typeSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        const locator = await tab.refLocator(params);
+        await tab.waitForCompletion(async () => {
+            if (params.slowly) {
+                response.setIncludeSnapshot();
+                response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
+                await locator.pressSequentially(params.text);
+            }
+            else {
+                response.addCode(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
+                await locator.fill(params.text);
+            }
+            if (params.submit) {
+                response.setIncludeSnapshot();
+                response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+                await locator.press('Enter');
+            }
+        });
+    },
+});
+export default [
+    pressKey,
+    type,
+];

package/lib/tools/mouse.js

@@ -0,0 +1,99 @@
+/**
+ * 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';
+const elementSchema = z.object({
+    element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
+});
+const mouseMove = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_move_xy',
+        title: 'Move mouse',
+        description: 'Move mouse to a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        response.addCode(`// Move mouse to (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+        });
+    },
+});
+const mouseClick = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_click_xy',
+        title: 'Click',
+        description: 'Click left mouse button at a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Click mouse at coordinates (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+            await tab.page.mouse.down();
+            await tab.page.mouse.up();
+        });
+    },
+});
+const mouseDrag = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_drag_xy',
+        title: 'Drag mouse',
+        description: 'Drag left mouse button to a given position',
+        inputSchema: elementSchema.extend({
+            startX: z.number().describe('Start X coordinate'),
+            startY: z.number().describe('Start Y coordinate'),
+            endX: z.number().describe('End X coordinate'),
+            endY: z.number().describe('End Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`);
+        response.addCode(`await page.mouse.move(${params.startX}, ${params.startY});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.move(${params.endX}, ${params.endY});`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.startX, params.startY);
+            await tab.page.mouse.down();
+            await tab.page.mouse.move(params.endX, params.endY);
+            await tab.page.mouse.up();
+        });
+    },
+});
+export default [
+    mouseMove,
+    mouseClick,
+    mouseDrag,
+];