@democratize-quality/mcp-server 1.2.0 → 1.2.1

package/src/tools/browser/screenshot.js

@@ -0,0 +1,370 @@
+/**
+ * Copyright (C) 2025 Democratize Quality
+ *
+ * This file is part of Democratize Quality MCP Server.
+ *
+ * Democratize Quality MCP Server is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Democratize Quality MCP Server is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Democratize Quality MCP Server. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+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;

package/src/tools/browser/type.js

@@ -0,0 +1,193 @@
+/**
+ * Copyright (C) 2025 Democratize Quality
+ *
+ * This file is part of Democratize Quality MCP Server.
+ *
+ * Democratize Quality MCP Server is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Democratize Quality MCP Server is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Democratize Quality MCP Server. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const ToolBase = require('../base/ToolBase');
+const browserService = require('../../services/browserService');
+
+/**
+ * Browser Type Tool
+ * Types text into a specific input field in the browser with Playwright-style locators
+ */
+class BrowserTypeTool extends ToolBase {
+    static definition = {
+        name: "browser_type",
+        description: "Types text into a specific input field in the browser.",
+        input_schema: {
+            type: "object",
+            properties: {
+                browserId: {
+                    type: "string",
+                    description: "The ID of the browser instance."
+                },
+                locatorType: {
+                    type: "string",
+                    enum: ["css", "xpath", "text", "role", "label", "placeholder", "testId", "altText"],
+                    default: "css",
+                    description: "The type of locator to use"
+                },
+                locatorValue: {
+                    type: "string",
+                    description: "The locator value (CSS selector, XPath, text content, etc.)"
+                },
+                text: {
+                    type: "string",
+                    description: "The text to type into the input field."
+                },
+                // Keep backward compatibility
+                selector: {
+                    type: "string",
+                    description: "The CSS selector of the input field (deprecated, use locatorType and locatorValue instead)."
+                },
+                options: {
+                    type: "object",
+                    properties: {
+                        timeout: {
+                            type: "number",
+                            default: 30000,
+                            description: "Timeout in milliseconds"
+                        },
+                        delay: {
+                            type: "number",
+                            default: 0,
+                            description: "Delay between keystrokes in milliseconds"
+                        },
+                        clear: {
+                            type: "boolean",
+                            default: true,
+                            description: "Clear the field before typing"
+                        },
+                        noWaitAfter: {
+                            type: "boolean",
+                            default: false,
+                            description: "Do not wait for navigation after typing"
+                        }
+                    },
+                    description: "Additional typing options"
+                }
+            },
+            anyOf: [
+                { required: ["browserId", "locatorType", "locatorValue", "text"] },
+                { required: ["browserId", "selector", "text"] }
+            ]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean", description: "Indicates if the typing was successful." },
+                locatorType: { type: "string", description: "The locator type that was used." },
+                locatorValue: { type: "string", description: "The locator value that was used." },
+                text: { type: "string", description: "The text that was typed." },
+                browserId: { type: "string", description: "The browser instance ID that was used." },
+                elementFound: { type: "boolean", description: "Whether the element was found." },
+                message: { type: "string", description: "Success or error message." }
+            },
+            required: ["success", "browserId"]
+        }
+    };
+
+    async execute(parameters) {
+        const { browserId, locatorType, locatorValue, selector, text, options = {} } = parameters;
+
+        // Handle backward compatibility
+        let finalLocatorType, finalLocatorValue;
+        if (selector) {
+            finalLocatorType = "css";
+            finalLocatorValue = selector;
+        } else {
+            finalLocatorType = locatorType || "css";
+            finalLocatorValue = locatorValue;
+        }
+
+        console.error(`[BrowserTypeTool] Typing in browser ${browserId} with locator: ${finalLocatorType}="${finalLocatorValue}"`);
+
+        try {
+            // Convert Playwright-style locator to appropriate format for browser service
+            const elementSelector = this.convertLocatorToSelector(finalLocatorType, finalLocatorValue);
+            
+            await browserService.typeIntoElement(browserId, elementSelector, text, options);
+            
+            console.error(`[BrowserTypeTool] Successfully typed in browser: ${browserId}`);
+            
+            return { 
+                success: true, 
+                browserId: browserId,
+                locatorType: finalLocatorType,
+                locatorValue: finalLocatorValue,
+                text: text,
+                elementFound: true,
+                message: `Successfully typed "${text}" into element with ${finalLocatorType} locator: ${finalLocatorValue}`
+            };
+        } catch (error) {
+            console.error(`[BrowserTypeTool] Failed to type in element:`, error.message);
+            
+            return {
+                success: false,
+                browserId: browserId,
+                locatorType: finalLocatorType,
+                locatorValue: finalLocatorValue,
+                text: text,
+                elementFound: false,
+                message: `Failed to type into element: ${error.message}`
+            };
+        }
+    }
+
+    /**
+     * Convert Playwright-style locator to CSS selector or XPath
+     */
+    convertLocatorToSelector(locatorType, locatorValue) {
+        switch (locatorType) {
+            case "css":
+                return locatorValue;
+            
+            case "xpath":
+                return locatorValue;
+            
+            case "text":
+                // Convert text locator to XPath for input elements
+                return `//input[contains(@placeholder, "${locatorValue}")] | //input[contains(@value, "${locatorValue}")] | //textarea[contains(text(), "${locatorValue}")] | //label[contains(text(), "${locatorValue}")]/following-sibling::input | //label[contains(text(), "${locatorValue}")]/following::input[1]`;
+            
+            case "role":
+                // Convert role locator to CSS attribute selector
+                return `[role="${locatorValue}"]`;
+            
+            case "label":
+                // Convert label locator to XPath for label association
+                return `//input[@aria-label="${locatorValue}"] | //input[@id=//label[contains(text(), "${locatorValue}")]/@for] | //label[contains(text(), "${locatorValue}")]/following-sibling::input | //label[contains(text(), "${locatorValue}")]/following::input[1]`;
+            
+            case "placeholder":
+                // Convert placeholder locator to CSS attribute selector
+                return `[placeholder="${locatorValue}"]`;
+            
+            case "testId":
+                // Convert test ID to CSS attribute selector (assuming data-testid)
+                return `[data-testid="${locatorValue}"]`;
+            
+            case "altText":
+                // Convert alt text to CSS attribute selector (less common for input fields)
+                return `[alt="${locatorValue}"]`;
+            
+            default:
+                // Default to CSS selector
+                return locatorValue;
+        }
+    }
+}
+
+module.exports = BrowserTypeTool;

