@democratize-quality/mcp-server 1.0.0

package/src/tools/browser/launch.js

@@ -0,0 +1,67 @@
+const ToolBase = require('../base/ToolBase');
+const browserService = require('../../services/browserService');
+
+/**
+ * Browser Launch Tool
+ * Launches a new web browser instance and returns a unique browserId
+ */
+class BrowserLaunchTool extends ToolBase {
+    static definition = {
+        name: "browser_launch",
+        description: "Launches a new web browser instance. Returns a unique browserId. Use this before any other browser actions.",
+        input_schema: {
+            type: "object",
+            properties: {
+                headless: { 
+                    type: "boolean", 
+                    description: "Whether to launch the browser in headless mode (no UI). Defaults to true. Set to false for manual login.", 
+                    default: true 
+                },
+                userDataDir: { 
+                    type: "string", 
+                    description: "Optional. A path (relative to the server) to a directory to store persistent user data (e.g., login sessions, cookies). Use for authenticated sessions. If not provided, a temporary profile is used." 
+                },
+                port: {
+                    type: "number",
+                    description: "Optional. The port for remote debugging. If not provided, Chrome will choose an available port."
+                }
+            }
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                browserId: { type: "string", description: "The unique ID of the launched browser instance." },
+                port: { type: "number", description: "The port the browser instance is running on for remote debugging." },
+                userDataDir: { type: "string", description: "The absolute path to the user data directory used." }
+            },
+            required: ["browserId", "port"]
+        }
+    };
+
+    async execute(parameters) {
+        // Set defaults
+        const headless = parameters.headless !== undefined ? parameters.headless : true;
+        const port = parameters.port || undefined; // Let chrome-launcher choose if not specified
+        const userDataDir = parameters.userDataDir || null;
+
+        console.error(`[BrowserLaunchTool] Launching browser with headless=${headless}, port=${port}, userDataDir=${userDataDir}`);
+
+        try {
+            const result = await browserService.launchBrowser(headless, port, userDataDir);
+            
+            console.error(`[BrowserLaunchTool] Successfully launched browser: ${result.browserId}`);
+            
+            return {
+                browserId: result.browserId,
+                port: result.port,
+                userDataDir: result.userDataDir || null
+            };
+            
+        } catch (error) {
+            console.error(`[BrowserLaunchTool] Failed to launch browser:`, error.message);
+            throw new Error(`Failed to launch browser: ${error.message}`);
+        }
+    }
+}
+
+module.exports = BrowserLaunchTool;

package/src/tools/browser/navigate.js

