@ricardodeazambuja/browser-mcp-server 1.0.3 → 1.4.0

package/src/browser.js

@@ -0,0 +1,152 @@
+/**
+ * Browser connection and state management
+ */
+
+const os = require('os');
+const { debugLog, loadPlaywright, findChromeExecutable } = require('./utils');
+const { resetCDPSession } = require('./cdp');
+
+// Browser state
+let browser = null;
+let context = null;
+let page = null;
+let activePageIndex = 0;
+
+/**
+ * Connect to existing Chrome or launch new instance (hybrid mode)
+ * @returns {Object} { browser, context, page }
+ */
+async function connectToBrowser() {
+    // Check if browser is disconnected or closed
+    if (browser && (!browser.isConnected || !browser.isConnected())) {
+        debugLog('Browser connection lost, resetting...');
+        browser = null;
+        context = null;
+        page = null;
+    }
+
+    if (!browser) {
+        try {
+            const pw = loadPlaywright();
+
+            // STRATEGY 1: Try to connect to existing Chrome (Antigravity mode)
+            try {
+                debugLog('Attempting to connect to Chrome on port 9222...');
+                browser = await pw.chromium.connectOverCDP('http://localhost:9222');
+                debugLog('✅ Connected to existing Chrome (Antigravity mode)');
+
+                const contexts = browser.contexts();
+                context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+            } catch (connectError) {
+                debugLog(`Could not connect to existing Chrome: ${connectError.message}`);
+            }
+
+            // STRATEGY 2: Launch our own Chrome (Standalone mode)
+            if (!browser) {
+                debugLog('No existing Chrome found. Launching new instance...');
+
+                const profileDir = process.env.MCP_BROWSER_PROFILE ||
+                    `${os.tmpdir()}/chrome-mcp-profile`;
+
+                debugLog(`Browser profile: ${profileDir}`);
+
+                const chromeExecutable = findChromeExecutable();
+                const launchOptions = {
+                    headless: false,
+                    args: [
+                        '--remote-debugging-port=9222',
+                        '--no-first-run',
+                        '--no-default-browser-check',
+                        '--disable-fre',
+                        '--disable-features=TranslateUI,OptGuideOnDeviceModel',
+                        '--disable-sync',
+                        '--disable-component-update',
+                        '--disable-background-networking',
+                        '--disable-breakpad',
+                        '--disable-background-timer-throttling',
+                        '--disable-backgrounding-occluded-windows',
+                        '--disable-renderer-backgrounding'
+                    ]
+                };
+
+                if (chromeExecutable) {
+                    debugLog(`Using system Chrome/Chromium: ${chromeExecutable}`);
+                    launchOptions.executablePath = chromeExecutable;
+                } else {
+                    debugLog('No system Chrome/Chromium found. Attempting to use Playwright Chromium...');
+                }
+
+                try {
+                    context = await pw.chromium.launchPersistentContext(profileDir, launchOptions);
+                    browser = context;
+                } catch (launchError) {
+                    if (!chromeExecutable && launchError.message.includes("Executable doesn't exist")) {
+                        debugLog('Playwright Chromium not installed and no system Chrome found');
+                        throw new Error(
+                            '❌ No Chrome/Chromium browser found!\n\n' +
+                            'This MCP server needs a Chrome or Chromium browser to work.\n\n' +
+                            'Option 1 - Install Chrome/Chromium on your system\n' +
+                            'Option 2 - Install Playwright\'s Chromium: npx playwright install chromium\n' +
+                            'Option 3 - Use with Antigravity: Open browser via Chrome logo\n'
+                        );
+                    }
+                    throw launchError;
+                }
+                debugLog('✅ Successfully launched new Chrome instance (Standalone mode)');
+            }
+
+        } catch (error) {
+            debugLog(`Failed to connect/launch Chrome: ${error.message}`);
+            throw error;
+        }
+    }
+
+    // Ensure we have a context and page
+    if (!context) {
+        const contexts = browser.contexts();
+        context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+    }
+
+    const pages = context.pages();
+    if (pages.length === 0) {
+        page = await context.newPage();
+        activePageIndex = 0;
+    } else {
+        if (activePageIndex >= pages.length) activePageIndex = pages.length - 1;
+        page = pages[activePageIndex];
+    }
+
+    return { browser, context, page };
+}
+
+/**
+ * Get browser state
+ */
+function getBrowserState() {
+    return { browser, context, page, activePageIndex };
+}
+
+/**
+ * Set active page index
+ */
+function setActivePageIndex(index) {
+    activePageIndex = index;
+}
+
+/**
+ * Reset browser state
+ */
+function resetBrowserState() {
+    browser = null;
+    context = null;
+    page = null;
+    activePageIndex = 0;
+    resetCDPSession();
+}
+
+module.exports = {
+    connectToBrowser,
+    getBrowserState,
+    setActivePageIndex,
+    resetBrowserState
+};

package/src/cdp.js