package/src/tools/index.js

@@ -0,0 +1,114 @@
+/**
+ * Copyright (C) 2025 Democratize Quality
+ *
+ * This file is part of Democratize Quality MCP Server.
+ *
+ * Democratize Quality MCP Server is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Democratize Quality MCP Server is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Democratize Quality MCP Server. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+const ToolRegistry = require('./base/ToolRegistry');
+const path = require('path');
+
+/**
+ * Initialize and configure the tool registry
+ * This file serves as the main entry point for the tools system
+ */
+
+// Create the global tool registry instance
+const toolRegistry = new ToolRegistry();
+
+/**
+ * Initialize the tool registry by discovering and loading all tools
+ * @param {boolean} debugMode - Whether to enable debug logging
+ * @returns {Promise<ToolRegistry>} - The initialized tool registry
+ */
+async function initializeTools(debugMode = false) {
+    if (debugMode) {
+        console.error('[Tools] Initializing tool system...');
+    }
+    
+    try {
+        // Get the tools directory path
+        const toolsDir = path.join(__dirname);
+        
+        // Discover and load all tools
+        await toolRegistry.discoverTools(toolsDir, debugMode);
+        
+        // Log registry statistics
+        const stats = toolRegistry.getStats();
+        console.error(`[Tools] Tool system initialized successfully:`);
+        console.error(`[Tools] - Total tools: ${stats.total_tools}`);
+        if (debugMode) {
+            console.error(`[Tools] - Available tools: ${stats.tool_names.join(', ')}`);
+        }
+        
+        return toolRegistry;
+        
+    } catch (error) {
+        console.error('[Tools] Failed to initialize tool system:', error.message);
+        throw error;
+    }
+}
+
+/**
+ * Get the tool registry instance
+ * @returns {ToolRegistry} - The tool registry instance
+ */
+function getToolRegistry() {
+    return toolRegistry;
+}
+
+/**
+ * Get all tool definitions for MCP tools/list response
+ * @returns {Array} - Array of tool definitions
+ */
+function getToolDefinitions() {
+    return toolRegistry.getDefinitions();
+}
+
+/**
+ * Execute a tool by name
+ * @param {string} toolName - The name of the tool to execute
+ * @param {object} parameters - The parameters to pass to the tool
+ * @returns {Promise<object>} - The tool execution result
+ */
+async function executeTool(toolName, parameters) {
+    return await toolRegistry.executeTool(toolName, parameters);
+}
+
+/**
+ * Check if a tool is available
+ * @param {string} toolName - The name of the tool to check
+ * @returns {boolean} - True if the tool is available
+ */
+function isToolAvailable(toolName) {
+    return toolRegistry.hasTool(toolName);
+}
+
+/**
+ * Get list of available tool names
+ * @returns {Array<string>} - Array of available tool names
+ */
+function getAvailableTools() {
+    return toolRegistry.getToolNames();
+}
+
+module.exports = {
+    initializeTools,
+    getToolRegistry,
+    getToolDefinitions,
+    executeTool,
+    isToolAvailable,
+    getAvailableTools
+};