@@ -0,0 +1,270 @@
+const ToolBase = require('../base/ToolBase');
+const browserService = require('../../services/browserService');
+
+/**
+ * Enhanced Browser Navigate Tool
+ * Navigates a specific browser instance to a given URL with history navigation support
+ * Inspired by Playwright MCP navigate capabilities
+ */
+class BrowserNavigateTool extends ToolBase {
+    static definition = {
+        name: "browser_navigate",
+        description: "Navigate browser pages with full history support including go to URL, back, forward, and refresh operations.",
+        input_schema: {
+            type: "object",
+            properties: {
+                browserId: { 
+                    type: "string", 
+                    description: "The ID of the browser instance to navigate." 
+                },
+                action: {
+                    type: "string",
+                    enum: ["goto", "back", "forward", "refresh", "reload"],
+                    default: "goto",
+                    description: "Navigation action to perform"
+                },
+                url: { 
+                    type: "string", 
+                    description: "The URL to navigate to (required for 'goto' action). Must include protocol (http:// or https://)." 
+                },
+                waitForNavigation: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to wait for navigation to complete"
+                },
+                timeout: {
+                    type: "number",
+                    default: 30000,
+                    description: "Navigation timeout in milliseconds"
+                }
+            },
+            required: ["browserId"]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean", description: "Whether the navigation was successful" },
+                action: { type: "string", description: "The navigation action that was performed" },
+                message: { type: "string", description: "Confirmation message of the navigation result" },
+                url: { type: "string", description: "The current URL after navigation" },
+                previousUrl: { type: "string", description: "The previous URL (for back/forward actions)" },
+                canGoBack: { type: "boolean", description: "Whether browser can navigate back" },
+                canGoForward: { type: "boolean", description: "Whether browser can navigate forward" },
+                browserId: { type: "string", description: "The browser instance ID that was used" }
+            },
+            required: ["success", "action", "message", "browserId"]
+        }
+    };
+
+    async execute(parameters) {
+        const { 
+            browserId, 
+            action = "goto", 
+            url, 
+            waitForNavigation = true, 
+            timeout = 30000 
+        } = parameters;
+
+        // Validate required parameters
+        if (action === "goto" && !url) {
+            throw new Error("URL is required for 'goto' action");
+        }
+
+        if (url && !url.startsWith('http://') && !url.startsWith('https://')) {
+            throw new Error("URL must include protocol (http:// or https://)");
+        }
+
+        const browser = browserService.getBrowserInstance(browserId);
+        if (!browser) {
+            throw new Error(`Browser instance '${browserId}' not found. Please launch a browser first using browser_launch.`);
+        }
+
+        const client = browser.cdpClient;
+        
+        console.error(`[BrowserNavigateTool] Performing ${action} action on browser ${browserId}`);
+
+        try {
+            let result = {
+                success: false,
+                action: action,
+                browserId: browserId
+            };
+
+            // Get current URL and navigation state before action
+            const currentInfo = await this.getCurrentNavigationState(client);
+
+            switch (action) {
+                case 'goto':
+                    await this.performGoto(client, url, waitForNavigation, timeout);
+                    result.success = true;
+                    result.message = `Successfully navigated to ${url}`;
+                    result.url = url;
+                    result.previousUrl = currentInfo.url;
+                    break;
+
+                case 'back':
+                    if (!currentInfo.canGoBack) {
+                        throw new Error("Cannot go back - no previous page in history");
+                    }
+                    await this.performBack(client, waitForNavigation);
+                    const backInfo = await this.getCurrentNavigationState(client);
+                    result.success = true;
+                    result.message = "Successfully navigated back";
+                    result.url = backInfo.url;
+                    result.previousUrl = currentInfo.url;
+                    break;
+
+                case 'forward':
+                    if (!currentInfo.canGoForward) {
+                        throw new Error("Cannot go forward - no next page in history");
+                    }
+                    await this.performForward(client, waitForNavigation);
+                    const forwardInfo = await this.getCurrentNavigationState(client);
+                    result.success = true;
+                    result.message = "Successfully navigated forward";
+                    result.url = forwardInfo.url;
+                    result.previousUrl = currentInfo.url;
+                    break;
+
+                case 'refresh':
+                case 'reload':
+                    await this.performRefresh(client, waitForNavigation);
+                    result.success = true;
+                    result.message = "Successfully refreshed page";
+                    result.url = currentInfo.url;
+                    break;
+
+                default:
+                    throw new Error(`Unsupported navigation action: ${action}`);
+            }
+
+            // Get final navigation state
+            const finalInfo = await this.getCurrentNavigationState(client);
+            result.canGoBack = finalInfo.canGoBack;
+            result.canGoForward = finalInfo.canGoForward;
+            
+            if (!result.url) {
+                result.url = finalInfo.url;
+            }
+
+            console.error(`[BrowserNavigateTool] Successfully completed ${action} action`);
+            return result;
+            
+        } catch (error) {
+            console.error(`[BrowserNavigateTool] Navigation failed:`, error.message);
+            throw new Error(`Failed to perform ${action}: ${error.message}`);
+        }
+    }
+
+    /**
+     * Navigate to a specific URL
+     */
+    async performGoto(client, url, waitForNavigation, timeout) {
+        await client.Page.enable();
+        
+        if (waitForNavigation) {
+            // Set up navigation promise
+            const navigationPromise = new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(() => {
+                    reject(new Error(`Navigation timeout after ${timeout}ms`));
+                }, timeout);
+
+                client.Page.loadEventFired(() => {
+                    clearTimeout(timeoutId);
+                    resolve();
+                });
+            });
+
+            // Navigate and wait
+            await client.Page.navigate({ url });
+            await navigationPromise;
+        } else {
+            await client.Page.navigate({ url });
+        }
+    }
+
+    /**
+     * Navigate back in history
+     */
+    async performBack(client, waitForNavigation) {
+        const history = await client.Page.getNavigationHistory();
+        
+        if (history.currentIndex > 0) {
+            const previousEntry = history.entries[history.currentIndex - 1];
+            
+            if (waitForNavigation) {
+                const navigationPromise = new Promise((resolve) => {
+                    client.Page.loadEventFired(resolve);
+                });
+                
+                await client.Page.navigateToHistoryEntry({ entryId: previousEntry.id });
+                await navigationPromise;
+            } else {
+                await client.Page.navigateToHistoryEntry({ entryId: previousEntry.id });
+            }
+        }
+    }
+
+    /**
+     * Navigate forward in history
+     */
+    async performForward(client, waitForNavigation) {
+        const history = await client.Page.getNavigationHistory();
+        
+        if (history.currentIndex < history.entries.length - 1) {
+            const nextEntry = history.entries[history.currentIndex + 1];
+            
+            if (waitForNavigation) {
+                const navigationPromise = new Promise((resolve) => {
+                    client.Page.loadEventFired(resolve);
+                });
+                
+                await client.Page.navigateToHistoryEntry({ entryId: nextEntry.id });
+                await navigationPromise;
+            } else {
+                await client.Page.navigateToHistoryEntry({ entryId: nextEntry.id });
+            }
+        }
+    }
+
+    /**
+     * Refresh/reload the current page
+     */
+    async performRefresh(client, waitForNavigation) {
+        if (waitForNavigation) {
+            const navigationPromise = new Promise((resolve) => {
+                client.Page.loadEventFired(resolve);
+            });
+            
+            await client.Page.reload();
+            await navigationPromise;
+        } else {
+            await client.Page.reload();
+        }
+    }
+
+    /**
+     * Get current navigation state
+     */
+    async getCurrentNavigationState(client) {
+        await client.Page.enable();
+        
+        // Get current URL
+        const urlResult = await client.Runtime.evaluate({
+            expression: 'window.location.href'
+        });
+        
+        // Get navigation history
+        const history = await client.Page.getNavigationHistory();
+        
+        return {
+            url: urlResult.result.value,
+            canGoBack: history.currentIndex > 0,
+            canGoForward: history.currentIndex < history.entries.length - 1,
+            historyLength: history.entries.length,
+            currentIndex: history.currentIndex
+        };
+    }
+}
+
+module.exports = BrowserNavigateTool;

