@democratize-quality/mcp-server 1.0.0

package/docs/examples/basic-automation.md

@@ -0,0 +1,105 @@
+# Basic Browser Automation
+
+This example demonstrates basic browser automation tasks using the Democratize Quality MCP Server.
+
+## Complete Workflow
+
+```json
+// 1. Launch browser
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_launch",
+    "arguments": {
+      "headless": true,
+      "userDataDir": "./browser-session"
+    }
+  }
+}
+
+// Response: { "browserId": "browser-abc123", "port": 9222 }
+
+// 2. Navigate to page
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_navigate",
+    "arguments": {
+      "browserId": "browser-abc123",
+      "url": "https://example.com"
+    }
+  }
+}
+
+// 3. Take screenshot
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_screenshot",
+    "arguments": {
+      "browserId": "browser-abc123",
+      "fileName": "homepage.png"
+    }
+  }
+}
+
+// 4. Extract page content
+{
+  "jsonrpc": "2.0",
+  "id": 4,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_dom",
+    "arguments": {
+      "browserId": "browser-abc123"
+    }
+  }
+}
+
+// 5. Close browser
+{
+  "jsonrpc": "2.0",
+  "id": 5,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_close",
+    "arguments": {
+      "browserId": "browser-abc123"
+    }
+  }
+}
+```
+
+## Error Handling
+
+Always handle errors appropriately:
+
+```json
+// If a tool call fails, you'll receive an error response:
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32000,
+    "message": "Tool 'browser_navigate' execution failed: Browser instance 'invalid-id' not found",
+    "data": {
+      "tool_name": "browser_navigate",
+      "original_error": "Browser instance 'invalid-id' not found"
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Always close browsers** when done to free resources
+2. **Use persistent profiles** for authenticated sessions
+3. **Handle errors gracefully** with retry logic
+4. **Take screenshots** for debugging and verification
+5. **Use meaningful file names** for screenshots

package/docs/getting-started.md

@@ -0,0 +1,214 @@
+# Getting Started
+
+Quick start guide for the Democratize Quality MCP Server.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ 
+- Chrome/Chromium browser
+- Git
+
+### Clone and Setup
+
+```bash
+git clone https://github.com/democratize-quality/mcp-server.git
+cd mcp-server
+npm install
+```
+
+## Basic Usage
+
+### 1. Start the Server
+
+```bash
+node mcpServer.js
+```
+
+The server will start and display available tools:
+
+```
+[Tools] Tool system initialized successfully:
+[Tools] - Total tools: 7
+[Tools] - Available tools: browser_launch, browser_navigate, browser_screenshot, ...
+```
+
+### 2. Connect an MCP Client
+
+The server communicates via JSON-RPC over stdin/stdout. Example client integration:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list"
+}
+```
+
+### 3. Basic Browser Automation
+
+Here's a complete example of launching a browser, navigating to a page, and taking a screenshot:
+
+```json
+// 1. Launch browser
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_launch",
+    "arguments": { "headless": true }
+  }
+}
+
+// 2. Navigate to page
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_navigate",
+    "arguments": {
+      "browserId": "browser-123",
+      "url": "https://example.com"
+    }
+  }
+}
+
+// 3. Take screenshot
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "browser_screenshot",
+    "arguments": {
+      "browserId": "browser-123",
+      "fileName": "example.png"
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Modes
+
+**Development Mode** (default):
+- Shows browser UI
+- Detailed logging
+- Debug features enabled
+
+**Production Mode**:
+```bash
+NODE_ENV=production node mcpServer.js
+```
+- Headless browsers only
+- Minimal logging
+- Optimized performance
+
+### Feature Flags
+
+Disable specific tool categories:
+
+```bash
+# Disable browser tools
+MCP_FEATURES_ENABLEBROWSERTOOLS=false node mcpServer.js
+
+# Run with only specific tools
+MCP_FEATURES_ENABLEFILETOOLS=false \
+MCP_FEATURES_ENABLENETWORKTOOLS=false \
+node mcpServer.js
+```
+
+### Custom Configuration
+
+Create environment-specific configs in `src/config/environments/`:
+
+```javascript
+// src/config/environments/testing.js
+module.exports = {
+  tools: {
+    browser: {
+      browser_launch: {
+        defaultHeadless: true,
+        maxInstances: 1
+      }
+    }
+  }
+};
+```
+
+Run with custom environment:
+```bash
+NODE_ENV=testing node mcpServer.js
+```
+
+## Common Use Cases
+
+### Web Scraping
+1. Launch browser with persistent profile
+2. Navigate to login page
+3. Fill credentials
+4. Navigate to target pages
+5. Extract data
+6. Close browser
+
+### Automated Testing
+1. Launch browser in headless mode
+2. Navigate to application
+3. Perform user interactions
+4. Take screenshots for verification
+5. Assert expected outcomes
+
+### Content Generation
+1. Navigate to webpage
+2. Take full-page screenshots
+3. Extract text content
+4. Generate reports
+
+## Troubleshooting
+
+### Common Issues
+
+**Browser fails to launch:**
+- Ensure Chrome/Chromium is installed
+- Check user permissions
+- Try running with `--no-sandbox` flag
+
+**Tools not loading:**
+- Check feature flags are enabled
+- Verify file permissions
+- Review server logs for errors
+
+**Connection issues:**
+- Ensure proper JSON-RPC formatting
+- Check stdin/stdout communication
+- Verify MCP client implementation
+
+### Debug Mode
+
+Enable detailed logging:
+```bash
+MCP_FEATURES_ENABLEDEBUGMODE=true node mcpServer.js
+```
+
+### Logs Location
+
+- Server logs: stderr output
+- Screenshots: `./output/` directory
+- Browser data: Temporary profiles in system temp
+
+## Next Steps
+
+- [Tool Reference](api/tool-reference.md) - Complete tool documentation
+- [Developer Guide](development/adding-tools.md) - Extend the server
+- [Configuration Guide](development/configuration.md) - Advanced configuration
+- [Examples](examples/) - Real-world usage examples
+
+---
+
+*For more help, check the documentation or open an issue on GitHub.*

package/docs/index.md

@@ -0,0 +1,61 @@
+# Documentation Index
+
+Welcome to the Democratize Quality MCP Server documentation!
+
+## 📚 Table of Contents
+
+### Getting Started
+- [🚀 Getting Started](getting-started.md) - Quick start guide and basic usage
+- [📦 Installation](getting-started.md#installation) - Setup and prerequisites
+
+### API Reference
+- [🔧 Tool Reference](api/tool-reference.md) - Complete documentation for all tools
+- [⚙️ Feature Flags](api/tool-reference.md#feature-flags) - Tool control and configuration
+
+### Development
+- [👨‍💻 Adding Tools](development/adding-tools.md) - Developer guide for extending the server
+- [🏗️ Architecture](development/adding-tools.md#architecture-overview) - System architecture overview
+- [⚙️ Configuration](development/configuration.md) - Advanced configuration options
+- [🧪 Testing](development/adding-tools.md#testing) - Testing guidelines and examples
+
+### Examples
+- [🤖 Basic Automation](examples/basic-automation.md) - Essential browser automation workflows
+- [🔐 Authentication](examples/authentication.md) - Login flows and session management
+
+### Additional Resources
+- [📄 Main README](../README.md) - Project overview and quick reference
+- [📋 Package Info](../package.json) - Project dependencies and scripts
+
+## 🎯 Quick Navigation
+
+### By Use Case
+- **First-time setup**: [Getting Started](getting-started.md)
+- **Tool usage**: [Tool Reference](api/tool-reference.md)
+- **Extending functionality**: [Adding Tools](development/adding-tools.md)
+- **Configuration tuning**: [Configuration Guide](development/configuration.md)
+- **Real-world examples**: [Examples](examples/)
+
+### By Role
+- **🤖 AI Agent Developers**: Start with [Tool Reference](api/tool-reference.md)
+- **🛠️ Server Developers**: Read [Adding Tools](development/adding-tools.md)
+- **⚙️ System Administrators**: Check [Configuration Guide](development/configuration.md)
+- **📊 Integration Teams**: Review [Examples](examples/)
+
+## 🔄 Keeping Documentation Updated
+
+Documentation is automatically generated from the codebase:
+
+```bash
+# Regenerate all documentation
+npm run docs:generate
+
+# Watch for changes and regenerate
+npm run docs:watch
+
+# Clean and regenerate
+npm run docs:clean && npm run docs:generate
+```
+
+---
+
+*Documentation generated automatically from tool definitions and configuration - Last updated: ${new Date().toISOString().split('T')[0]}*

package/mcpServer.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+// mcpServer.js - Democratize Quality MCP Server entry point
+//
+// Debug/Logging Modes:
+// - Production mode (default): NODE_ENV=production or npm start - Minimal logging
+// - Debug mode: MCP_FEATURES_ENABLEDEBUGMODE=true or npm run dev - Detailed logging
+// - Development mode: NODE_ENV=development - Detailed logging (same as debug)
+//
+// The server automatically detects the mode and adjusts logging verbosity accordingly.
+
+const { JSONRPCServer } = require("json-rpc-2.0");
+const browserService = require('./src/services/browserService'); // Keep for shutdown functionality
+const { initializeTools, getToolDefinitions, executeTool } = require('./src/tools');
+const config = require('./src/config');
+
+// Initialize JSON-RPC server
+const server = new JSONRPCServer();
+
+// Check if debug mode is requested via environment variable first
+const debugFromEnv = process.env.MCP_FEATURES_ENABLEDEBUGMODE === 'true' || process.env.NODE_ENV === 'development';
+const isDebugMode = config.get('features.enableDebugMode', false) || debugFromEnv;
+
+// Set quiet mode if not in debug
+config.setQuiet(!isDebugMode);
+
+// Global variable to hold tool definitions after initialization
+let toolDefinitions = [];
+
+// Helper function for debug logging
+function debugLog(...args) {
+    if (isDebugMode) {
+        console.error('[Democratize Quality MCP]', ...args);
+    }
+}
+
+// Helper function for important logs (always shown)
+function log(...args) {
+    console.error('[Democratize Quality MCP]', ...args);
+}
+
+// Initialize the tool system
+async function initializeServer() {
+    try {
+        if (isDebugMode) {
+            log('Initializing tool system...');
+        }
+        await initializeTools(isDebugMode);
+        toolDefinitions = getToolDefinitions();
+        log(`Tool system initialized with ${toolDefinitions.length} tools`);
+    } catch (error) {
+        log('Failed to initialize tool system:', error.message);
+        process.exit(1);
+    }
+}
+
+// --- Register MCP Standard Methods ---
+
+// Initialize method for MCP protocol
+server.addMethod("initialize", async (params) => {
+    debugLog("Received 'initialize' request.");
+    return {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+            tools: {},
+            prompts: {},
+            resources: {}
+        },
+        serverInfo: {
+            name: "browser-control-server",
+            version: "1.0.0"
+        }
+    };
+});
+
+// The `tools/list` method for tool discovery
+// Replace your tools/list method with this Draft 7 compatible version:
+
+server.addMethod("tools/list", async () => {
+    debugLog("Received 'tools/list' request.");
+    
+    // Convert all tool definitions to Claude Desktop compatible format
+    const compatibleTools = toolDefinitions.map(tool => {
+        // Ensure we use the correct property name and clean schema
+        return {
+            name: tool.name,
+            description: tool.description,
+            // Claude Desktop expects 'inputSchema', not 'input_schema'
+            inputSchema: {
+                type: "object",
+                properties: {
+                    // Add minimal properties to avoid empty schema issues
+                    ...((tool.input_schema && tool.input_schema.properties) || {}),
+                    // Fallback to ensure there's always at least one property
+                    ...(Object.keys((tool.input_schema && tool.input_schema.properties) || {}).length === 0 ? {
+                        _placeholder: { type: "string", description: "Placeholder parameter" }
+                    } : {})
+                },
+                // Only add required if it exists and is not empty
+                ...(tool.input_schema && tool.input_schema.required && tool.input_schema.required.length > 0 ? {
+                    required: tool.input_schema.required
+                } : {}),
+                // Ensure no additionalProperties or other Draft 2020-12 features
+                additionalProperties: false
+            }
+        };
+    });
+    
+    debugLog(`Returning ${compatibleTools.length} tools with compatible schemas`);
+    debugLog('First tool schema sample:', JSON.stringify(compatibleTools[0]?.inputSchema, null, 2));
+    
+    return { tools: compatibleTools };
+});
+
+// The `tools/call` method for tool invocation (note: it's tools/call, not tool/call)
+server.addMethod("tools/call", async ({ name, arguments: parameters }) => {
+    debugLog(`Received 'tools/call' for method: ${name} with params: ${JSON.stringify(parameters)}`);
+
+    try {
+        // Use the new tool system to execute the tool
+        const result = await executeTool(name, parameters);
+        return result;
+        
+    } catch (error) {
+        log(`Error executing tool '${name}':`, error.message);
+        
+        // If it's already a properly formatted MCP error, re-throw it
+        if (error.code && error.message) {
+            throw error;
+        }
+        
+        // Otherwise, format it as an MCP error
+        throw {
+            code: -32000,
+            message: `Tool execution failed: ${error.message}`,
+            data: { tool_name: name, original_error: error.message }
+        };
+    }
+});
+
+// The `prompts/list` method for prompt discovery
+server.addMethod("prompts/list", async () => {
+    debugLog("Received 'prompts/list' request.");
+    // This server doesn't provide any prompts, so return an empty array
+    return { prompts: [] };
+});
+
+// The `resources/list` method for resource discovery
+server.addMethod("resources/list", async () => {
+    debugLog("Received 'resources/list' request.");
+    // This server doesn't provide any resources, so return an empty array
+    return { resources: [] };
+});
+
+// Notification methods (these don't return responses)
+server.addMethod("notifications/initialized", async () => {
+    debugLog("Received 'notifications/initialized' notification.");
+    // Notifications don't return responses
+});
+
+server.addMethod("notifications/cancelled", async ({ requestId, reason }) => {
+    debugLog(`Received 'notifications/cancelled' for request ${requestId}: ${reason}`);
+    // Notifications don't return responses
+});
+
+// Add a catch-all method handler for debugging
+server.addMethod("*", async (params, method) => {
+    debugLog(`Unknown method called: ${method}`);
+    throw {
+        code: -32601,
+        message: `Method '${method}' not found`
+    };
+});
+
+// --- STDIO Communication Loop ---
+// This part handles reading JSON-RPC requests from stdin and writing responses to stdout.
+
+let inputBuffer = '';
+
+process.stdin.on('data', (chunk) => {
+    inputBuffer += chunk.toString();
+
+    // Process messages delimited by newline. This is a common pattern for STDIO RPC.
+    // In a production-grade server, you'd want a more robust JSON stream parser
+    // to handle partial messages or multiple messages in one chunk.
+    let newlineIndex;
+    while ((newlineIndex = inputBuffer.indexOf('\n')) !== -1) {
+        const messageString = inputBuffer.substring(0, newlineIndex).trim();
+        inputBuffer = inputBuffer.substring(newlineIndex + 1);
+
+        if (messageString) { // Ensure it's not an empty line
+            try {
+                const jsonRpcRequest = JSON.parse(messageString);
+                debugLog(`Received request: ${JSON.stringify(jsonRpcRequest)}`);
+                
+                // Handle notifications (no response expected)
+                if (!jsonRpcRequest.id && jsonRpcRequest.method && jsonRpcRequest.method.startsWith('notifications/')) {
+                    server.receive(jsonRpcRequest).catch(err => {
+                        log("Error processing notification:", err.message);
+                    });
+                    return; // Don't send a response for notifications
+                }
+                
+                // The receive method handles processing the request and generating a response
+                server.receive(jsonRpcRequest).then((jsonRpcResponse) => {
+                    if (jsonRpcResponse) {
+                        debugLog(`Sending response: ${JSON.stringify(jsonRpcResponse)}`);
+                        // All responses must go to stdout
+                        process.stdout.write(JSON.stringify(jsonRpcResponse) + '\n');
+                    }
+                }).catch(err => {
+                    // Catch errors from receive() if it rejects (e.g., malformed JSON-RPC request)
+                    log("Error processing JSON-RPC request:", err.message);
+                    
+                    // Send an error response if we have an ID
+                    if (jsonRpcRequest.id) {
+                        const errorResponse = {
+                            jsonrpc: "2.0",
+                            error: {
+                                code: -32603,
+                                message: "Internal error",
+                                data: err.message
+                            },
+                            id: jsonRpcRequest.id
+                        };
+                        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+                    }
+                });
+            } catch (parseError) {
+                log("JSON parse error on input:", messageString, parseError);
+                // If the input itself is not valid JSON, we can't get an ID, so ID is null
+                const errorResponse = {
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32700, // Parse error
+                        message: "Parse error"
+                    },
+                    id: null
+                };
+                process.stdout.write(JSON.stringify(errorResponse) + '\n');
+            }
+        }
+    }
+});
+
+// Handle graceful shutdown signals (Ctrl+C, termination)
+process.on('SIGINT', async () => {
+    log('\nSIGINT received. Shutting down...');
+    try {
+        await browserService.shutdownAllBrowsers();
+        log('All browser instances closed. Exiting gracefully.');
+    } catch (err) {
+        log('Error during graceful shutdown:', err.message);
+        process.exit(1); // Exit with error code
+    }
+    process.exit(0); // Exit successfully
+});
+
+process.on('SIGTERM', async () => {
+    log('\nSIGTERM received. Shutting down...');
+    try {
+        await browserService.shutdownAllBrowsers();
+        log('All browser instances closed. Exiting gracefully.');
+    } catch (err) {
+        log('Error during graceful shutdown:', err.message);
+        process.exit(1);
+    }
+    process.exit(0);
+});
+
+// Initialize the server and start listening
+(async () => {
+    await initializeServer();
+    
+    // Initial message to indicate server is ready (to stderr)
+    log(`Server started. Waiting for input on stdin.`);
+    if (isDebugMode) {
+        log(`To integrate with a host, provide the command: node ${__filename}`);
+        log(`Debug mode enabled - showing detailed logs`);
+    }
+})();