@@ -0,0 +1,58 @@
+/**
+ * CDP (Chrome DevTools Protocol) Session Manager
+ * Manages CDP session lifecycle for advanced browser automation tools
+ */
+
+const { debugLog } = require('./utils');
+
+// CDP session state
+let cdpSession = null;
+let currentPage = null;
+
+/**
+ * Get or create CDP session for current page
+ * Sessions are cached per page instance for efficiency
+ * @returns {CDPSession} Active CDP session
+ */
+async function getCDPSession() {
+    // Lazy-load to avoid circular dependency with browser.js
+    const { connectToBrowser } = require('./browser');
+    const { page } = await connectToBrowser();
+
+    // If page changed or session doesn't exist, create new session
+    if (!cdpSession || currentPage !== page) {
+        // Detach old session if it exists
+        if (cdpSession) {
+            try {
+                await cdpSession.detach();
+                debugLog('Detached old CDP session');
+            } catch (e) {
+                debugLog(`Failed to detach old CDP session: ${e.message}`);
+            }
+        }
+
+        // Create new session for current page
+        currentPage = page;
+        cdpSession = await page.context().newCDPSession(page);
+        debugLog('Created new CDP session');
+    }
+
+    return cdpSession;
+}
+
+/**
+ * Reset CDP session state
+ * Called when browser state is reset (connection lost, browser restart, etc.)
+ */
+function resetCDPSession() {
+    if (cdpSession) {
+        debugLog('Resetting CDP session state');
+    }
+    cdpSession = null;
+    currentPage = null;
+}
+
+module.exports = {
+    getCDPSession,
+    resetCDPSession
+};

package/src/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Universal Browser Automation MCP Server (Playwright Edition)
+ * Main Entry Point
+ */
+
+const readline = require('readline');
+const { debugLog, version } = require('./utils');
+const { tools, handlers } = require('./tools');
+const { getBrowserState } = require('./browser');
+
+class BrowserMCPServer {
+    constructor() {
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false
+        });
+
+        this.init();
+    }
+
+    init() {
+        debugLog('Server starting via src/index.js...');
+
+        // Process stdin lines as MCP requests
+        this.rl.on('line', (line) => this.handleLine(line));
+
+        // Handle cleanup
+        process.on('SIGTERM', () => this.cleanup());
+        process.on('SIGINT', () => this.cleanup());
+    }
+
+    async handleLine(line) {
+        let request;
+        try {
+            debugLog(`Received: ${line.substring(0, 200)}`);
+            request = JSON.parse(line);
+
+            if (request.method === 'initialize') {
+                this.handleInitialize(request);
+            } else if (request.method === 'notifications/initialized') {
+                debugLog('Received initialized notification');
+            } else if (request.method === 'tools/list') {
+                this.handleToolsList(request);
+            } else if (request.method === 'tools/call') {
+                await this.handleToolCall(request);
+            } else {
+                debugLog(`Unknown method: ${request.method}`);
+                this.respond(request.id, null, { code: -32601, message: 'Method not found' });
+            }
+        } catch (error) {
+            debugLog(`Error processing request: ${error.message}`);
+            // Only log to stderr if it's not a JSON parse error (which would break MCP)
+            // Actually, stderr is fine, just don't write to stdout unless it's a JSON-RPC response
+            const id = request?.id || null;
+            this.respond(id, null, { code: -32603, message: error.message });
+        }
+    }
+
+    handleInitialize(request) {
+        debugLog(`Initialize with protocol: ${request.params.protocolVersion}`);
+        this.respond(request.id, {
+            protocolVersion: request.params.protocolVersion || '2024-11-05',
+            capabilities: { tools: {} },
+            serverInfo: {
+                name: 'browser-automation-playwright',
+                version: version
+            }
+        });
+    }
+
+    handleToolsList(request) {
+        debugLog('Sending tools list');
+        this.respond(request.id, { tools });
+    }
+
+    async handleToolCall(request) {
+        debugLog(`Calling tool: ${request.params.name}`);
+        const result = await this.executeTool(request.params.name, request.params.arguments || {});
+        this.respond(request.id, result);
+    }
+
+    async executeTool(name, args) {
+        try {
+            const handler = handlers[name];
+            if (!handler) {
+                throw new Error(`Unknown tool: ${name}`);
+            }
+            return await handler(args);
+        } catch (error) {
+            debugLog(`Tool execution error (${name}): ${error.message}`);
+            return {
+                content: [{
+                    type: 'text',
+                    text: `❌ Error executing ${name}: ${error.message}`
+                }],
+                isError: true
+            };
+        }
+    }
+
+    respond(id, result, error = null) {
+        const response = { jsonrpc: '2.0', id };
+        if (error) response.error = error;
+        else response.result = result;
+        console.log(JSON.stringify(response));
+    }
+
+    async cleanup() {
+        const { browser } = getBrowserState();
+        if (browser) {
+            debugLog('Closing browser on exit...');
+            await browser.close().catch(() => { });
+        }
+        process.exit(0);
+    }
+}
+
+// Start the server if this file is run directly
+if (require.main === module) {
+    new BrowserMCPServer();
+}
+
+module.exports = { BrowserMCPServer };

