@playwright/mcp 0.0.31 → 0.0.33

package/lib/tools/mouse.js

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+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 = defineTool({
+const mouseMove = defineTabTool({
     capability: 'vision',
     schema: {
         name: 'browser_mouse_move_xy',
@@ -30,22 +30,15 @@ const mouseMove = defineTool({
         }),
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [
-            `// Move mouse to (${params.x}, ${params.y})`,
-            `await page.mouse.move(${params.x}, ${params.y});`,
-        ];
-        const action = () => tab.page.mouse.move(params.x, params.y);
-        return {
-            code,
-            action,
-            captureSnapshot: false,
-            waitForNetwork: false
-        };
+    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 = defineTool({
+const mouseClick = defineTabTool({
     capability: 'vision',
     schema: {
         name: 'browser_mouse_click_xy',
@@ -57,28 +50,20 @@ const mouseClick = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [
-            `// Click mouse at coordinates (${params.x}, ${params.y})`,
-            `await page.mouse.move(${params.x}, ${params.y});`,
-            `await page.mouse.down();`,
-            `await page.mouse.up();`,
-        ];
-        const action = async () => {
+    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();
-        };
-        return {
-            code,
-            action,
-            captureSnapshot: false,
-            waitForNetwork: true,
-        };
+        });
     },
 });
-const mouseDrag = defineTool({
+const mouseDrag = defineTabTool({
     capability: 'vision',
     schema: {
         name: 'browser_mouse_drag_xy',
@@ -92,27 +77,19 @@ const mouseDrag = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const code = [
-            `// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`,
-            `await page.mouse.move(${params.startX}, ${params.startY});`,
-            `await page.mouse.down();`,
-            `await page.mouse.move(${params.endX}, ${params.endY});`,
-            `await page.mouse.up();`,
-        ];
-        const action = async () => {
+    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();
-        };
-        return {
-            code,
-            action,
-            captureSnapshot: false,
-            waitForNetwork: true,
-        };
+        });
     },
 });
 export default [

package/lib/tools/navigate.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTool, defineTabTool } from './tool.js';
 const navigate = defineTool({
     capability: 'core',
     schema: {
@@ -26,21 +26,14 @@ const navigate = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
+    handle: async (context, params, response) => {
         const tab = await context.ensureTab();
         await tab.navigate(params.url);
-        const code = [
-            `// Navigate to ${params.url}`,
-            `await page.goto('${params.url}');`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`await page.goto('${params.url}');`);
     },
 });
-const goBack = defineTool({
+const goBack = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_navigate_back',
@@ -49,21 +42,13 @@ const goBack = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const tab = await context.ensureTab();
+    handle: async (tab, params, response) => {
         await tab.page.goBack();
-        const code = [
-            `// Navigate back`,
-            `await page.goBack();`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`await page.goBack();`);
     },
 });
-const goForward = defineTool({
+const goForward = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_navigate_forward',
@@ -72,18 +57,10 @@ const goForward = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const tab = context.currentTabOrDie();
+    handle: async (tab, params, response) => {
         await tab.page.goForward();
-        const code = [
-            `// Navigate forward`,
-            `await page.goForward();`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
+        response.addCode(`await page.goForward();`);
     },
 });
 export default [

package/lib/tools/network.js

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
-const requests = defineTool({
+import { defineTabTool } from './tool.js';
+const requests = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_network_requests',
@@ -24,19 +24,9 @@ const requests = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
-        const requests = context.currentTabOrDie().requests();
-        const log = [...requests.entries()].map(([request, response]) => renderRequest(request, response)).join('\n');
-        return {
-            code: [`// <internal code to list network requests>`],
-            action: async () => {
-                return {
-                    content: [{ type: 'text', text: log }]
-                };
-            },
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    handle: async (tab, params, response) => {
+        const requests = tab.requests();
+        [...requests.entries()].forEach(([req, res]) => response.addResult(renderRequest(req, res)));
     },
 });
 function renderRequest(request, response) {

package/lib/tools/pdf.js

@@ -14,13 +14,12 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
-import { outputFile } from '../config.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 = defineTool({
+const pdf = defineTabTool({
     capability: 'pdf',
     schema: {
         name: 'browser_pdf_save',
@@ -29,19 +28,11 @@ const pdf = defineTool({
         inputSchema: pdfSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.pdf`);
-        const code = [
-            `// Save page as ${fileName}`,
-            `await page.pdf(${javascript.formatObject({ path: fileName })});`,
-        ];
-        return {
-            code,
-            action: async () => tab.page.pdf({ path: fileName }).then(() => { }),
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+    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 [

package/lib/tools/screenshot.js

@@ -14,22 +14,27 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool } from './tool.js';
 import * as javascript from '../javascript.js';
-import { outputFile } from '../config.js';
 import { generateLocator } from './utils.js';
 const screenshotSchema = z.object({
-    raw: z.boolean().optional().describe('Whether to return without compression (in PNG format). Default is false, which returns a JPEG image.'),
+    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 = defineTool({
+const screenshot = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_take_screenshot',
@@ -38,38 +43,35 @@ const screenshot = defineTool({
         inputSchema: screenshotSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const snapshot = tab.snapshotOrDie();
-        const fileType = params.raw ? 'png' : 'jpeg';
-        const fileName = await outputFile(context.config, params.filename ?? `page-${new Date().toISOString()}.${fileType}`);
-        const options = { type: fileType, quality: fileType === 'png' ? undefined : 50, scale: 'css', path: fileName };
+    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 code = [
-            `// Screenshot ${isElementScreenshot ? params.element : 'viewport'} and save it as ${fileName}`,
-        ];
-        const locator = params.ref ? snapshot.refLocator({ element: params.element || '', ref: params.ref }) : null;
+        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)
-            code.push(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
+            response.addCode(`await page.${await generateLocator(locator)}.screenshot(${javascript.formatObject(options)});`);
         else
-            code.push(`await page.screenshot(${javascript.formatObject(options)});`);
-        const includeBase64 = context.clientSupportsImages();
-        const action = async () => {
-            const screenshot = locator ? await locator.screenshot(options) : await tab.page.screenshot(options);
-            return {
-                content: includeBase64 ? [{
-                        type: 'image',
-                        data: screenshot.toString('base64'),
-                        mimeType: fileType === 'png' ? 'image/png' : 'image/jpeg',
-                    }] : []
-            };
-        };
-        return {
-            code,
-            action,
-            captureSnapshot: false,
-            waitForNetwork: false,
-        };
+            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 [

package/lib/tools/snapshot.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { defineTool } from './tool.js';
+import { defineTabTool, defineTool } from './tool.js';
 import * as javascript from '../javascript.js';
 import { generateLocator } from './utils.js';
 const snapshot = defineTool({
@@ -26,13 +26,9 @@ const snapshot = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
+    handle: async (context, params, response) => {
         await context.ensureTab();
-        return {
-            code: [`// <internal code to capture accessibility snapshot>`],
-            captureSnapshot: true,
-            waitForNetwork: false,
-        };
+        response.setIncludeSnapshot();
     },
 });
 export const elementSchema = z.object({
@@ -43,7 +39,7 @@ 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 = defineTool({
+const click = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_click',
@@ -52,29 +48,24 @@ const click = defineTool({
         inputSchema: clickSchema,
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const tab = context.currentTabOrDie();
-        const locator = tab.snapshotOrDie().refLocator(params);
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const locator = await tab.refLocator(params);
         const button = params.button;
         const buttonAttr = button ? `{ button: '${button}' }` : '';
-        const code = [];
-        if (params.doubleClick) {
-            code.push(`// Double click ${params.element}`);
-            code.push(`await page.${await generateLocator(locator)}.dblclick(${buttonAttr});`);
-        }
-        else {
-            code.push(`// Click ${params.element}`);
-            code.push(`await page.${await generateLocator(locator)}.click(${buttonAttr});`);
-        }
-        return {
-            code,
-            action: () => params.doubleClick ? locator.dblclick({ button }) : locator.click({ button }),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+        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 = defineTool({
+const drag = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_drag',
@@ -88,23 +79,19 @@ const drag = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const startLocator = snapshot.refLocator({ ref: params.startRef, element: params.startElement });
-        const endLocator = snapshot.refLocator({ ref: params.endRef, element: params.endElement });
-        const code = [
-            `// Drag ${params.startElement} to ${params.endElement}`,
-            `await page.${await generateLocator(startLocator)}.dragTo(page.${await generateLocator(endLocator)});`
-        ];
-        return {
-            code,
-            action: () => startLocator.dragTo(endLocator),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    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 = defineTool({
+const hover = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_hover',
@@ -113,25 +100,19 @@ const hover = defineTool({
         inputSchema: elementSchema,
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params);
-        const code = [
-            `// Hover over ${params.element}`,
-            `await page.${await generateLocator(locator)}.hover();`
-        ];
-        return {
-            code,
-            action: () => locator.hover(),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    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 = defineTool({
+const selectOption = defineTabTool({
     capability: 'core',
     schema: {
         name: 'browser_select_option',
@@ -140,19 +121,13 @@ const selectOption = defineTool({
         inputSchema: selectOptionSchema,
         type: 'destructive',
     },
-    handle: async (context, params) => {
-        const snapshot = context.currentTabOrDie().snapshotOrDie();
-        const locator = snapshot.refLocator(params);
-        const code = [
-            `// Select options [${params.values.join(', ')}] in ${params.element}`,
-            `await page.${await generateLocator(locator)}.selectOption(${javascript.formatObject(params.values)});`
-        ];
-        return {
-            code,
-            action: () => locator.selectOption(params.values).then(() => { }),
-            captureSnapshot: true,
-            waitForNetwork: true,
-        };
+    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 [

package/lib/tools/tabs.js

@@ -24,19 +24,9 @@ const listTabs = defineTool({
         inputSchema: z.object({}),
         type: 'readOnly',
     },
-    handle: async (context) => {
+    handle: async (context, params, response) => {
         await context.ensureTab();
-        return {
-            code: [`// <internal code to list tabs>`],
-            captureSnapshot: false,
-            waitForNetwork: false,
-            resultOverride: {
-                content: [{
-                        type: 'text',
-                        text: await context.listTabsMarkdown(),
-                    }],
-            },
-        };
+        response.setIncludeTabs();
     },
 });
 const selectTab = defineTool({
@@ -50,16 +40,9 @@ const selectTab = defineTool({
         }),
         type: 'readOnly',
     },
-    handle: async (context, params) => {
+    handle: async (context, params, response) => {
         await context.selectTab(params.index);
-        const code = [
-            `// <internal code to select tab ${params.index}>`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false
-        };
+        response.setIncludeSnapshot();
     },
 });
 const newTab = defineTool({
@@ -73,18 +56,11 @@ const newTab = defineTool({
         }),
         type: 'readOnly',
     },
-    handle: async (context, params) => {
-        await context.newTab();
+    handle: async (context, params, response) => {
+        const tab = await context.newTab();
         if (params.url)
-            await context.currentTabOrDie().navigate(params.url);
-        const code = [
-            `// <internal code to open a new tab>`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false
-        };
+            await tab.navigate(params.url);
+        response.setIncludeSnapshot();
     },
 });
 const closeTab = defineTool({
@@ -98,16 +74,9 @@ const closeTab = defineTool({
         }),
         type: 'destructive',
     },
-    handle: async (context, params) => {
+    handle: async (context, params, response) => {
         await context.closeTab(params.index);
-        const code = [
-            `// <internal code to close tab ${params.index}>`,
-        ];
-        return {
-            code,
-            captureSnapshot: true,
-            waitForNetwork: false
-        };
+        response.setIncludeSnapshot();
     },
 });
 export default [

package/lib/tools/tool.js

@@ -16,3 +16,18 @@
 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);
+        },
+    };
+}