@ejazullah/browser-mcp 0.0.56

package/lib/tools/interactions.js

@@ -0,0 +1,191 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+import { elementSchema } from './snapshot.js';
+import { generateLocator } from './utils.js';
+// Scroll to element or position
+const scrollTo = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_scroll_to',
+        title: 'Scroll to element or position',
+        description: 'Scroll to a specific element or coordinate position',
+        inputSchema: z.object({
+            element: z.string().optional().describe('Human-readable element description (if scrolling to element)'),
+            ref: z.string().optional().describe('Element reference (if scrolling to element)'),
+            x: z.number().optional().describe('X coordinate to scroll to (if scrolling to position)'),
+            y: z.number().optional().describe('Y coordinate to scroll to (if scrolling to position)'),
+            behavior: z.enum(['auto', 'smooth']).optional().default('auto').describe('Scroll behavior'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            if (params.element && params.ref) {
+                // Scroll to element
+                const locator = await tab.refLocator({ element: params.element, ref: params.ref });
+                await locator.scrollIntoViewIfNeeded();
+                response.addCode(`await page.${await generateLocator(locator)}.scrollIntoViewIfNeeded();`);
+                response.addResult('Scrolled to element successfully');
+            }
+            else if (params.x !== undefined && params.y !== undefined) {
+                // Scroll to coordinates
+                await tab.page.evaluate(({ x, y, behavior }) => {
+                    window.scrollTo({ left: x, top: y, behavior });
+                }, { x: params.x, y: params.y, behavior: params.behavior });
+                response.addCode(`await page.evaluate(() => window.scrollTo({ left: ${params.x}, top: ${params.y}, behavior: '${params.behavior}' }));`);
+                response.addResult(`Scrolled to position (${params.x}, ${params.y})`);
+            }
+            else {
+                response.addError('Either provide element+ref OR x+y coordinates');
+                return;
+            }
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to scroll: ${error}`);
+        }
+    },
+});
+// Get page scroll position
+const getScrollPosition = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_get_scroll_position',
+        title: 'Get scroll position',
+        description: 'Get the current scroll position of the page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            const position = await tab.page.evaluate(() => ({
+                x: window.scrollX,
+                y: window.scrollY,
+            }));
+            response.addCode(`const position = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));`);
+            response.addResult(`Current scroll position: x=${position.x}, y=${position.y}`);
+        }
+        catch (error) {
+            response.addError(`Failed to get scroll position: ${error}`);
+        }
+    },
+});
+// Focus on element
+const focusElement = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_focus_element',
+        title: 'Focus on element',
+        description: 'Set focus on a specific element',
+        inputSchema: elementSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            const locator = await tab.refLocator(params);
+            await locator.focus();
+            response.addCode(`await page.${await generateLocator(locator)}.focus();`);
+            response.addResult('Element focused successfully');
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to focus element: ${error}`);
+        }
+    },
+});
+// Blur (remove focus from) element
+const blurElement = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_blur_element',
+        title: 'Remove focus from element',
+        description: 'Remove focus from a specific element',
+        inputSchema: elementSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            const locator = await tab.refLocator(params);
+            await locator.blur();
+            response.addCode(`await page.${await generateLocator(locator)}.blur();`);
+            response.addResult('Element blurred successfully');
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to blur element: ${error}`);
+        }
+    },
+});
+// Double click
+const doubleClick = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_double_click',
+        title: 'Double click element',
+        description: 'Perform a double click on an element',
+        inputSchema: elementSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            const locator = await tab.refLocator(params);
+            await tab.waitForCompletion(async () => {
+                await locator.dblclick();
+            });
+            response.addCode(`await page.${await generateLocator(locator)}.dblclick();`);
+            response.addResult('Double click performed successfully');
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to double click: ${error}`);
+        }
+    },
+});
+// Right click (context menu)
+const rightClick = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_right_click',
+        title: 'Right click element',
+        description: 'Perform a right click on an element to open context menu',
+        inputSchema: elementSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        try {
+            const locator = await tab.refLocator(params);
+            await tab.waitForCompletion(async () => {
+                await locator.click({ button: 'right' });
+            });
+            response.addCode(`await page.${await generateLocator(locator)}.click({ button: 'right' });`);
+            response.addResult('Right click performed successfully');
+            response.setIncludeSnapshot();
+        }
+        catch (error) {
+            response.addError(`Failed to right click: ${error}`);
+        }
+    },
+});
+export default [
+    scrollTo,
+    getScrollPosition,
+    focusElement,
+    blurElement,
+    doubleClick,
+    rightClick,
+];