package/src/tools/console.js

@@ -0,0 +1,139 @@
+const { connectToBrowser } = require('../browser');
+const { debugLog } = require('../utils');
+
+// Local state for console tool
+let consoleLogs = [];
+let consoleListening = false;
+
+const definitions = [
+    {
+        name: 'browser_console_start',
+        description: 'Start capturing browser console logs (console.log, console.error, console.warn, etc.) (see browser_docs)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                level: {
+                    type: 'string',
+                    description: 'Optional filter for log level: "log", "error", "warn", "info", "debug", or "all"',
+                    enum: ['log', 'error', 'warn', 'info', 'debug', 'all']
+                }
+            },
+            additionalProperties: false,
+            $schema: 'http://json-schema.org/draft-07/schema#'
+        }
+    },
+    {
+        name: 'browser_console_get',
+        description: 'Get all captured console logs since browser_console_start was called (see browser_docs)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filter: {
+                    type: 'string',
+                    description: 'Optional filter by log level: "log", "error", "warn", "info", "debug", or "all"',
+                    enum: ['log', 'error', 'warn', 'info', 'debug', 'all']
+                }
+            },
+            additionalProperties: false,
+            $schema: 'http://json-schema.org/draft-07/schema#'
+        }
+    },
+    {
+        name: 'browser_console_clear',
+        description: 'Clear all captured console logs and stop listening (see browser_docs)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+            $schema: 'http://json-schema.org/draft-07/schema#'
+        }
+    }
+];
+
+const handlers = {
+    browser_console_start: async (args) => {
+        const { page } = await connectToBrowser();
+        if (!consoleListening) {
+            page.on('console', msg => {
+                const logEntry = {
+                    type: msg.type(),
+                    text: msg.text(),
+                    timestamp: new Date().toISOString(),
+                    location: msg.location()
+                };
+                consoleLogs.push(logEntry);
+                debugLog(`Console [${logEntry.type}]: ${logEntry.text}`);
+            });
+            consoleListening = true;
+            debugLog('Console logging started');
+        }
+        return {
+            content: [{
+                type: 'text',
+                text: `✅ Console logging started.\n\nCapturing: console.log, console.error, console.warn, console.info, console.debug\n\nUse browser_console_get to retrieve captured logs.`
+            }]
+        };
+    },
+
+    browser_console_get: async (args) => {
+        const filter = args.filter;
+        const filtered = filter && filter !== 'all'
+            ? consoleLogs.filter(log => log.type === filter)
+            : consoleLogs;
+
+        if (filtered.length === 0) {
+            return {
+                content: [{
+                    type: 'text',
+                    text: consoleListening
+                        ? `No console logs captured yet.\n\n${filter && filter !== 'all' ? `Filter: ${filter}\n` : ''}Console logging is active - logs will appear as the page executes JavaScript.`
+                        : `Console logging is not active.\n\nUse browser_console_start to begin capturing logs.`
+                }]
+            };
+        }
+
+        const logSummary = `📋 Captured ${filtered.length} console log${filtered.length === 1 ? '' : 's'}${filter && filter !== 'all' ? ` (filtered by: ${filter})` : ''}:\n\n`;
+        const formattedLogs = filtered.map((log, i) => {
+            const icon = {
+                'error': '❌',
+                'warn': '⚠️',
+                'log': '📝',
+                'info': 'ℹ️',
+                'debug': '🔍'
+            }[log.type] || '📄';
+
+            return `${i + 1}. ${icon} [${log.type.toUpperCase()}] ${log.timestamp}\n   ${log.text}${log.location.url ? `\n   Location: ${log.location.url}:${log.location.lineNumber}` : ''}`;
+        }).join('\n\n');
+
+        return {
+            content: [{
+                type: 'text',
+                text: logSummary + formattedLogs
+            }]
+        };
+    },
+
+    browser_console_clear: async (args) => {
+        const { page } = await connectToBrowser();
+        const count = consoleLogs.length;
+        consoleLogs = [];
+        if (consoleListening) {
+            // Removing listeners is tricky if we don't store the reference to the specific function we passed
+            // But page.removeAllListeners('console') is cleaner if we are the only one using it.
+            // In this server context, we likely are.
+            if (page) {
+                page.removeAllListeners('console');
+            }
+            consoleListening = false;
+        }
+        debugLog(`Cleared ${count} console logs and stopped listening`);
+        return {
+            content: [{
+                type: 'text',
+                text: `✅ Cleared ${count} console log${count === 1 ? '' : 's'} and stopped listening.\n\nUse browser_console_start to resume capturing.`
+            }]
+        };
+    }
+};
+
+module.exports = { definitions, handlers };