@wordbricks/playwright-mcp 0.1.3

package/lib/tools/snapshot.js

@@ -0,0 +1,139 @@
+/**
+ * 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, defineTool } from './tool.js';
+import * as javascript from '../utils/codegen.js';
+import { generateLocator } from './utils.js';
+const snapshot = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_snapshot',
+        title: 'Page snapshot',
+        description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        await context.ensureTab();
+        response.setIncludeSnapshot();
+    },
+});
+export const elementSchema = z.object({
+    element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
+    ref: z.string().describe('Exact target element reference from the page snapshot'),
+});
+const clickSchema = elementSchema.extend({
+    doubleClick: z.boolean().optional().describe('Whether to perform a double click instead of a single click'),
+    button: z.enum(['left', 'right', 'middle']).optional().describe('Button to click, defaults to left'),
+});
+const click = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_click',
+        title: 'Click',
+        description: 'Perform click on a web page',
+        inputSchema: clickSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        const button = params.button;
+        const buttonAttr = button ? `{ button: '${button}' }` : '';
+        if (params.doubleClick)
+            response.addCode(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
+        else
+            response.addCode(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
+        await tab.waitForCompletion(async () => {
+            if (params.doubleClick)
+                await locator.dblclick({ button });
+            else
+                await locator.click({ button });
+        });
+    },
+});
+const drag = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_drag',
+        title: 'Drag mouse',
+        description: 'Perform drag and drop between two elements',
+        inputSchema: z.object({
+            startElement: z.string().describe('Human-readable source element description used to obtain the permission to interact with the element'),
+            startRef: z.string().describe('Exact source element reference from the page snapshot'),
+            endElement: z.string().describe('Human-readable target element description used to obtain the permission to interact with the element'),
+            endRef: z.string().describe('Exact target element reference from the page snapshot'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const [startLocator, endLocator] = await tab.refLocators([
+            { ref: params.startRef, element: params.startElement },
+            { ref: params.endRef, element: params.endElement },
+        ]);
+        await tab.waitForCompletion(async () => {
+            await startLocator.dragTo(endLocator);
+        });
+        response.addCode(`await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`);
+    },
+});
+const hover = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_hover',
+        title: 'Hover mouse',
+        description: 'Hover over element on page',
+        inputSchema: elementSchema,
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        response.addCode(`await page.${await generateLocator(locator)}.hover();`);
+        await tab.waitForCompletion(async () => {
+            await locator.hover();
+        });
+    },
+});
+const selectOptionSchema = elementSchema.extend({
+    values: z.array(z.string()).describe('Array of values to select in the dropdown. This can be a single value or multiple values.'),
+});
+const selectOption = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_select_option',
+        title: 'Select option',
+        description: 'Select an option in a dropdown',
+        inputSchema: selectOptionSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
+        response.addCode(`await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`);
+        await tab.waitForCompletion(async () => {
+            await locator.selectOption(params.values);
+        });
+    },
+});
+export default [
+    snapshot,
+    click,
+    drag,
+    hover,
+    selectOption,
+];

package/lib/tools/tabs.js

@@ -0,0 +1,87 @@
+/**
+ * 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 { defineTool } from './tool.js';
+const listTabs = defineTool({
+    capability: 'core-tabs',
+    schema: {
+        name: 'browser_tab_list',
+        title: 'List tabs',
+        description: 'List browser tabs',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        await context.ensureTab();
+        response.setIncludeTabs();
+    },
+});
+const selectTab = defineTool({
+    capability: 'core-tabs',
+    schema: {
+        name: 'browser_tab_select',
+        title: 'Select a tab',
+        description: 'Select a tab by index',
+        inputSchema: z.object({
+            index: z.number().describe('The index of the tab to select'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        await context.selectTab(params.index);
+        response.setIncludeSnapshot();
+    },
+});
+const newTab = defineTool({
+    capability: 'core-tabs',
+    schema: {
+        name: 'browser_tab_new',
+        title: 'Open a new tab',
+        description: 'Open a new tab',
+        inputSchema: z.object({
+            url: z.string().optional().describe('The URL to navigate to in the new tab. If not provided, the new tab will be blank.'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        const tab = await context.newTab();
+        if (params.url)
+            await tab.navigate(params.url);
+        response.setIncludeSnapshot();
+    },
+});
+const closeTab = defineTool({
+    capability: 'core-tabs',
+    schema: {
+        name: 'browser_tab_close',
+        title: 'Close a tab',
+        description: 'Close a tab',
+        inputSchema: z.object({
+            index: z.number().optional().describe('The index of the tab to close. Closes current tab if not provided.'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params, response) => {
+        await context.closeTab(params.index);
+        response.setIncludeSnapshot();
+    },
+});
+export default [
+    listTabs,
+    newTab,
+    selectTab,
+    closeTab,
+];

package/lib/tools/tool.js

@@ -0,0 +1,33 @@
+/**
+ * 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 function defineTool(tool) {
+    return tool;
+}
+export function defineTabTool(tool) {
+    return {
+        ...tool,
+        handle: async (context, params, response) => {
+            const tab = context.currentTabOrDie();
+            const modalStates = tab.modalStates().map(state => state.type);
+            if (tool.clearsModalState && !modalStates.includes(tool.clearsModalState))
+                response.addError(`Error: The tool "${tool.schema.name}" can only be used when there is related modal state present.\n` + tab.modalStatesMarkdown().join('\n'));
+            else if (!tool.clearsModalState && modalStates.length)
+                response.addError(`Error: Tool "${tool.schema.name}" does not handle the modal state.\n` + tab.modalStatesMarkdown().join('\n'));
+            else
+                return tool.handle(tab, params, response);
+        },
+    };
+}

package/lib/tools/utils.js

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+// @ts-ignore
+import { asLocator } from 'playwright-core/lib/utils';
+export async function waitForCompletion(tab, callback) {
+    const requests = new Set();
+    let frameNavigated = false;
+    let waitCallback = () => { };
+    const waitBarrier = new Promise(f => { waitCallback = f; });
+    const requestListener = (request) => requests.add(request);
+    const requestFinishedListener = (request) => {
+        requests.delete(request);
+        if (!requests.size)
+            waitCallback();
+    };
+    const frameNavigateListener = (frame) => {
+        if (frame.parentFrame())
+            return;
+        frameNavigated = true;
+        dispose();
+        clearTimeout(timeout);
+        void tab.waitForLoadState('load').then(waitCallback);
+    };
+    const onTimeout = () => {
+        dispose();
+        waitCallback();
+    };
+    tab.page.on('request', requestListener);
+    tab.page.on('requestfinished', requestFinishedListener);
+    tab.page.on('framenavigated', frameNavigateListener);
+    const timeout = setTimeout(onTimeout, 10000);
+    const dispose = () => {
+        tab.page.off('request', requestListener);
+        tab.page.off('requestfinished', requestFinishedListener);
+        tab.page.off('framenavigated', frameNavigateListener);
+        clearTimeout(timeout);
+    };
+    try {
+        const result = await callback();
+        if (!requests.size && !frameNavigated)
+            waitCallback();
+        await waitBarrier;
+        await tab.waitForTimeout(1000);
+        return result;
+    }
+    finally {
+        dispose();
+    }
+}
+export async function generateLocator(locator) {
+    try {
+        const { resolvedSelector } = await locator._resolveSelector();
+        return asLocator('javascript', resolvedSelector);
+    }
+    catch (e) {
+        throw new Error('Ref not found, likely because element was removed. Use browser_get_snapshot to see what elements are currently on the page.');
+    }
+}
+export async function callOnPageNoTrace(page, callback) {
+    return await page._wrapApiCall(() => callback(page), { internal: true });
+}

package/lib/tools/wait.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { defineTool } from './tool.js';
+const wait = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_wait_for',
+        title: 'Wait for',
+        description: 'Wait for text to appear or disappear or a specified time to pass',
+        inputSchema: z.object({
+            time: z.number().optional().describe('The time to wait in seconds'),
+            text: z.string().optional().describe('The text to wait for'),
+            textGone: z.string().optional().describe('The text to wait for to disappear'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        if (!params.text && !params.textGone && !params.time)
+            throw new Error('Either time, text or textGone must be provided');
+        if (params.time) {
+            response.addCode(`await new Promise(f => setTimeout(f, ${params.time} * 1000));`);
+            await new Promise(f => setTimeout(f, Math.min(30000, params.time * 1000)));
+        }
+        const tab = context.currentTabOrDie();
+        const locator = params.text ? tab.page.getByText(params.text).first() : undefined;
+        const goneLocator = params.textGone ? tab.page.getByText(params.textGone).first() : undefined;
+        if (goneLocator) {
+            response.addCode(`await page.getByText(${JSON.stringify(params.textGone)}).first().waitFor({ state: 'hidden' });`);
+            await goneLocator.waitFor({ state: 'hidden' });
+        }
+        if (locator) {
+            response.addCode(`await page.getByText(${JSON.stringify(params.text)}).first().waitFor({ state: 'visible' });`);
+            await locator.waitFor({ state: 'visible' });
+        }
+        response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+        response.setIncludeSnapshot();
+    },
+});
+export default [
+    wait,
+];

package/lib/tools.js

@@ -0,0 +1,67 @@
+/**
+ * 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 common from './tools/common.js';
+import console from './tools/console.js';
+// import dialogs from './tools/dialogs.js';
+// import files from './tools/files.js';
+// import install from './tools/install.js';
+import keyboard from './tools/keyboard.js';
+import navigate from './tools/navigate.js';
+import network from './tools/network.js';
+import networkSearch from './tools/networkSearch.js';
+import networkDetail from './tools/networkDetail.js';
+// import pdf from './tools/pdf.js';
+import snapshot from './tools/snapshot.js';
+// import tabs from './tools/tabs.js';
+// import screenshot from './tools/screenshot.js';
+// import wait from './tools/wait.js';
+// import javascript from './tools/javascript.js';
+import evaluate from './tools/evaluate.js';
+import getVisibleHtml from './tools/getVisibleHtml.js';
+import getSnapshot from './tools/getSnapshot.js';
+import repl from './tools/repl.js';
+import extractFrameworkState from './tools/extractFrameworkState.js';
+import scroll from './tools/scroll.js';
+import { toolNameSchema } from './hooks/schema.js';
+export const allTools = [
+    ...common,
+    ...console,
+    // ...dialogs(true),
+    // ...files(true),
+    // ...install,
+    ...keyboard,
+    ...navigate,
+    ...network,
+    ...networkSearch,
+    ...networkDetail,
+    // ...pdf,
+    // ...screenshot,
+    ...snapshot,
+    // ...javascript,
+    ...evaluate,
+    // ...tabs(true),
+    // ...testing,
+    // ...wait,
+    ...getVisibleHtml,
+    ...getSnapshot,
+    ...repl,
+    ...extractFrameworkState,
+    ...scroll,
+];
+export function filteredTools(config) {
+    return allTools.filter(tool => (tool.capability.startsWith('core') || config.capabilities?.includes(tool.capability)) &&
+        toolNameSchema.safeParse(tool.schema.name).success);
+}

package/lib/utils/codegen.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+// adapted from:
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/utils/isomorphic/stringUtils.ts
+// - https://github.com/microsoft/playwright/blob/76ee48dc9d4034536e3ec5b2c7ce8be3b79418a8/packages/playwright-core/src/server/codegen/javascript.ts
+// NOTE: this function should not be used to escape any selectors.
+export function escapeWithQuotes(text, char = '\'') {
+    const stringified = JSON.stringify(text);
+    const escapedText = stringified.substring(1, stringified.length - 1).replace(/\\"/g, '"');
+    if (char === '\'')
+        return char + escapedText.replace(/[']/g, '\\\'') + char;
+    if (char === '"')
+        return char + escapedText.replace(/["]/g, '\\"') + char;
+    if (char === '`')
+        return char + escapedText.replace(/[`]/g, '\\`') + char;
+    throw new Error('Invalid escape char');
+}
+export function quote(text) {
+    return escapeWithQuotes(text, '\'');
+}
+export function formatObject(value, indent = '  ') {
+    if (typeof value === 'string')
+        return quote(value);
+    if (Array.isArray(value))
+        return `[${value.map(o => formatObject(o)).join(', ')}]`;
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+        if (!keys.length)
+            return '{}';
+        const tokens = [];
+        for (const key of keys)
+            tokens.push(`${key}: ${formatObject(value[key])}`);
+        return `{\n${indent}${tokens.join(`,\n${indent}`)}\n}`;
+    }
+    return String(value);
+}

package/lib/utils/extensionPath.js

@@ -0,0 +1,6 @@
+import { dirname, resolve } from 'node:path';
+import { findUpSync } from 'find-up';
+const lockFile = findUpSync(['bun.lock', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'], { cwd: process.cwd() });
+if (!lockFile)
+    throw new Error('Could not find project root (no lock file found)');
+export const extensionPath = resolve(dirname(lockFile), 'src/extensions/uBlockOriginLite');

package/lib/utils/fileUtils.js

@@ -0,0 +1,36 @@
+/**
+ * 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 os from 'node:os';
+import path from 'node:path';
+export function cacheDir() {
+    let cacheDirectory;
+    if (process.platform === 'linux')
+        cacheDirectory = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    else if (process.platform === 'darwin')
+        cacheDirectory = path.join(os.homedir(), 'Library', 'Caches');
+    else if (process.platform === 'win32')
+        cacheDirectory = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    else
+        throw new Error('Unsupported platform: ' + process.platform);
+    return path.join(cacheDirectory, 'ms-playwright');
+}
+export function sanitizeForFilePath(s) {
+    const sanitize = (s) => s.replace(/[\x00-\x2C\x2E-\x2F\x3A-\x40\x5B-\x60\x7B-\x7F]+/g, '-');
+    const separator = s.lastIndexOf('.');
+    if (separator === -1)
+        return sanitize(s);
+    return sanitize(s.substring(0, separator)) + '.' + sanitize(s.substring(separator + 1));
+}