@roxybrowser/playwright-mcp 0.0.1

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,
+];

package/lib/tools/navigate.js

@@ -0,0 +1,70 @@
+/**
+ * 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();`);
+    },
+});
+const goForward = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_navigate_forward',
+        title: 'Go forward',
+        description: 'Go forward to the next page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        await tab.page.goForward();
+        response.setIncludeSnapshot();
+        response.addCode(`await page.goForward();`);
+    },
+});
+export default [
+    navigate,
+    goBack,
+    goForward,
+];

package/lib/tools/network.js

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

@@ -0,0 +1,40 @@
+/**
+ * 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/roxy.js

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTool } from './tool.js';
+const roxyConnect = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_connect_roxy',
+        title: 'Connect to RoxyBrowser',
+        description: 'Connect to RoxyBrowser using CDP WebSocket endpoint',
+        inputSchema: z.object({
+            cdpEndpoint: z.string().describe('The CDP WebSocket endpoint URL from RoxyBrowser (e.g., ws://127.0.0.1:59305/devtools/browser/4d876b0b-6adc-4e9f-b572-bb68ff02a199)'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params, response) => {
+        try {
+            // Validate CDP endpoint format
+            if (!params.cdpEndpoint.startsWith('ws://') && !params.cdpEndpoint.startsWith('wss://'))
+                throw new Error(`Invalid CDP endpoint format. Expected WebSocket URL starting with ws:// or wss://, got: ${params.cdpEndpoint}`);
+            // Use the reconnectToCDP method to connect to RoxyBrowser
+            await context.reconnectToCDP(params.cdpEndpoint);
+            // Verify connection by ensuring we have tabs or can create one
+            await context.ensureTab();
+            response.addResult(`Successfully connected to RoxyBrowser at ${params.cdpEndpoint}`);
+            response.addCode(`// Connected to RoxyBrowser CDP endpoint: ${params.cdpEndpoint}`);
+            // Take a snapshot to show current state
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to connect to RoxyBrowser: ${error.message}`);
+        }
+    },
+});
+export default [
+    roxyConnect,
+];

package/lib/tools/screenshot.js

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

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