@democratize-quality/mcp-server 1.0.0

package/docs/development/adding-tools.md

@@ -0,0 +1,274 @@
+# Developer Guide
+
+A comprehensive guide for extending and contributing to the MCP Browser Control Server.
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Adding New Tools](#adding-new-tools)
+- [Tool Development Best Practices](#tool-development-best-practices)
+- [Configuration System](#configuration-system)
+- [Testing](#testing)
+- [Contributing](#contributing)
+
+## Architecture Overview
+
+The MCP Browser Control Server follows a modular architecture:
+
+```
+src/
+├── tools/
+│   ├── base/
+│   │   ├── ToolBase.js      # Base class for all tools
+│   │   └── ToolRegistry.js  # Tool discovery and management
+│   ├── browser/             # Browser automation tools
+│   └── index.js             # Tool system entry point
+├── services/
+│   └── browserService.js    # Core browser management
+├── config/                  # Configuration management
+└── utils/                   # Utility functions
+```
+
+### Key Components
+
+1. **ToolBase**: Abstract base class providing common functionality
+2. **ToolRegistry**: Manages tool discovery, loading, and execution
+3. **Configuration System**: Environment-based configuration management
+4. **Browser Service**: Core browser automation functionality
+
+## Adding New Tools
+
+### Step 1: Create Tool File
+
+Create a new file in the appropriate category directory:
+
+```javascript
+// src/tools/browser/my-new-tool.js
+const ToolBase = require('../base/ToolBase');
+const browserService = require('../../services/browserService');
+
+class MyNewTool extends ToolBase {
+    static definition = {
+        name: "browser_my_action",
+        description: "Performs a custom browser action",
+        input_schema: {
+            type: "object",
+            properties: {
+                browserId: { 
+                    type: "string", 
+                    description: "Browser instance ID" 
+                },
+                // Add your parameters here
+            },
+            required: ["browserId"]
+        },
+        output_schema: {
+            type: "object",
+            properties: {
+                success: { type: "boolean" },
+                // Add your output fields here
+            },
+            required: ["success"]
+        }
+    };
+
+    async execute(parameters) {
+        const { browserId } = parameters;
+        
+        // Your tool implementation here
+        
+        return { success: true };
+    }
+}
+
+module.exports = MyNewTool;
+```
+
+### Step 2: Tool Discovery
+
+The tool will be automatically discovered and registered when the server starts. No manual registration required!
+
+### Step 3: Add Configuration (Optional)
+
+Add tool-specific configuration in `src/config/tools/`:
+
+```javascript
+// src/config/tools/browser.js
+module.exports = {
+    // ... existing config
+    browser_my_action: {
+        timeout: 5000,
+        retryAttempts: 3,
+        customSetting: 'value'
+    }
+};
+```
+
+### Step 4: Access Configuration in Tool
+
+```javascript
+async execute(parameters) {
+    const timeout = this.getConfig('timeout', 30000);
+    const customSetting = this.getConfig('customSetting');
+    
+    // Use configuration in your tool logic
+}
+```
+
+## Tool Development Best Practices
+
+### 1. Error Handling
+
+```javascript
+async execute(parameters) {
+    try {
+        // Your logic here
+        return result;
+    } catch (error) {
+        // Provide meaningful error messages
+        throw new Error(`Failed to perform action: ${error.message}`);
+    }
+}
+```
+
+### 2. Parameter Validation
+
+Use the JSON schema in the `input_schema` for automatic validation:
+
+```javascript
+static definition = {
+    input_schema: {
+        type: "object",
+        properties: {
+            url: {
+                type: "string",
+                pattern: "^https?://", // Regex validation
+                description: "Must be a valid HTTP/HTTPS URL"
+            },
+            timeout: {
+                type: "number",
+                minimum: 1000,
+                maximum: 60000
+            }
+        }
+    }
+};
+```
+
+### 3. Logging
+
+Use consistent logging patterns:
+
+```javascript
+async execute(parameters) {
+    const toolName = this.constructor.definition.name;
+    const enableDebug = this.config.isFeatureEnabled('enableDebugMode');
+    
+    if (enableDebug) {
+        console.error(`[${toolName}] Starting execution with:, parameters);
+    }
+    
+    // Your logic here
+    
+    if (enableDebug) {
+        console.error(`[${toolName}] Execution completed successfully`);
+    }
+}
+```
+
+### 4. Configuration Usage
+
+```javascript
+async execute(parameters) {
+    // Get tool-specific config with fallback
+    const timeout = this.getConfig('timeout', 30000);
+    const retries = this.getConfig('retryAttempts', 3);
+    
+    // Check feature flags
+    if (this.config.isFeatureEnabled('enableDetailedLogging')) {
+        // Enhanced logging
+    }
+}
+```
+
+## Configuration System
+
+### Environment-Based Configuration
+
+- `development.js` - Development settings
+- `production.js` - Production optimizations
+- `server.js` - Server-level settings
+- `tools/` - Tool-specific configurations
+
+### Environment Variable Overrides
+
+Override any configuration using environment variables:
+
+```bash
+# Feature flags
+MCP_FEATURES_ENABLEBROWSERTOOLS=false
+
+# Tool settings
+MCP_TOOLS_BROWSER_TIMEOUT=60000
+
+# Server settings
+MCP_SERVER_PORT=8080
+```
+
+## Testing
+
+### Unit Testing Tools
+
+```javascript
+// tests/tools/browser/my-tool.test.js
+const MyNewTool = require('../../../src/tools/browser/my-new-tool');
+
+describe('MyNewTool', () => {
+    let tool;
+    
+    beforeEach(() => {
+        tool = new MyNewTool();
+    });
+    
+    test('should validate required parameters', async () => {
+        await expect(tool.run({})).rejects.toThrow('Missing required parameter');
+    });
+    
+    test('should execute successfully with valid parameters', async () => {
+        const result = await tool.run({ browserId: 'test-123' });
+        expect(result.content[0].text).toContain('success');
+    });
+});
+```
+
+### Integration Testing
+
+Test tools with actual browser instances in development environment.
+
+## Contributing
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/my-new-tool`
+3. **Add your tool** following the patterns above
+4. **Add tests** for your tool
+5. **Update documentation** by running `npm run docs:generate`
+6. **Submit a pull request**
+
+### Code Style
+
+- Use descriptive variable names
+- Add JSDoc comments for public methods
+- Follow existing patterns for consistency
+- Use async/await for asynchronous operations
+
+### Commit Messages
+
+- Use conventional commit format: `feat: add new browser tool`
+- Include scope when relevant: `feat(browser): add scroll tool`
+- Use present tense: "add" not "added"
+
+---
+
+*Generated automatically from tool definitions and code analysis*

package/docs/development/configuration.md

@@ -0,0 +1,332 @@
+# Configuration Guide
+
+Comprehensive guide to configuring the MCP Browser Control Server.
+
+---
+
+## Configuration Structure
+
+The configuration system supports multiple sources with clear precedence:
+
+1. **Environment Variables** (highest precedence)
+2. **Environment-specific files** (`environments/`)
+3. **Tool-specific files** (`tools/`)
+4. **Default configuration** (lowest precedence)
+
+```
+src/config/
+├── index.js                 # Configuration manager
+├── server.js                # Server settings
+├── tools/
+│   ├── default.js          # Default tool settings
+│   └── browser.js          # Browser tool settings
+└── environments/
+    ├── development.js      # Development overrides
+    └── production.js       # Production overrides
+```
+
+## Environment Variables
+
+All configuration can be overridden using environment variables with the prefix `MCP_`.
+
+### Format
+`MCP_SECTION_SUBSECTION_KEY=value`
+
+### Examples
+
+```bash
+# Feature flags
+MCP_FEATURES_ENABLEBROWSERTOOLS=false
+MCP_FEATURES_ENABLEDEBUGMODE=true
+
+# Server settings
+MCP_SERVER_PORT=8080
+MCP_SERVER_NAME="custom-server"
+
+# Tool settings
+MCP_TOOLS_BROWSER_TIMEOUT=60000
+MCP_TOOLS_BROWSER_MAXINSTANCES=5
+```
+
+## Feature Flags
+
+Control which tool categories are available:
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `enableBrowserTools` | Browser automation tools | `true` |
+| `enableFileTools` | File system tools | `false` |
+| `enableNetworkTools` | Network tools | `false` |
+| `enableDebugMode` | Debug logging and features | `true` in dev |
+
+### Usage
+
+```bash
+# Environment variable
+MCP_FEATURES_ENABLEBROWSERTOOLS=false node mcpServer.js
+
+# Or in environment config file
+// src/config/environments/production.js
+module.exports = {
+  features: {
+    enableBrowserTools: true,
+    enableDebugMode: false
+  }
+};
+```
+
+## Tool Configuration
+
+### Browser Tools
+
+```javascript
+// src/config/tools/browser.js
+module.exports = {
+  browser_launch: {
+    defaultHeadless: true,
+    maxInstances: 10,
+    launchTimeout: 30000,
+    chromeFlags: [
+      '--disable-gpu',
+      '--no-sandbox'
+    ]
+  },
+  
+  browser_screenshot: {
+    defaultQuality: 80,
+    maxFileSize: '10MB',
+    outputDirectory: './output'
+  }
+};
+```
+
+### Default Tool Settings
+
+Applied to all tools unless overridden:
+
+```javascript
+// src/config/tools/default.js
+module.exports = {
+  timeout: 30000,
+  retryAttempts: 3,
+  enableInputValidation: true,
+  logErrors: true
+};
+```
+
+## Environment-Specific Configuration
+
+### Development
+
+```javascript
+// src/config/environments/development.js
+module.exports = {
+  features: {
+    enableDebugMode: true
+  },
+  
+  tools: {
+    browser: {
+      browser_launch: {
+        defaultHeadless: false, // Show browser UI
+        enableScreenshotOnError: true
+      }
+    }
+  },
+  
+  logging: {
+    level: 'debug'
+  }
+};
+```
+
+### Production
+
+```javascript
+// src/config/environments/production.js
+module.exports = {
+  features: {
+    enableDebugMode: false
+  },
+  
+  tools: {
+    browser: {
+      browser_launch: {
+        defaultHeadless: true,
+        maxInstances: 3 // Conservative limit
+      }
+    }
+  },
+  
+  logging: {
+    level: 'error'
+  }
+};
+```
+
+## Accessing Configuration in Tools
+
+### Basic Access
+
+```javascript
+class MyTool extends ToolBase {
+  async execute(parameters) {
+    // Get tool-specific configuration
+    const timeout = this.getConfig('timeout', 30000);
+    const retries = this.getConfig('retryAttempts', 3);
+    
+    // Check feature flags
+    if (this.config.isFeatureEnabled('enableDebugMode')) {
+      console.error('Debug mode enabled');
+    }
+    
+    // Get global configuration
+    const serverPort = this.config.get('server.port');
+  }
+}
+```
+
+### Configuration Hierarchy
+
+Tools receive configuration in this order:
+1. Tool-specific config (`tools.browser.browser_launch`)
+2. Category config (`tools.browser`)
+3. Default config (`tools.default`)
+
+## Advanced Configuration
+
+### Custom Environments
+
+Create custom environment configurations:
+
+```javascript
+// src/config/environments/testing.js
+module.exports = {
+  tools: {
+    browser: {
+      browser_launch: {
+        defaultHeadless: true,
+        maxInstances: 1,
+        launchTimeout: 10000
+      }
+    }
+  }
+};
+```
+
+Run with custom environment:
+```bash
+NODE_ENV=testing node mcpServer.js
+```
+
+### Runtime Configuration
+
+Some settings can be modified at runtime:
+
+```javascript
+// In your tool
+async execute(parameters) {
+  // Override default timeout for this execution
+  const customTimeout = parameters.timeout || this.getConfig('timeout');
+  
+  // Use custom timeout
+  await this.executeWithTimeout(customTimeout);
+}
+```
+
+### Configuration Validation
+
+The system validates configuration at startup:
+
+```javascript
+// Example validation in tool
+constructor() {
+  super();
+  
+  const maxInstances = this.getConfig('maxInstances');
+  if (maxInstances > 20) {
+    console.warn('maxInstances > 20 may cause performance issues');
+  }
+}
+```
+
+## Configuration Examples
+
+### High-Performance Setup
+
+```bash
+NODE_ENV=production \
+MCP_TOOLS_BROWSER_MAXINSTANCES=2 \
+MCP_TOOLS_BROWSER_LAUNCHTIMEOUT=15000 \
+node mcpServer.js
+```
+
+### Debug Development
+
+```bash
+MCP_FEATURES_ENABLEDEBUGMODE=true \
+MCP_LOGGING_LEVEL=debug \
+MCP_TOOLS_BROWSER_ENABLESCREENSHOTONERROR=true \
+node mcpServer.js
+```
+
+### Minimal Setup
+
+```bash
+MCP_FEATURES_ENABLEFILETOOLS=false \
+MCP_FEATURES_ENABLENETWORKTOOLS=false \
+MCP_TOOLS_BROWSER_MAXINSTANCES=1 \
+node mcpServer.js
+```
+
+## Configuration Reference
+
+### Complete Configuration Schema
+
+```javascript
+{
+  server: {
+    name: 'browser-control-server',
+    version: '1.0.0',
+    port: 3000
+  },
+  
+  features: {
+    enableBrowserTools: true,
+    enableFileTools: false,
+    enableNetworkTools: false,
+    enableDebugMode: true
+  },
+  
+  tools: {
+    autoDiscovery: true,
+    validationLevel: 'strict',
+    
+    // Default settings for all tools
+    default: {
+      timeout: 30000,
+      retryAttempts: 3,
+      enableInputValidation: true
+    },
+    
+    // Browser tool settings
+    browser: {
+      browser_launch: {
+        defaultHeadless: true,
+        maxInstances: 10,
+        launchTimeout: 30000
+      }
+      // ... other browser tools
+    }
+  },
+  
+  logging: {
+    level: 'debug',
+    enableToolDebug: true
+  }
+}
+```
+
+---
+
+*Configuration is loaded at server startup. Restart the server after making changes.*

package/docs/examples/authentication.md

@@ -0,0 +1,124 @@
+# Authentication and Sessions
+
+This example shows how to handle login flows and maintain authenticated sessions.
+
+## Persistent Browser Profile
+
+Use a persistent profile to maintain login sessions:
+
+```json
+// Launch with persistent profile
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_launch",
+    "arguments": {
+      "headless": false,
+      "userDataDir": "./auth-session"
+    }
+  }
+}
+```
+
+## Login Workflow
+
+```json
+// 1. Navigate to login page
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_navigate",
+    "arguments": {
+      "browserId": "browser-123",
+      "url": "https://example.com/login"
+    }
+  }
+}
+
+// 2. Fill username
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_type",
+    "arguments": {
+      "browserId": "browser-123",
+      "locator": { "type": "css", "value": "#username" },
+      "text": "your-username"
+    }
+  }
+}
+
+// 3. Fill password
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_type",
+    "arguments": {
+      "browserId": "browser-123",
+      "locator": { "type": "css", "value": "#password" },
+      "text": "your-password"
+    }
+  }
+}
+
+// 4. Click login button
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_click",
+    "arguments": {
+      "browserId": "browser-123",
+      "locator": { "type": "css", "value": "#login-button" }
+    }
+  }
+}
+
+// 5. Take screenshot to verify login
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_screenshot",
+    "arguments": {
+      "browserId": "browser-123",
+      "fileName": "after-login.png"
+    }
+  }
+}
+```
+
+## Session Reuse
+
+Once authenticated, the session is preserved:
+
+```json
+// Later session - reuse the same profile
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_launch",
+    "arguments": {
+      "headless": true,
+      "userDataDir": "./auth-session"
+    }
+  }
+}
+
+// Navigate to protected page (already authenticated)
+{
+  "method": "tools/call",
+  "params": {
+    "name": "browser_navigate",
+    "arguments": {
+      "browserId": "browser-456",
+      "url": "https://example.com/dashboard"
+    }
+  }
+}
+```
+
+## Tips
+
+- Use non-headless mode for initial login setup
+- Keep the userDataDir consistent across sessions
+- Take screenshots to verify authentication state
+- Handle 2FA and captcha challenges manually when needed