package/src/tools/browser/screenshot.js

@@ -0,0 +1,351 @@
+const ToolBase = require('../base/ToolBase');
+const browserService = require('../../services/browserService');
+
+/**
+ * Enhanced Browser Screenshot Tool
+ * Captures screenshots with advanced options including element-specific and full-page captures
+ * Inspired by Playwright MCP screenshot capabilities
+ */
+class BrowserScreenshotTool extends ToolBase {
+    static definition = {
+        name: "browser_screenshot",
+        description: "Capture screenshots with advanced options including full page, element-specific, and custom formats with quality control.",
+        input_schema: {
+            type: "object",
+            properties: {
+                browserId: { 
+                    type: "string", 
+                    description: "The ID of the browser instance." 
+                },
+                fileName: { 
+                    type: "string", 
+                    description: "Optional. The name of the file to save the screenshot as (e.g., 'my_page.png'). Saved to the server's configured output directory. If not provided, a timestamped name is used." 
+                },
+                saveToDisk: { 
+                    type: "boolean", 
+                    description: "Optional. Whether to save the screenshot to disk on the server. Defaults to true. Set to false to only receive base64 data.", 
+                    default: true 
+                },
+                options: {
+                    type: "object",
+                    properties: {
+                        fullPage: {
+                            type: "boolean",
+                            default: false,
+                            description: "Capture full scrollable page instead of just viewport"
+                        },
+                        element: {
+                            type: "string",
+                            description: "CSS selector of element to screenshot (captures only that element)"
+                        },
+                        format: {
+                            type: "string",
+                            enum: ["png", "jpeg", "webp"],
+                            default: "png",
+                            description: "Image format"
+                        },
+                        quality: {
+                            type: "number",
+                            minimum: 0,
+                            maximum: 100,
+                            description: "JPEG/WebP quality (0-100, ignored for PNG)"
+                        },
+                        clip: {
+                            type: "object",
+                            properties: {
+                                x: { type: "number", description: "X coordinate of clip area" },
+                                y: { type: "number", description: "Y coordinate of clip area" },
+                                width: { type: "number", description: "Width of clip area" },
+                                height: { type: "number", description: "Height of clip area" },
+                                scale: { type: "number", description: "Scale factor for clip area" }
+                            },
+                            description: "Specific area to capture"
+                        },
+                        omitBackground: {
+                            type: "boolean",
+                            default: false,
+                            description: "Hide default white background for transparent screenshots"
+                        },
+                        captureBeyondViewport: {
+                            type: "boolean",
+                            default: false,
+                            description: "Capture content outside viewport"
+                        }
+                    },
+                    description: "Screenshot capture options"
+                }
+            },
+            required: ["browserId"]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean", description: "Whether screenshot was captured successfully" },
+                imageData: { type: "string", description: "Base64 encoded image data" },
+                format: { type: "string", description: "Image format used" },
+                fileName: { type: "string", description: "The file name if saved to disk" },
+                dimensions: {
+                    type: "object",
+                    properties: {
+                        width: { type: "number" },
+                        height: { type: "number" }
+                    },
+                    description: "Image dimensions"
+                },
+                fileSize: { type: "number", description: "File size in bytes" },
+                element: { type: "string", description: "CSS selector if element screenshot was taken" },
+                browserId: { type: "string", description: "The browser instance ID that was used" }
+            },
+            required: ["success", "imageData", "format", "browserId"]
+        }
+    };
+
+    async execute(parameters) {
+        const { 
+            browserId, 
+            fileName, 
+            saveToDisk = true, 
+            options = {} 
+        } = parameters;
+
+        const browser = browserService.getBrowserInstance(browserId);
+        if (!browser) {
+            throw new Error(`Browser instance '${browserId}' not found. Please launch a browser first using browser_launch.`);
+        }
+
+        // Generate filename if not provided
+        const fileExtension = this.getFileExtension(options.format || 'png');
+        const finalFileName = fileName || `screenshot_${browserId}_${Date.now()}.${fileExtension}`;
+
+        console.error(`[BrowserScreenshotTool] Taking screenshot of browser ${browserId}, fileName: ${finalFileName}, saveToDisk: ${saveToDisk}`);
+
+        try {
+            let screenshotResult;
+            
+            if (options.element) {
+                screenshotResult = await this.captureElementScreenshot(browser.client, options);
+            } else {
+                screenshotResult = await this.capturePageScreenshot(browser.client, options);
+            }
+            
+            // Save to disk if requested
+            let savedPath = null;
+            if (saveToDisk) {
+                savedPath = await this.saveScreenshot(screenshotResult.data, finalFileName);
+            }
+            
+            console.error(`[BrowserScreenshotTool] Successfully captured screenshot for browser: ${browserId}`);
+            
+            return {
+                success: true,
+                imageData: screenshotResult.data,
+                format: options.format || 'png',
+                fileName: savedPath ? finalFileName : null,
+                dimensions: screenshotResult.dimensions,
+                fileSize: screenshotResult.fileSize,
+                element: options.element || null,
+                browserId: browserId
+            };
+            
+        } catch (error) {
+            console.error(`[BrowserScreenshotTool] Failed to take screenshot:`, error.message);
+            throw new Error(`Failed to take screenshot of browser ${browserId}: ${error.message}`);
+        }
+    }
+
+    /**
+     * Capture page screenshot with options
+     */
+    async capturePageScreenshot(client, options) {
+        await client.Page.enable();
+        
+        const screenshotOptions = {
+            format: options.format || 'png',
+            quality: options.format !== 'png' ? options.quality : undefined,
+            optimizeForSpeed: false,
+            captureBeyondViewport: options.captureBeyondViewport || options.fullPage || false
+        };
+
+        // Handle clip area
+        if (options.clip) {
+            screenshotOptions.clip = options.clip;
+        }
+
+        // Handle full page screenshot
+        if (options.fullPage && !options.clip) {
+            const layoutMetrics = await client.Page.getLayoutMetrics();
+            screenshotOptions.clip = {
+                x: 0,
+                y: 0,
+                width: layoutMetrics.contentSize.width,
+                height: layoutMetrics.contentSize.height,
+                scale: 1
+            };
+        }
+
+        // Handle transparent background
+        if (options.omitBackground) {
+            // Set background to transparent (requires format support)
+            await client.Emulation.setDefaultBackgroundColorOverride({
+                color: { r: 0, g: 0, b: 0, a: 0 }
+            });
+        }
+
+        const result = await client.Page.captureScreenshot(screenshotOptions);
+        
+        // Reset background if it was changed
+        if (options.omitBackground) {
+            await client.Emulation.setDefaultBackgroundColorOverride();
+        }
+
+        return {
+            data: result.data,
+            dimensions: this.getImageDimensions(screenshotOptions.clip),
+            fileSize: Buffer.from(result.data, 'base64').length
+        };
+    }
+
+    /**
+     * Capture element screenshot
+     */
+    async captureElementScreenshot(client, options) {
+        await client.DOM.enable();
+        await client.Page.enable();
+
+        // Find the element
+        const document = await client.DOM.getDocument();
+        const element = await client.DOM.querySelector({
+            nodeId: document.root.nodeId,
+            selector: options.element
+        });
+
+        if (!element.nodeId) {
+            throw new Error(`Element not found with selector: ${options.element}`);
+        }
+
+        // Get element bounds
+        const box = await client.DOM.getBoxModel({ nodeId: element.nodeId });
+        if (!box.model) {
+            throw new Error(`Could not get bounds for element: ${options.element}`);
+        }
+
+        // Use content bounds for the clip
+        const bounds = box.model.content;
+        const clip = {
+            x: Math.round(bounds[0]),
+            y: Math.round(bounds[1]),
+            width: Math.round(bounds[4] - bounds[0]),
+            height: Math.round(bounds[5] - bounds[1]),
+            scale: 1
+        };
+
+        const screenshotOptions = {
+            format: options.format || 'png',
+            quality: options.format !== 'png' ? options.quality : undefined,
+            clip: clip,
+            optimizeForSpeed: false
+        };
+
+        // Handle transparent background for element
+        if (options.omitBackground) {
+            await client.Emulation.setDefaultBackgroundColorOverride({
+                color: { r: 0, g: 0, b: 0, a: 0 }
+            });
+        }
+
+        const result = await client.Page.captureScreenshot(screenshotOptions);
+        
+        if (options.omitBackground) {
+            await client.Emulation.setDefaultBackgroundColorOverride();
+        }
+
+        return {
+            data: result.data,
+            dimensions: { width: clip.width, height: clip.height },
+            fileSize: Buffer.from(result.data, 'base64').length
+        };
+    }
+
+    /**
+     * Save screenshot to disk
+     */
+    async saveScreenshot(base64Data, fileName) {
+        const fs = require('fs').promises;
+        const path = require('path');
+        const os = require('os');
+        
+        // Use output directory from environment or default to user home directory
+        const defaultOutputDir = process.env.HOME 
+            ? path.join(process.env.HOME, '.mcp-browser-control') 
+            : path.join(os.tmpdir(), 'mcp-browser-control');
+        const outputDir = process.env.OUTPUT_DIR || defaultOutputDir;
+        const filePath = path.join(outputDir, fileName);
+        
+        // Ensure directory exists
+        await fs.mkdir(outputDir, { recursive: true });
+        
+        // Save file
+        const buffer = Buffer.from(base64Data, 'base64');
+        await fs.writeFile(filePath, buffer);
+        
+        return filePath;
+    }
+
+    /**
+     * Get file extension for format
+     */
+    getFileExtension(format) {
+        const extensions = {
+            'png': 'png',
+            'jpeg': 'jpg',
+            'webp': 'webp'
+        };
+        return extensions[format] || 'png';
+    }
+
+    /**
+     * Get image dimensions from clip or default
+     */
+    getImageDimensions(clip) {
+        if (clip) {
+            return {
+                width: clip.width,
+                height: clip.height
+            };
+        }
+        return null; // Will be determined by actual screenshot
+    }
+
+    /**
+     * Capture screenshot with scroll handling
+     */
+    async captureWithScroll(client, options) {
+        // Save current scroll position
+        const scrollPosition = await client.Runtime.evaluate({
+            expression: '({ x: window.scrollX, y: window.scrollY })'
+        });
+
+        try {
+            // Scroll to top for full page capture
+            if (options.fullPage) {
+                await client.Runtime.evaluate({
+                    expression: 'window.scrollTo(0, 0)'
+                });
+                // Wait for scroll to complete
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+
+            const result = await this.capturePageScreenshot(client, options);
+
+            return result;
+        } finally {
+            // Restore original scroll position
+            const original = scrollPosition.result.value;
+            await client.Runtime.evaluate({
+                expression: `window.scrollTo(${original.x}, ${original.y})`
+            });
+        }
+    }
+}
+
+module.exports = BrowserScreenshotTool;