@democratize-quality/mcp-server 1.2.0 → 1.2.1

package/src/server.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * 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/>.
+ */
+
+
+/**
+ * @democratize-quality/mcp-server
+ * Main MCP server implementation for API testing and browser automation
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import * as path from 'path';
+
+// Import existing CommonJS modules - use paths relative to project root
+// When compiled, this will be in dist/, so we need to go up one level to find src/
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const browserService = require(path.join(__dirname, '..', 'src', 'services', 'browserService.js'));
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const toolsModule = require(path.join(__dirname, '..', 'src', 'tools', 'index.js'));
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const config = require(path.join(__dirname, '..', 'src', 'config', 'index.js'));
+
+interface ServerConfig {
+  enableDebugMode?: boolean;
+  enableApiTools?: boolean;
+  enableBrowserTools?: boolean;
+  enableAdvancedTools?: boolean;
+}
+
+class DemocratizeQualityMCPServer {
+  private server: Server;
+  private toolDefinitions: any[] = [];
+  private config: ServerConfig;
+  private isDebugMode: boolean;
+
+  constructor(serverConfig: ServerConfig = {}) {
+    // Check if debug mode is requested via environment variable
+    const debugFromEnv = process.env.MCP_FEATURES_ENABLEDEBUGMODE === 'true' || 
+                          process.env.NODE_ENV === 'development';
+    
+    this.isDebugMode = config.get('features.enableDebugMode', false) || debugFromEnv || serverConfig.enableDebugMode || false;
+    
+    // Set quiet mode if not in debug
+    config.setQuiet(!this.isDebugMode);
+
+    this.config = serverConfig;
+
+    // Initialize MCP Server with SDK
+    this.server = new Server(
+      {
+        name: '@democratize-quality/mcp-server',
+        version: '1.2.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private debugLog(...args: any[]): void {
+    if (this.isDebugMode) {
+      console.error('[Democratize Quality MCP]', ...args);
+    }
+  }
+
+  private log(...args: any[]): void {
+    console.error('[Democratize Quality MCP]', ...args);
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      this.debugLog(`Received 'tools/list' request.`);
+      this.debugLog(`Returning ${this.toolDefinitions.length} tools`);
+      
+      return {
+        tools: this.getAvailableTools(),
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      this.debugLog(`Received 'tools/call' for method: ${name}`);
+
+      try {
+        // Use the existing tool system to execute the tool
+        const result = await toolsModule.executeTool(name, args || {});
+        
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        this.log(`Error executing tool '${name}':`, (error as Error).message);
+        
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error executing ${name}: ${(error as Error).message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  private getAvailableTools(): Tool[] {
+    // Convert existing tool definitions to MCP SDK format
+    return this.toolDefinitions.map((tool) => {
+      const sdkTool: Tool = {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: {
+          type: 'object' as const,
+          properties: tool.input_schema?.properties || tool.inputSchema?.properties || {},
+          ...(tool.input_schema?.required && tool.input_schema.required.length > 0
+            ? { required: tool.input_schema.required }
+            : {}),
+        },
+      };
+      return sdkTool;
+    });
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      this.debugLog('Initializing tool system...');
+      
+      // Initialize the existing tool system
+      await toolsModule.initializeTools(this.isDebugMode);
+      
+      // Get tool definitions from the existing system
+      this.toolDefinitions = toolsModule.getToolDefinitions();
+      
+      this.log(`Tool system initialized with ${this.toolDefinitions.length} tools`);
+      
+    } catch (error) {
+      this.log('Failed to initialize tool system:', (error as Error).message);
+      throw error;
+    }
+  }
+
+  async start(): Promise<void> {
+    // Initialize tools first
+    await this.initialize();
+    
+    // Create transport and connect
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    
+    this.log('Server started and ready');
+    if (this.isDebugMode) {
+      this.log('Debug mode enabled - showing detailed logs');
+    }
+  }
+
+  async stop(): Promise<void> {
+    try {
+      await browserService.shutdownAllBrowsers();
+      this.log('All browser instances closed');
+    } catch (error) {
+      this.log('Error during shutdown:', (error as Error).message);
+    }
+  }
+}
+
+// Main entry point
+async function main(): Promise<void> {
+  const server = new DemocratizeQualityMCPServer();
+
+  // Handle graceful shutdown
+  process.on('SIGINT', async () => {
+    console.error('\nSIGINT received. Shutting down...');
+    await server.stop();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', async () => {
+    console.error('\nSIGTERM received. Shutting down...');
+    await server.stop();
+    process.exit(0);
+  });
+
+  try {
+    await server.start();
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+// Start the server if this file is being executed directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+  });
+}
+
+export { DemocratizeQualityMCPServer };

package/src/services/browserService.js

@@ -0,0 +1,344 @@
+/**
+ * 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 CDP = require('chrome-remote-interface');
+//const launchChrome = require('chrome-launcher').launch;
+const fs = require('fs');
+const path = require('path');
+const { findNodeBySelector, getElementClickCoordinates } = require('../utils/browserHelpers'); // Import helpers
+const config = require('../config');
+
+// A private in-memory store for our browser instances within the service
+// Each key will be a unique browserId, value will be { chromeInstance, cdpClient, userDataDir }
+const activeBrowsers = {};
+
+/**
+ * Ensures a user data directory exists.
+ * @param {string} dirPath - The absolute path to the user data directory.
+ */
+function ensureUserDataDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        console.log(`[BrowserService] Created user data directory: ${dirPath}`);
+    } else {
+        console.log(`[BrowserService] Using existing user data directory: ${dirPath}`);
+    }
+}
+
+/**
+ * Retrieves a browser instance by ID.
+ * @param {string} browserId - The ID of the browser instance.
+ * @returns {object|null} - The browser instance object or null if not found.
+ */
+function getBrowserInstance(browserId) {
+    return activeBrowsers[browserId];
+}
+
+/**
+ * Launches a new Chrome instance.
+ * @param {boolean} headless - Whether to run Chrome in headless mode.
+ * @param {number} port - The port for remote debugging.
+ * @param {string|null} userDataDir - Path to the user data directory for persistent profiles.
+ * @returns {Promise<object>} - Object containing browserId, port, and resolvedUserDataDir.
+ */
+async function launchBrowser(headless, port, userDataDir) {
+    let chrome;
+    let client;
+    const { launch: launchChrome } = await import('chrome-launcher');
+    let resolvedUserDataDir = null;
+
+    try {
+        if (userDataDir) {
+            resolvedUserDataDir = path.resolve(process.cwd(), userDataDir);
+            ensureUserDataDir(resolvedUserDataDir);
+        }
+
+        console.log(`[BrowserService] Launching Chrome (headless: ${headless}, userDataDir: ${resolvedUserDataDir || 'temporary'})...`);
+
+        const launchOptions = {
+            port: port,
+            userDataDir: resolvedUserDataDir, // Set userDataDir if provided
+            chromeFlags: [
+                headless ? '--headless=new' : '',
+                '--disable-gpu',
+                '--disable-setuid-sandbox',
+                '--no-sandbox'
+            ].filter(Boolean)
+        };
+
+        chrome = await launchChrome(launchOptions);
+
+        // Generate browserId: profile-name if userDataDir is used, otherwise a unique timestamped ID
+        const browserId = userDataDir ? `profile-${path.basename(resolvedUserDataDir)}` : `browser-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+
+        if (activeBrowsers[browserId]) {
+            console.warn(`[BrowserService] Warning: Browser ID '${browserId}' already exists. Overwriting.`);
+            // In a real scenario, you might want more sophisticated handling here,
+            // e.g., error if ID exists, or try to attach to existing.
+            // For now, we're assuming a new launch means a fresh start or overwrite.
+            try { // Attempt to clean up old instance if it exists
+                if (activeBrowsers[browserId].cdpClient) activeBrowsers[browserId].cdpClient.close();
+                if (activeBrowsers[browserId].chromeInstance) await activeBrowsers[browserId].chromeInstance.kill();
+            } catch (cleanupErr) {
+                console.error(`[BrowserService] Error cleaning up old instance for ${browserId}:`, cleanupErr.message);
+            }
+        }
+
+        activeBrowsers[browserId] = { chromeInstance: chrome, cdpClient: null, userDataDir: resolvedUserDataDir };
+        console.log(`[BrowserService] Chrome launched on port ${chrome.port} with ID: ${browserId}`);
+
+        client = await CDP({ port: chrome.port });
+        activeBrowsers[browserId].cdpClient = client;
+
+        const { Page, Runtime, DOM, Network, Security, Input } = client; // Enable Input domain here
+        await Page.enable();
+        await Runtime.enable();
+        await DOM.enable();
+        await Network.enable();
+        await Security.enable();
+        //await Input.enable(); // Enable Input domain
+
+        console.log(`[BrowserService] CDP client connected and domains enabled for ${browserId}.`);
+
+        return { browserId, port: chrome.port, userDataDir: resolvedUserDataDir };
+
+    } catch (error) {
+        console.error(`[BrowserService] Error launching browser:`, error);
+        if (chrome && !client) { // If chrome launched but CDP connection failed
+            try {
+                await chrome.kill();
+                console.log(`[BrowserService] Partially launched Chrome instance killed due to error.`);
+            } catch (killError) {
+                console.error(`[BrowserService] Error killing partially launched Chrome:`, killError);
+            }
+        }
+        throw error; // Re-throw to be caught by the route handler
+    }
+}
+
+/**
+ * Navigates a specific browser instance to a URL.
+ * @param {string} browserId - The ID of the browser instance.
+ * @param {string} url - The URL to navigate to.
+ * @returns {Promise<void>}
+ */
+async function navigateBrowser(browserId, url) {
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { cdpClient } = instance;
+    console.log(`[BrowserService] Browser ${browserId} navigating to: ${url}`);
+    await cdpClient.Page.navigate({ url: url });
+    await cdpClient.Page.loadEventFired(); // Wait for page to load
+    console.log(`[BrowserService] Browser ${browserId} successfully navigated to ${url}.`);
+}
+
+/**
+ * Takes a screenshot of a specific browser page and can save it to disk.
+ * @param {string} browserId - The ID of the browser instance.
+ * @param {string} [fileName='screenshot.png'] - Optional: The name of the file to save the screenshot as.
+ * @param {boolean} [saveToDisk=true] - Optional: Whether to save the screenshot to disk.
+ * @returns {Promise<string>} - Base64 encoded screenshot data.
+ */
+async function takeScreenshot(browserId, fileName = 'screenshot.png', saveToDisk = true) { // Added fileName and saveToDisk params
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { cdpClient } = instance;
+    console.log(`[BrowserService] Taking screenshot for browser ${browserId}...`);
+    const screenshot = await cdpClient.Page.captureScreenshot({ format: 'png', quality: 80 });
+
+    if (saveToDisk) {
+        const screenshotBuffer = Buffer.from(screenshot.data, 'base64');
+        // Ensure the output directory exists
+        if (!fs.existsSync(config.OUTPUT_DIR)) {
+            fs.mkdirSync(config.OUTPUT_DIR, { recursive: true });
+        }
+        const filePath = path.join(config.OUTPUT_DIR, fileName);
+        fs.writeFileSync(filePath, screenshotBuffer);
+        console.log(`[BrowserService] Screenshot saved to ${filePath}`);
+    }
+
+    console.log(`[BrowserService] Screenshot captured for browser ${browserId}.`);
+    return screenshot.data; // Always return base64 data to the caller (e.g., AI agent)
+}
+
+/**
+ * Gets the current DOM content of a specific browser page.
+ * @param {string} browserId - The ID of the browser instance.
+ * @returns {Promise<string>} - The outer HTML of the document.
+ */
+async function getDomContent(browserId) {
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { cdpClient } = instance;
+    console.log(`[BrowserService] Getting DOM for browser ${browserId}...`);
+    const documentNode = await cdpClient.DOM.getDocument({ depth: -1 });
+    const outerHTML = await cdpClient.DOM.getOuterHTML({ nodeId: documentNode.root.nodeId });
+    console.log(`[BrowserService] DOM content retrieved for browser ${browserId}.`);
+    return outerHTML.outerHTML;
+}
+
+/**
+ * Clicks an element identified by a locator.
+ * @param {string} browserId - The ID of the browser instance.
+ * @param {object} locator - { type: 'css'|'xpath', value: 'selector' }
+ * @returns {Promise<object>} - Coordinates of the click.
+ */
+async function clickElement(browserId, locator) {
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { cdpClient } = instance;
+    const { Input } = cdpClient;
+
+    console.log(`[BrowserService] Browser ${browserId}: Attempting to click element with locator:`, locator);
+
+    const nodeId = await findNodeBySelector(cdpClient, locator.type, locator.value);
+    if (!nodeId) {
+        throw new Error(`Element not found for locator: ${JSON.stringify(locator)}`);
+    }
+
+    const coords = await getElementClickCoordinates(cdpClient, nodeId);
+    if (!coords) {
+        throw new Error(`Could not determine click coordinates for element: ${JSON.stringify(locator)}`);
+    }
+
+    await Input.dispatchMouseEvent({
+        type: 'mousePressed',
+        button: 'left',
+        x: coords.x,
+        y: coords.y,
+        clickCount: 1
+    });
+    await Input.dispatchMouseEvent({
+        type: 'mouseReleased',
+        button: 'left',
+        x: coords.x,
+        y: coords.y,
+        clickCount: 1
+    });
+
+    console.log(`[BrowserService] Browser ${browserId}: Clicked element at x: ${coords.x}, y: ${coords.y}`);
+    return coords;
+}
+
+/**
+ * Types text into an element identified by a locator.
+ * @param {string} browserId - The ID of the browser instance.
+ * @param {object} locator - { type: 'css'|'xpath', value: 'selector' }
+ * @param {string} text - The text to type.
+ * @returns {Promise<void>}
+ */
+async function typeIntoElement(browserId, locator, text) {
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { cdpClient } = instance;
+    const { DOM, Input } = cdpClient;
+
+    console.log(`[BrowserService] Browser ${browserId}: Attempting to type "${text}" into element with locator:`, locator);
+
+    const nodeId = await findNodeBySelector(cdpClient, locator.type, locator.value);
+    if (!nodeId) {
+        throw new Error(`Element not found for locator: ${JSON.stringify(locator)}`);
+    }
+
+    await DOM.focus({ nodeId: nodeId });
+    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay for focus
+
+    // Clear existing text: Cmd/Ctrl+A then Backspace
+    await Input.dispatchKeyEvent({ type: 'keyDown', text: 'a', modifiers: (process.platform === 'darwin' ? 4 : 2) }); // 4 for Meta (Cmd), 2 for Control
+    await Input.dispatchKeyEvent({ type: 'keyUp', text: 'a', modifiers: (process.platform === 'darwin' ? 4 : 2) });
+    await Input.dispatchKeyEvent({ type: 'keyDown', key: 'Backspace' });
+    await Input.dispatchKeyEvent({ type: 'keyUp', key: 'Backspace' });
+    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay for clear
+
+    for (const char of text) {
+        await Input.dispatchKeyEvent({ type: 'keyDown', text: char, key: char });
+        await Input.dispatchKeyEvent({ type: 'keyUp', text: char, key: char });
+        await new Promise(resolve => setTimeout(resolve, 10)); // Small delay for realism
+    }
+
+    console.log(`[BrowserService] Browser ${browserId}: Typed "${text}" into element.`);
+}
+
+/**
+ * Closes a specific browser instance.
+ * @param {string} browserId - The ID of the browser instance.
+ * @returns {Promise<void>}
+ */
+async function closeBrowser(browserId) {
+    const instance = getBrowserInstance(browserId);
+    if (!instance) throw new Error(`Browser instance with ID '${browserId}' not found.`);
+
+    const { chromeInstance, cdpClient, userDataDir } = instance;
+
+    console.log(`[BrowserService] Closing browser ${browserId} (profile: ${userDataDir || 'temporary'})...`);
+    if (cdpClient) {
+        try {
+            cdpClient.close();
+            console.log(`[BrowserService] CDP client disconnected for ${browserId}.`);
+        } catch (err) {
+            console.warn(`[BrowserService] Error during CDP client close for ${browserId}:`, err.message);
+        }
+    }
+    if (chromeInstance) {
+        try {
+            await chromeInstance.kill();
+            console.log(`[BrowserService] Chrome instance ${browserId} killed.`);
+        } catch (err) {
+            console.warn(`[BrowserService] Error during Chrome instance kill for ${browserId}:`, err.message);
+        }
+    }
+    delete activeBrowsers[browserId]; // Remove from our store
+    console.log(`[BrowserService] Browser ${browserId} removed from active list.`);
+}
+
+/**
+ * Shuts down all active browser instances. Used for graceful server shutdown.
+ * @returns {Promise<void>}
+ */
+async function shutdownAllBrowsers() {
+    const browserIds = Object.keys(activeBrowsers);
+    if (browserIds.length === 0) {
+        console.log('[BrowserService] No active browsers to shut down.');
+        return;
+    }
+    console.log(`[BrowserService] Shutting down ${browserIds.length} active browser(s)...`);
+    await Promise.all(browserIds.map(id => closeBrowser(id).catch(err => {
+        console.error(`[BrowserService] Failed to gracefully close browser ${id}:`, err.message);
+        // Continue with other shutdowns even if one fails
+    })));
+    console.log('[BrowserService] All active browsers shut down.');
+}
+
+
+module.exports = {
+    launchBrowser,
+    navigateBrowser,
+    getBrowserInstance,
+    takeScreenshot,
+    getDomContent,
+    clickElement,
+    typeIntoElement,
+    closeBrowser,
+    shutdownAllBrowsers // Export for server.js to use
+};