@ejazullah/browser-mcp 0.0.56

package/lib/tab.js

@@ -0,0 +1,266 @@
+/**
+ * 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 { EventEmitter } from 'events';
+import { callOnPageNoTrace, waitForCompletion } from './tools/utils.js';
+import { logUnhandledError } from './log.js';
+import { ManualPromise } from './manualPromise.js';
+export const TabEvents = {
+    modalState: 'modalState'
+};
+export class Tab extends EventEmitter {
+    context;
+    page;
+    _lastTitle = 'about:blank';
+    _consoleMessages = [];
+    _recentConsoleMessages = [];
+    _requests = new Map();
+    _onPageClose;
+    _modalStates = [];
+    _downloads = [];
+    constructor(context, page, onPageClose) {
+        super();
+        this.context = context;
+        this.page = page;
+        this._onPageClose = onPageClose;
+        page.on('console', event => this._handleConsoleMessage(messageToConsoleMessage(event)));
+        page.on('pageerror', error => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
+        page.on('request', request => this._requests.set(request, null));
+        page.on('response', response => this._requests.set(response.request(), response));
+        page.on('close', () => this._onClose());
+        page.on('filechooser', chooser => {
+            this.setModalState({
+                type: 'fileChooser',
+                description: 'File chooser',
+                fileChooser: chooser,
+            });
+        });
+        page.on('dialog', dialog => this._dialogShown(dialog));
+        page.on('download', download => {
+            void this._downloadStarted(download);
+        });
+        page.setDefaultNavigationTimeout(60000);
+        page.setDefaultTimeout(5000);
+        page[tabSymbol] = this;
+    }
+    static forPage(page) {
+        return page[tabSymbol];
+    }
+    modalStates() {
+        return this._modalStates;
+    }
+    setModalState(modalState) {
+        this._modalStates.push(modalState);
+        this.emit(TabEvents.modalState, modalState);
+    }
+    clearModalState(modalState) {
+        this._modalStates = this._modalStates.filter(state => state !== modalState);
+    }
+    modalStatesMarkdown() {
+        return renderModalStates(this.context, this.modalStates());
+    }
+    _dialogShown(dialog) {
+        this.setModalState({
+            type: 'dialog',
+            description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+            dialog,
+        });
+    }
+    async _downloadStarted(download) {
+        const entry = {
+            download,
+            finished: false,
+            outputFile: await this.context.outputFile(download.suggestedFilename())
+        };
+        this._downloads.push(entry);
+        await download.saveAs(entry.outputFile);
+        entry.finished = true;
+    }
+    _clearCollectedArtifacts() {
+        this._consoleMessages.length = 0;
+        this._recentConsoleMessages.length = 0;
+        this._requests.clear();
+    }
+    _handleConsoleMessage(message) {
+        this._consoleMessages.push(message);
+        this._recentConsoleMessages.push(message);
+    }
+    _onClose() {
+        this._clearCollectedArtifacts();
+        this._onPageClose(this);
+    }
+    async updateTitle() {
+        await this._raceAgainstModalStates(async () => {
+            this._lastTitle = await callOnPageNoTrace(this.page, page => page.title());
+        });
+    }
+    lastTitle() {
+        return this._lastTitle;
+    }
+    isCurrentTab() {
+        return this === this.context.currentTab();
+    }
+    async waitForLoadState(state, options) {
+        await callOnPageNoTrace(this.page, page => page.waitForLoadState(state, options).catch(logUnhandledError));
+    }
+    async navigate(url) {
+        this._clearCollectedArtifacts();
+        const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(logUnhandledError));
+        try {
+            await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+        }
+        catch (_e) {
+            const e = _e;
+            const mightBeDownload = e.message.includes('net::ERR_ABORTED') // chromium
+                || e.message.includes('Download is starting'); // firefox + webkit
+            if (!mightBeDownload)
+                throw e;
+            // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
+            const download = await Promise.race([
+                downloadEvent,
+                new Promise(resolve => setTimeout(resolve, 3000)),
+            ]);
+            if (!download)
+                throw e;
+            // Make sure other "download" listeners are notified first.
+            await new Promise(resolve => setTimeout(resolve, 500));
+            return;
+        }
+        // Cap load event to 5 seconds, the page is operational at this point.
+        await this.waitForLoadState('load', { timeout: 5000 });
+    }
+    consoleMessages() {
+        return this._consoleMessages;
+    }
+    requests() {
+        return this._requests;
+    }
+    async captureSnapshot() {
+        let tabSnapshot;
+        const modalStates = await this._raceAgainstModalStates(async () => {
+            const snapshot = await this.page._snapshotForAI();
+            tabSnapshot = {
+                url: this.page.url(),
+                title: await this.page.title(),
+                ariaSnapshot: snapshot,
+                modalStates: [],
+                consoleMessages: [],
+                downloads: this._downloads,
+            };
+        });
+        if (tabSnapshot) {
+            // Assign console message late so that we did not lose any to modal state.
+            tabSnapshot.consoleMessages = this._recentConsoleMessages;
+            this._recentConsoleMessages = [];
+        }
+        return tabSnapshot ?? {
+            url: this.page.url(),
+            title: '',
+            ariaSnapshot: '',
+            modalStates,
+            consoleMessages: [],
+            downloads: [],
+        };
+    }
+    _javaScriptBlocked() {
+        return this._modalStates.some(state => state.type === 'dialog');
+    }
+    async _raceAgainstModalStates(action) {
+        if (this.modalStates().length)
+            return this.modalStates();
+        const promise = new ManualPromise();
+        const listener = (modalState) => promise.resolve([modalState]);
+        this.once(TabEvents.modalState, listener);
+        return await Promise.race([
+            action().then(() => {
+                this.off(TabEvents.modalState, listener);
+                return [];
+            }),
+            promise,
+        ]);
+    }
+    async waitForCompletion(callback) {
+        await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
+    }
+    async refLocator(params) {
+        return (await this.refLocators([params]))[0];
+    }
+    async refLocators(params) {
+        const snapshot = await this.page._snapshotForAI();
+        return params.map(param => {
+            if (!snapshot.includes(`[ref=${param.ref}]`))
+                throw new Error(`Ref ${param.ref} not found in the current page snapshot. Try capturing new snapshot.`);
+            return this.page.locator(`aria-ref=${param.ref}`).describe(param.element);
+        });
+    }
+    async refLocatorWithSelector(params) {
+        const snapshot = await this.page._snapshotForAI();
+        if (!snapshot.includes(`[ref=${params.ref}]`))
+            throw new Error(`Ref ${params.ref} not found in the current page snapshot. Try capturing new snapshot.`);
+        const locator = this.page.locator(`aria-ref=${params.ref}`).describe(params.element);
+        const selector = `aria-ref=${params.ref}`;
+        // Try to get the resolved selector (CSS/XPath)
+        let resolvedSelector;
+        try {
+            const selectorInfo = await locator._resolveSelector();
+            resolvedSelector = selectorInfo.resolvedSelector;
+        }
+        catch (e) {
+            // Ignore if we can't resolve the selector
+        }
+        return { locator, selector, resolvedSelector };
+    }
+    async waitForTimeout(time) {
+        if (this._javaScriptBlocked()) {
+            await new Promise(f => setTimeout(f, time));
+            return;
+        }
+        await callOnPageNoTrace(this.page, page => {
+            return page.evaluate(() => new Promise(f => setTimeout(f, 1000)));
+        });
+    }
+}
+function messageToConsoleMessage(message) {
+    return {
+        type: message.type(),
+        text: message.text(),
+        toString: () => `[${message.type().toUpperCase()}] ${message.text()} @ ${message.location().url}:${message.location().lineNumber}`,
+    };
+}
+function pageErrorToConsoleMessage(errorOrValue) {
+    if (errorOrValue instanceof Error) {
+        return {
+            type: undefined,
+            text: errorOrValue.message,
+            toString: () => errorOrValue.stack || errorOrValue.message,
+        };
+    }
+    return {
+        type: undefined,
+        text: String(errorOrValue),
+        toString: () => String(errorOrValue),
+    };
+}
+export function renderModalStates(context, modalStates) {
+    const result = ['### Modal state'];
+    if (modalStates.length === 0)
+        result.push('- There is no modal state present');
+    for (const state of modalStates) {
+        const tool = context.tools.filter(tool => 'clearsModalState' in tool).find(tool => tool.clearsModalState === state.type);
+        result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
+    }
+    return result;
+}
+const tabSymbol = Symbol('tabSymbol');

package/lib/tools/cdp.js

@@ -0,0 +1,169 @@
+/**
+ * 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';
+import * as playwright from 'playwright';
+import { contextFactory } from '../browserContextFactory.js';
+// Connect to a browser via CDP endpoint
+const connectCDP = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_connect_cdp',
+        title: 'Connect to browser via CDP',
+        description: 'Connect to an existing browser instance using Chrome DevTools Protocol (CDP) endpoint',
+        inputSchema: z.object({
+            endpoint: z.string().describe('CDP endpoint URL (e.g., "ws://localhost:9222" or "wss://example.com/devtools/sessionid"  or "http://localhost:9222")'),
+            timeout: z.number().optional().default(30000).describe('Connection timeout in milliseconds'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (context, params, response) => {
+        try {
+            // Ensure endpoint format - don't modify if it already has a valid scheme
+            let cdpEndpoint = params.endpoint;
+            if (!cdpEndpoint.startsWith('ws://') &&
+                !cdpEndpoint.startsWith('wss://') &&
+                !cdpEndpoint.startsWith('http://') &&
+                !cdpEndpoint.startsWith('https://')) {
+                cdpEndpoint = `ws://${cdpEndpoint}`;
+            }
+            response.addResult(`Connecting to CDP endpoint: ${cdpEndpoint}`);
+            // Connect to the browser via CDP
+            const browser = await playwright.chromium.connectOverCDP(cdpEndpoint, {
+                timeout: params.timeout,
+            });
+            // Get browser info
+            const version = browser.version();
+            const contexts = browser.contexts();
+            response.addResult(`✅ Successfully connected to browser!`);
+            response.addResult(`Browser version: ${version}`);
+            response.addResult(`Active contexts: ${contexts.length}`);
+            // Update the context configuration to use this CDP connection
+            context.config.browser.cdpEndpoint = cdpEndpoint;
+            // Switch to CDP mode by updating the browser context factory
+            const newContextFactory = contextFactory(context.config);
+            await context.updateBrowserContextFactory(newContextFactory);
+            response.addCode(`// Browser connected via CDP
+const browser = await playwright.chromium.connectOverCDP('${cdpEndpoint}');
+console.log('Connected to:', browser.version());`);
+            // List available pages/tabs
+            if (contexts.length > 0) {
+                const pages = contexts[0].pages();
+                response.addResult(`Available pages: ${pages.length}`);
+                for (let i = 0; i < Math.min(pages.length, 5); i++) {
+                    const page = pages[i];
+                    const url = page.url();
+                    const title = await page.title().catch(() => 'Unknown');
+                    response.addResult(`  [${i}] ${title} - ${url}`);
+                }
+                if (pages.length > 5) {
+                    response.addResult(`  ... and ${pages.length - 5} more pages`);
+                }
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            response.addError(`Failed to connect to CDP endpoint: ${errorMessage}`);
+            if (errorMessage.includes('ECONNREFUSED')) {
+                response.addResult(`\n💡 Troubleshooting tips:`);
+                response.addResult(`1. Make sure Chrome/Chromium is running with --remote-debugging-port=9222`);
+                response.addResult(`2. Start Chrome with: chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0`);
+                response.addResult(`3. Check if the endpoint is accessible: curl ${params.endpoint}/json/version`);
+            }
+            throw error;
+        }
+    },
+});
+// Get CDP endpoints from running browsers
+const getCDPEndpoints = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_get_cdp_endpoints',
+        title: 'Get available CDP endpoints',
+        description: 'Discover available Chrome DevTools Protocol endpoints from running browsers',
+        inputSchema: z.object({
+            port: z.number().optional().default(9222).describe('CDP port to check (default: 9222)'),
+            host: z.string().optional().default('localhost').describe('Host to check (default: localhost)'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        try {
+            const baseUrl = `http://${params.host}:${params.port}`;
+            response.addResult(`Checking for CDP endpoints at ${baseUrl}`);
+            // Try to fetch the version info
+            const versionResponse = await fetch(`${baseUrl}/json/version`);
+            if (!versionResponse.ok) {
+                throw new Error(`No CDP server found at ${baseUrl}`);
+            }
+            const versionInfo = await versionResponse.json();
+            response.addResult(`✅ Found CDP server!`);
+            response.addResult(`Browser: ${versionInfo.Browser}`);
+            response.addResult(`User-Agent: ${versionInfo['User-Agent']}`);
+            response.addResult(`WebSocket URL: ${versionInfo.webSocketDebuggerUrl}`);
+            // Get list of pages/targets
+            const pagesResponse = await fetch(`${baseUrl}/json`);
+            const pages = await pagesResponse.json();
+            response.addResult(`\nAvailable targets: ${pages.length}`);
+            pages.forEach((page, index) => {
+                response.addResult(`[${index}] ${page.type}: ${page.title || 'Untitled'}`);
+                response.addResult(`    URL: ${page.url}`);
+                response.addResult(`    WebSocket: ${page.webSocketDebuggerUrl}`);
+                response.addResult('');
+            });
+            response.addCode(`// To connect to this CDP endpoint:
+await client.callTool({
+  name: 'browser_connect_cdp',
+  arguments: { endpoint: '${baseUrl}' }
+});`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            response.addError(`Failed to discover CDP endpoints: ${errorMessage}`);
+            response.addResult(`\n💡 To start a browser with CDP enabled:`);
+            response.addResult(`Chrome: google-chrome --remote-debugging-port=${params.port} --remote-debugging-address=0.0.0.0`);
+            response.addResult(`Chromium: chromium --remote-debugging-port=${params.port} --remote-debugging-address=0.0.0.0`);
+            response.addResult(`Edge: msedge --remote-debugging-port=${params.port} --remote-debugging-address=0.0.0.0`);
+        }
+    },
+});
+// Disconnect from CDP
+const disconnectCDP = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_disconnect_cdp',
+        title: 'Disconnect from CDP',
+        description: 'Disconnect from the current CDP connection and return to normal browser mode',
+        inputSchema: z.object({}),
+        type: 'destructive',
+    },
+    handle: async (context, params, response) => {
+        if (!context.config.browser.cdpEndpoint) {
+            response.addResult('ℹ️ No active CDP connection to disconnect from');
+            return;
+        }
+        const previousEndpoint = context.config.browser.cdpEndpoint;
+        // Clear the CDP endpoint
+        context.config.browser.cdpEndpoint = undefined;
+        response.addResult(`✅ Disconnected from CDP endpoint: ${previousEndpoint}`);
+        response.addResult('Browser will now use normal launch mode for new connections');
+    },
+});
+export const cdpTools = [
+    connectCDP,
+    getCDPEndpoints,
+    disconnectCDP,
+];

package/lib/tools/common.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { defineTabTool, defineTool } from './tool.js';
+const close = defineTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_close',
+        title: 'Close browser',
+        description: 'Close the page',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (context, params, response) => {
+        await context.closeBrowserContext();
+        response.setIncludeTabs();
+        response.addCode(`await page.close()`);
+    },
+});
+const resize = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_resize',
+        title: 'Resize browser window',
+        description: 'Resize the browser window',
+        inputSchema: z.object({
+            width: z.number().describe('Width of the browser window'),
+            height: z.number().describe('Height of the browser window'),
+        }),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        response.addCode(`await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.setViewportSize({ width: params.width, height: params.height });
+        });
+    },
+});
+export default [
+    close,
+    resize
+];

package/lib/tools/console.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.
+ */
+import { z } from 'zod';
+import { defineTabTool } from './tool.js';
+const console = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_console_messages',
+        title: 'Get console messages',
+        description: 'Returns all console messages',
+        inputSchema: z.object({}),
+        type: 'readOnly',
+    },
+    handle: async (tab, params, response) => {
+        tab.consoleMessages().map(message => response.addResult(message.toString()));
+    },
+});
+export default [
+    console,
+];

