@democratize-quality/mcp-server 1.2.0 → 1.2.1

package/src/tools/browser/dom.js

@@ -0,0 +1,89 @@
+/**
+ * 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 DOM Tool
+ * Interacts with the DOM of the current browser page.
+ */
+class BrowserDOMTool extends ToolBase {
+    static definition = {
+        name: "browser_dom",
+        description: "Interacts with the DOM of the current browser page.",
+        input_schema: {
+            type: "object",
+            properties: {
+                browserId: {
+                    type: "string",
+                    description: "The ID of the browser instance."
+                },
+                action: {
+                    type: "string",
+                    description: "The DOM action to perform (e.g., 'click', 'type')."
+                },
+                selector: {
+                    type: "string",
+                    description: "The CSS selector of the element to interact with."
+                },
+                text: {
+                    type: "string",
+                    description: "The text to type into the element (if applicable)."
+                }
+            },
+            required: ["browserId", "action", "selector"]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean", description: "Indicates if the DOM action was successful." },
+                browserId: { type: "string", description: "The browser instance ID that was used." }
+            },
+            required: ["success", "browserId"]
+        }
+    };
+
+    async execute(parameters) {
+        const { browserId, action, selector, text } = parameters;
+
+        console.error(`[BrowserDOMTool] Performing ${action} in browser ${browserId} on element: ${selector}`);
+
+        try {
+            switch (action) {
+                case 'click':
+                    await browserService.clickElement(browserId, selector);
+                    break;
+                case 'type':
+                    await browserService.typeText(browserId, selector, text);
+                    break;
+                default:
+                    throw new Error(`Unknown action: ${action}`);
+            }
+
+            console.error(`[BrowserDOMTool] Successfully performed ${action} in browser: ${browserId}`);
+            return { success: true, browserId: browserId };
+        } catch (error) {
+            console.error(`[BrowserDOMTool] Failed to perform ${action}:`, error.message);
+            throw new Error(`Failed to perform ${action} in browser ${browserId}: ${error.message}`);
+        }
+    }
+}
+
+module.exports = BrowserDOMTool;

package/src/tools/browser/launch.js

@@ -0,0 +1,86 @@
+/**
+ * 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 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,289 @@
+/**
+ * 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 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;