package/lib/tools/keyboard.js

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+import { elementSchema } from './snapshot.js';
+import { generateLocator } from './utils.js';
+import * as javascript from '../javascript.js';
+const pressKey = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_press_key',
+        title: 'Press a key',
+        description: 'Press a key on the keyboard',
+        inputSchema: z.object({
+            key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Press ${params.key}`);
+        response.addCode(`await page.keyboard.press('${params.key}');`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.keyboard.press(params.key);
+        });
+    },
+});
+const typeSchema = elementSchema.extend({
+    text: z.string().describe('Text to type into the element'),
+    submit: z.boolean().optional().describe('Whether to submit entered text (press Enter after)'),
+    slowly: z.boolean().optional().describe('Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.'),
+});
+const type = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_type',
+        title: 'Type text',
+        description: 'Type text into editable element',
+        inputSchema: typeSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        // Get locator with selector information for database logging
+        const { locator, selector, resolvedSelector } = await tab.refLocatorWithSelector(params);
+        // Store element interaction data for database logging
+        response.setElementInteraction({
+            elementRef: params.ref,
+            elementDescription: params.element,
+            playwrightSelector: selector,
+            resolvedSelector: resolvedSelector,
+        });
+        await tab.waitForCompletion(async () => {
+            if (params.slowly) {
+                response.setIncludeSnapshot();
+                response.addCode(`await page.${await generateLocator(locator)}.pressSequentially(${javascript.quote(params.text)});`);
+                await locator.pressSequentially(params.text);
+            }
+            else {
+                response.addCode(`await page.${await generateLocator(locator)}.fill(${javascript.quote(params.text)});`);
+                await locator.fill(params.text);
+            }
+            if (params.submit) {
+                response.setIncludeSnapshot();
+                response.addCode(`await page.${await generateLocator(locator)}.press('Enter');`);
+                await locator.press('Enter');
+            }
+        });
+    },
+});
+export default [
+    pressKey,
+    type,
+];

package/lib/tools/mouse.js

@@ -0,0 +1,99 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+const elementSchema = z.object({
+    element: z.string().describe('Human-readable element description used to obtain permission to interact with the element'),
+});
+const mouseMove = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_move_xy',
+        title: 'Move mouse',
+        description: 'Move mouse to a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        response.addCode(`// Move mouse to (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+        });
+    },
+});
+const mouseClick = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_click_xy',
+        title: 'Click',
+        description: 'Click left mouse button at a given position',
+        inputSchema: elementSchema.extend({
+            x: z.number().describe('X coordinate'),
+            y: z.number().describe('Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Click mouse at coordinates (${params.x}, ${params.y})`);
+        response.addCode(`await page.mouse.move(${params.x}, ${params.y});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.x, params.y);
+            await tab.page.mouse.down();
+            await tab.page.mouse.up();
+        });
+    },
+});
+const mouseDrag = defineTabTool({
+    capability: 'vision',
+    schema: {
+        name: 'browser_mouse_drag_xy',
+        title: 'Drag mouse',
+        description: 'Drag left mouse button to a given position',
+        inputSchema: elementSchema.extend({
+            startX: z.number().describe('Start X coordinate'),
+            startY: z.number().describe('Start Y coordinate'),
+            endX: z.number().describe('End X coordinate'),
+            endY: z.number().describe('End Y coordinate'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        response.addCode(`// Drag mouse from (${params.startX}, ${params.startY}) to (${params.endX}, ${params.endY})`);
+        response.addCode(`await page.mouse.move(${params.startX}, ${params.startY});`);
+        response.addCode(`await page.mouse.down();`);
+        response.addCode(`await page.mouse.move(${params.endX}, ${params.endY});`);
+        response.addCode(`await page.mouse.up();`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.mouse.move(params.startX, params.startY);
+            await tab.page.mouse.down();
+            await tab.page.mouse.move(params.endX, params.endY);
+            await tab.page.mouse.up();
+        });
+    },
+});
+export default [
+    mouseMove,
+    mouseClick,
+    mouseDrag,
+];

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 '../javascript.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

@@ -0,0 +1,75 @@
+/**
+ * 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 '../javascript.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}`);
+        response.addImage({
+            contentType: fileType === 'png' ? 'image/png' : 'image/jpeg',
+            data: buffer
+        });
+    }
+});
+export default [
+    screenshot,
+];