package/lib/tools/dialogs.js

@@ -0,0 +1,47 @@
+/**
+ * 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 handleDialog = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_handle_dialog',
+        title: 'Handle a dialog',
+        description: 'Handle a dialog',
+        inputSchema: z.object({
+            accept: z.boolean().describe('Whether to accept the dialog.'),
+            promptText: z.string().optional().describe('The text of the prompt in case of a prompt dialog.'),
+        }),
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        const dialogState = tab.modalStates().find(state => state.type === 'dialog');
+        if (!dialogState)
+            throw new Error('No dialog visible');
+        tab.clearModalState(dialogState);
+        await tab.waitForCompletion(async () => {
+            if (params.accept)
+                await dialogState.dialog.accept(params.promptText);
+            else
+                await dialogState.dialog.dismiss();
+        });
+    },
+    clearsModalState: 'dialog',
+});
+export default [
+    handleDialog,
+];

package/lib/tools/evaluate.js

@@ -0,0 +1,53 @@
+/**
+ * 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 evaluateSchema = z.object({
+    function: z.string().describe('() => { /* code */ } or (element) => { /* code */ } when element is provided'),
+    element: z.string().optional().describe('Human-readable element description used to obtain permission to interact with the element'),
+    ref: z.string().optional().describe('Exact target element reference from the page snapshot'),
+});
+const evaluate = defineTabTool({
+    capability: 'core',
+    schema: {
+        name: 'browser_evaluate',
+        title: 'Evaluate JavaScript',
+        description: 'Evaluate JavaScript expression on page or element',
+        inputSchema: evaluateSchema,
+        type: 'destructive',
+    },
+    handle: async (tab, params, response) => {
+        response.setIncludeSnapshot();
+        let locator;
+        if (params.ref && params.element) {
+            locator = await tab.refLocator({ ref: params.ref, element: params.element });
+            response.addCode(`await page.${await generateLocator(locator)}.evaluate(${javascript.quote(params.function)});`);
+        }
+        else {
+            response.addCode(`await page.evaluate(${javascript.quote(params.function)});`);
+        }
+        await tab.waitForCompletion(async () => {
+            const receiver = locator ?? tab.page;
+            const result = await receiver._evaluateFunction(params.function);
+            response.addResult(JSON.stringify(result, null, 2) || 'undefined');
+        });
+    },
+});
+export default [
+    evaluate,
+];