@playwright/mcp 0.0.36 → 0.0.37-alpha-2025-09-08

package/lib/tools/mouse.js

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

package/lib/tools/navigate.js

@@ -1,54 +0,0 @@
-/**
- * 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, defineTabTool } from './tool.js';
-const navigate = defineTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_navigate',
-        title: 'Navigate to a URL',
-        description: 'Navigate to a URL',
-        inputSchema: z.object({
-            url: z.string().describe('The URL to navigate to'),
-        }),
-        type: 'destructive',
-    },
-    handle: async (context, params, response) => {
-        const tab = await context.ensureTab();
-        await tab.navigate(params.url);
-        response.setIncludeSnapshot();
-        response.addCode(`await page.goto('${params.url}');`);
-    },
-});
-const goBack = defineTabTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_navigate_back',
-        title: 'Go back',
-        description: 'Go back to the previous page',
-        inputSchema: z.object({}),
-        type: 'readOnly',
-    },
-    handle: async (tab, params, response) => {
-        await tab.page.goBack();
-        response.setIncludeSnapshot();
-        response.addCode(`await page.goBack();`);
-    },
-});
-export default [
-    navigate,
-    goBack,
-];

package/lib/tools/network.js

@@ -1,41 +0,0 @@
-/**
- * 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 requests = defineTabTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_network_requests',
-        title: 'List network requests',
-        description: 'Returns all network requests since loading the page',
-        inputSchema: z.object({}),
-        type: 'readOnly',
-    },
-    handle: async (tab, params, response) => {
-        const requests = tab.requests();
-        [...requests.entries()].forEach(([req, res]) => response.addResult(renderRequest(req, res)));
-    },
-});
-function renderRequest(request, response) {
-    const result = [];
-    result.push(`[${request.method().toUpperCase()}] ${request.url()}`);
-    if (response)
-        result.push(`=> [${response.status()}] ${response.statusText()}`);
-    return result.join(' ');
-}
-export default [
-    requests,
-];

package/lib/tools/pdf.js

@@ -1,40 +0,0 @@
-/**
- * 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';
-const pdfSchema = z.object({
-    filename: z.string().optional().describe('File name to save the pdf to. Defaults to `page-{timestamp}.pdf` if not specified.'),
-});
-const pdf = defineTabTool({
-    capability: 'pdf',
-    schema: {
-        name: 'browser_pdf_save',
-        title: 'Save as PDF',
-        description: 'Save page as PDF',
-        inputSchema: pdfSchema,
-        type: 'readOnly',
-    },
-    handle: async (tab, params, response) => {
-        const fileName = await tab.context.outputFile(params.filename ?? `page-${new Date().toISOString()}.pdf`);
-        response.addCode(`await page.pdf(${javascript.formatObject({ path: fileName })});`);
-        response.addResult(`Saved page as ${fileName}`);
-        await tab.page.pdf({ path: fileName });
-    },
-});
-export default [
-    pdf,
-];

package/lib/tools/screenshot.js

@@ -1,79 +0,0 @@
-/**
- * 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 screenshotSchema = z.object({
-    type: z.enum(['png', 'jpeg']).default('png').describe('Image format for the screenshot. Default is png.'),
-    filename: z.string().optional().describe('File name to save the screenshot to. Defaults to `page-{timestamp}.{png|jpeg}` if not specified.'),
-    element: z.string().optional().describe('Human-readable element description used to obtain permission to screenshot the element. If not provided, the screenshot will be taken of viewport. If element is provided, ref must be provided too.'),
-    ref: z.string().optional().describe('Exact target element reference from the page snapshot. If not provided, the screenshot will be taken of viewport. If ref is provided, element must be provided too.'),
-    fullPage: z.boolean().optional().describe('When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Cannot be used with element screenshots.'),
-}).refine(data => {
-    return !!data.element === !!data.ref;
-}, {
-    message: 'Both element and ref must be provided or neither.',
-    path: ['ref', 'element']
-}).refine(data => {
-    return !(data.fullPage && (data.element || data.ref));
-}, {
-    message: 'fullPage cannot be used with element screenshots.',
-    path: ['fullPage']
-});
-const screenshot = defineTabTool({
-    capability: 'core',
-    schema: {
-        name: 'browser_take_screenshot',
-        title: 'Take a screenshot',
-        description: `Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.`,
-        inputSchema: screenshotSchema,
-        type: 'readOnly',
-    },
-    handle: async (tab, params, response) => {
-        const fileType = params.type || 'png';
-        const fileName = await tab.context.outputFile(params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
-        const options = {
-            type: fileType,
-            quality: fileType === 'png' ? undefined : 90,
-            scale: 'css',
-            path: fileName,
-            ...(params.fullPage !== undefined && { fullPage: params.fullPage })
-        };
-        const isElementScreenshot = params.element && params.ref;
-        const screenshotTarget = isElementScreenshot ? params.element : (params.fullPage ? 'full page' : 'viewport');
-        response.addCode(`// Screenshot ${screenshotTarget} and save it as ${fileName}`);
-        // Only get snapshot when element screenshot is needed
-        const locator = params.ref ? await tab.refLocator({ element: params.element || '', ref: params.ref }) : null;
-        if (locator)
-            response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
-        else
-            response.addCode(`await page.screenshot(${javascript.formatObject(options)});`);
-        const buffer = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
-        response.addResult(`Took the ${screenshotTarget} screenshot and saved it as ${fileName}`);
-        // https://github.com/microsoft/playwright-mcp/issues/817
-        // Never return large images to LLM, saving them to the file system is enough.
-        if (!params.fullPage) {
-            response.addImage({
-                contentType: fileType === 'png' ? 'image/png' : 'image/jpeg',
-                data: buffer
-            });
-        }
-    }
-});
-export default [
-    screenshot,
-];

package/lib/tools/snapshot.js

@@ -1,139 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-/**
- * 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 browserTabs = defineTool({
-    capability: 'core-tabs',
-    schema: {
-        name: 'browser_tabs',
-        title: 'Manage tabs',
-        description: 'List, create, close, or select a browser tab.',
-        inputSchema: z.object({
-            action: z.enum(['list', 'new', 'close', 'select']).describe('Operation to perform'),
-            index: z.number().optional().describe('Tab index, used for close/select. If omitted for close, current tab is closed.'),
-        }),
-        type: 'destructive',
-    },
-    handle: async (context, params, response) => {
-        switch (params.action) {
-            case 'list': {
-                await context.ensureTab();
-                response.setIncludeTabs();
-                return;
-            }
-            case 'new': {
-                await context.newTab();
-                response.setIncludeTabs();
-                return;
-            }
-            case 'close': {
-                await context.closeTab(params.index);
-                response.setIncludeSnapshot();
-                return;
-            }
-            case 'select': {
-                if (params.index === undefined)
-                    throw new Error('Tab index is required');
-                await context.selectTab(params.index);
-                response.setIncludeSnapshot();
-                return;
-            }
-        }
-    },
-});
-export default [
-    browserTabs,
-];

package/lib/tools/tool.js

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,74 +0,0 @@
-/**
- * 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_snapshot to see what elements are currently on the page.');
-    }
-}
-export async function callOnPageNoTrace(page, callback) {
-    return await page._wrapApiCall(() => callback(page), { internal: true });
-}