@democratize-quality/mcp-server 1.0.0

package/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+/**
+ * Democratize Quality MCP Server CLI
+ * Can be run via npx @democratize-quality/mcp-server
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Handle CLI arguments
+const args = process.argv.slice(2);
+const isHelp = args.includes('--help') || args.includes('-h');
+const isVersion = args.includes('--version') || args.includes('-v');
+
+if (isVersion) {
+    const packageJson = require('./package.json');
+    console.log(`Democratize Quality MCP Server v${packageJson.version}`);
+    process.exit(0);
+}
+
+if (isHelp) {
+    console.log(`
+🎯 Democratize Quality MCP Server
+
+A comprehensive MCP server for democratizing quality through browser automation and API testing.
+
+Usage:
+  npx @democratize-quality/mcp-server [options]
+  democratize-quality-mcp [options]
+  dq-mcp-server [options]
+
+Options:
+  --help, -h                Show this help
+  --version, -v             Show version
+  --debug                   Enable debug mode
+  --port <number>           Set server port
+  --env <environment>       Set environment (development|production|api-only)
+  
+Tool Category Options:
+  --api-only                Enable only API tools (shortcut for api-only environment)
+  --browser-only            Enable only browser tools
+  --no-api                  Disable API tools
+  --no-browser              Disable browser tools
+  --no-advanced             Disable advanced browser tools
+  --enable-all              Enable all tool categories (default in development)
+
+Environment Variables:
+  MCP_FEATURES_ENABLEAPITOOLS=true/false        Enable/disable API tools
+  MCP_FEATURES_ENABLEBROWSERTOOLS=true/false    Enable/disable browser tools
+  MCP_FEATURES_ENABLEADVANCEDTOOLS=true/false   Enable/disable advanced tools
+  NODE_ENV=api-only                             Use API-only configuration
+
+Integration with Claude Desktop:
+Add this to ~/Library/Application Support/Claude/claude_desktop_config.json
+
+{
+  "mcpServers": {
+    "democratize-quality": {
+      "command": "npx",
+      "args": ["@democratize-quality/mcp-server"]
+    }
+  }
+}
+
+Or if installed globally:
+{
+  "mcpServers": {
+    "democratize-quality": {
+      "command": "democratize-quality-mcp"
+    }
+  }
+}
+
+Available Tools: 20
+• Browser Automation (17): launch, navigate, click, type, screenshot, pdf, etc.
+• API Testing (3): request, session status, HTML reports
+
+GitHub: https://github.com/democratize-quality/mcp-server
+`);
+    process.exit(0);
+}
+
+// Set up environment
+const env = { ...process.env };
+
+// Handle debug flag
+if (args.includes('--debug')) {
+    env.MCP_FEATURES_ENABLEDEBUGMODE = 'true';
+    env.NODE_ENV = 'development';
+}
+
+// Handle environment flag
+const envIndex = args.indexOf('--env');
+if (envIndex !== -1 && args[envIndex + 1]) {
+    env.NODE_ENV = args[envIndex + 1];
+}
+
+// Handle tool category flags
+if (args.includes('--api-only')) {
+    env.NODE_ENV = 'api-only';
+} else if (args.includes('--browser-only')) {
+    env.MCP_FEATURES_ENABLEAPITOOLS = 'false';
+    env.MCP_FEATURES_ENABLEBROWSERTOOLS = 'true';
+    env.MCP_FEATURES_ENABLEADVANCEDTOOLS = 'true';
+    env.MCP_FEATURES_ENABLEFILETOOLS = 'false';
+    env.MCP_FEATURES_ENABLENETWORKTOOLS = 'false';
+    env.MCP_FEATURES_ENABLEOTHERTOOLS = 'false';
+} else if (args.includes('--enable-all')) {
+    env.MCP_FEATURES_ENABLEAPITOOLS = 'true';
+    env.MCP_FEATURES_ENABLEBROWSERTOOLS = 'true';
+    env.MCP_FEATURES_ENABLEADVANCEDTOOLS = 'true';
+    env.MCP_FEATURES_ENABLEFILETOOLS = 'true';
+    env.MCP_FEATURES_ENABLENETWORKTOOLS = 'true';
+    env.MCP_FEATURES_ENABLEOTHERTOOLS = 'true';
+}
+
+// Handle individual tool category disable flags
+if (args.includes('--no-api')) {
+    env.MCP_FEATURES_ENABLEAPITOOLS = 'false';
+}
+if (args.includes('--no-browser')) {
+    env.MCP_FEATURES_ENABLEBROWSERTOOLS = 'false';
+}
+if (args.includes('--no-advanced')) {
+    env.MCP_FEATURES_ENABLEADVANCEDTOOLS = 'false';
+}
+
+// Handle port flag
+const portIndex = args.indexOf('--port');
+if (portIndex !== -1 && args[portIndex + 1]) {
+    env.PORT = args[portIndex + 1];
+}
+
+// Ensure output directory exists
+// When run via npx/Claude, process.cwd() might be root, so use home directory or temp
+const defaultOutputDir = env.HOME 
+    ? path.join(env.HOME, '.mcp-browser-control') 
+    : path.join(os.tmpdir(), 'mcp-browser-control');
+    
+const outputDir = env.OUTPUT_DIR || defaultOutputDir;
+if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+}
+env.OUTPUT_DIR = outputDir;
+
+// Debug output (if enabled)
+if (args.includes('--debug')) {
+    console.error(`📁 Output directory: ${outputDir}`);
+    console.error(`🏠 Working directory: ${process.cwd()}`);
+    console.error(`🌍 Environment: ${env.NODE_ENV || 'development'}`);
+    console.error(`🔧 Tool Categories:`);
+    console.error(`   API Tools: ${env.MCP_FEATURES_ENABLEAPITOOLS || 'default'}`);
+    console.error(`   Browser Tools: ${env.MCP_FEATURES_ENABLEBROWSERTOOLS || 'default'}`);
+    console.error(`   Advanced Tools: ${env.MCP_FEATURES_ENABLEADVANCEDTOOLS || 'default'}`);
+}
+
+// Start the MCP server
+const serverPath = path.join(__dirname, 'mcpServer.js');
+const serverProcess = spawn('node', [serverPath], {
+    env,
+    stdio: 'inherit'
+});
+
+// Handle process cleanup
+const cleanup = (signal) => {
+    console.error(`\nReceived ${signal}, shutting down gracefully...`);
+    serverProcess.kill(signal);
+};
+
+process.on('SIGINT', () => cleanup('SIGINT'));
+process.on('SIGTERM', () => cleanup('SIGTERM'));
+
+serverProcess.on('error', (error) => {
+    console.error('Failed to start CDP Browser Control MCP Server:', error.message);
+    process.exit(1);
+});
+
+serverProcess.on('exit', (code, signal) => {
+    if (signal) {
+        process.exit(0);
+    } else {
+        process.exit(code || 0);
+    }
+});

package/docs/api/tool-reference.md

@@ -0,0 +1,317 @@
+# Tool Reference
+
+Complete reference for all available tools
+
+---
+
+## Table of Contents
+
+- [Browser Tools](#browser-tools)
+  - [browser_click](#browser-click)
+  - [browser_close](#browser-close)
+  - [browser_dom](#browser-dom)
+  - [browser_launch](#browser-launch)
+  - [browser_navigate](#browser-navigate)
+  - [browser_screenshot](#browser-screenshot)
+  - [browser_type](#browser-type)
+
+## Browser Tools
+
+Tools for browser automation and control.
+
+### browser_click
+
+**Description:** Simulates a click on a specific element in the browser.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance. |
+| `selector` | string | ✅ | The CSS selector of the element to click. |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Indicates if the click was successful. |
+| `browserId` | string | The browser instance ID that was used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_click",
+  "parameters": {
+    "browserId": "browser-123",
+    "locator": {
+      "type": "css",
+      "value": "#submit-button"
+    }
+  }
+}
+```
+
+*Click a button using CSS selector*
+
+
+---
+
+### browser_close
+
+**Description:** Closes a specific browser instance and cleans up its resources. Always call this when done with a browser.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance to close. |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | string | Confirmation message of successful closure. |
+| `browserId` | string | The browser instance ID that was closed. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_close",
+  "parameters": {
+    "browserId": "example"
+  }
+}
+```
+
+*Basic usage example*
+
+
+---
+
+### browser_dom
+
+**Description:** Interacts with the DOM of the current browser page.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance. |
+| `action` | string | ✅ | The DOM action to perform (e.g., 'click', 'type'). |
+| `selector` | string | ✅ | The CSS selector of the element to interact with. |
+| `text` | string | ❌ | The text to type into the element (if applicable). |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Indicates if the DOM action was successful. |
+| `browserId` | string | The browser instance ID that was used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_dom",
+  "parameters": {
+    "browserId": "example",
+    "action": "example",
+    "selector": "example"
+  }
+}
+```
+
+*Basic usage example*
+
+
+---
+
+### browser_launch
+
+**Description:** Launches a new web browser instance. Returns a unique browserId. Use this before any other browser actions.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `headless` | boolean | ❌ | Whether to launch the browser in headless mode (no UI). Defaults to true. Set to false for manual login. |
+| `userDataDir` | string | ❌ | 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` | number | ❌ | Optional. The port for remote debugging. If not provided, Chrome will choose an available port. |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `browserId` | string | The unique ID of the launched browser instance. |
+| `port` | number | The port the browser instance is running on for remote debugging. |
+| `userDataDir` | string | The absolute path to the user data directory used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_launch",
+  "parameters": {
+    "headless": true
+  }
+}
+```
+
+*Launch a headless browser instance*
+
+```json
+{
+  "tool": "browser_launch",
+  "parameters": {
+    "headless": false,
+    "userDataDir": "./my_profile"
+  }
+}
+```
+
+*Launch browser with custom profile for authenticated sessions*
+
+
+---
+
+### browser_navigate
+
+**Description:** Navigates a specific browser instance to a given URL.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance to navigate. |
+| `url` | string | ✅ | The URL to navigate to. Must include protocol (http:// or https://). |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | string | Confirmation message of successful navigation. |
+| `url` | string | The URL that was navigated to. |
+| `browserId` | string | The browser instance ID that was used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_navigate",
+  "parameters": {
+    "browserId": "browser-123",
+    "url": "https://example.com"
+  }
+}
+```
+
+*Navigate to a website*
+
+
+---
+
+### browser_screenshot
+
+**Description:** Captures a screenshot of the current browser page. Returns base64 encoded image data. Optionally saves to disk.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance. |
+| `fileName` | string | ❌ | 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` | boolean | ❌ | Optional. Whether to save the screenshot to disk on the server. Defaults to true. Set to false to only receive base64 data. |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `imageData` | string | Base64 encoded PNG image data. |
+| `format` | string | Image format (e.g., 'png'). |
+| `fileName` | string | The file name if saved to disk. |
+| `browserId` | string | The browser instance ID that was used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_screenshot",
+  "parameters": {
+    "browserId": "browser-123",
+    "fileName": "page-capture.png"
+  }
+}
+```
+
+*Take a screenshot and save it*
+
+
+---
+
+### browser_type
+
+**Description:** Types text into a specific input field in the browser.
+
+#### Input Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `browserId` | string | ✅ | The ID of the browser instance. |
+| `selector` | string | ✅ | The CSS selector of the input field. |
+| `text` | string | ✅ | The text to type into the input field. |
+
+#### Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Indicates if the typing was successful. |
+| `browserId` | string | The browser instance ID that was used. |
+
+#### Example Usage
+
+```json
+{
+  "tool": "browser_type",
+  "parameters": {
+    "browserId": "browser-123",
+    "locator": {
+      "type": "css",
+      "value": "#email-input"
+    },
+    "text": "user@example.com"
+  }
+}
+```
+
+*Type text into an input field*
+
+
+---
+
+
+## Feature Flags
+
+Tools can be enabled or disabled using feature flags:
+
+| Feature Flag | Environment Variable | Description |
+|--------------|---------------------|-------------|
+| `enableBrowserTools` | `MCP_FEATURES_ENABLEBROWSERTOOLS` | Enable/disable all browser automation tools |
+| `enableFileTools` | `MCP_FEATURES_ENABLEFILETOOLS` | Enable/disable file system tools |
+| `enableNetworkTools` | `MCP_FEATURES_ENABLENETWORKTOOLS` | Enable/disable network tools |
+| `enableDebugMode` | `MCP_FEATURES_ENABLEDEBUGMODE` | Enable/disable debug mode |
+
+### Usage Examples
+
+```bash
+# Disable browser tools
+MCP_FEATURES_ENABLEBROWSERTOOLS=false node mcpServer.js
+
+# Run in production mode
+NODE_ENV=production node mcpServer.js
+
+# Enable debug mode
+MCP_FEATURES_ENABLEDEBUGMODE=true node mcpServer.js
+```
+