uppadhyayraj/democratize-quality-mcp-server

🎯 Democratize Quality MCP Server

A comprehensive Model Context Protocol (MCP) server that democratizes quality through comprehensive API testing capabilities.

🤖 API Testing Agents for GitHub Copilot

Introducing intelligent API testing agents that work seamlessly with GitHub Copilot Chat to automate your API testing workflow - from planning to generation to healing.

🚀 One-Click Installation

Get started instantly with our VS Code integration:

Choose your installation: Install the core server for direct tool access. Agent button installs chatmode files for GitHub Copilot Chat integration.

Run following command in your project:

# Install MCP Server + Agents (Recommended)
npx @democratize-quality/mcp-server --agents

🎭 Meet Your API Testing Agents

Once installed, these agents become available in GitHub Copilot Chat:

🔄 Complete API Testing Workflow

1. Plan → 2. Generate → 3. Heal → Repeat

# 1. Analyze your API and create a comprehensive test plan
@🌐 api-planner analyze our REST API using the OpenAPI spec at /docs/api-spec.yaml

# 2. Generate executable tests from the plan
@🌐 api-generator create Playwright tests from the generated test plan

# 3. If tests fail, automatically heal them
@🌐 api-healer fix any failing tests and update assertions to match current API behavior

✨ Key Agent Capabilities

• 🔍 Schema Analysis: Automatically parse OpenAPI/Swagger specs and GraphQL schemas
• 📋 Intelligent Planning: Generate comprehensive test scenarios covering functional, security, and edge cases
• ⚡ Multi-Format Generation: Create Jest, Playwright, and Postman tests from the same plan
• 🛠️ Automatic Healing: Detect and fix common test failures like changed endpoints, updated schemas, and authentication issues
• 🔗 Workflow Integration: Seamlessly work together to maintain your API test suite

🎬 See It In Action

Coming soon: Video demonstration of the complete API testing workflow

📋 Overview

This MCP server offers 6 powerful API testing tools for comprehensive API quality assurance:

🤖 AI-Powered API Testing Tools

• api_planner: Analyze API schemas and generate comprehensive test plans
• api_generator: Generate executable tests (Jest, Playwright, Postman) from test plans
• api_healer: Debug and automatically fix failing API tests

🔗 Core API Testing Tools

• api_request: HTTP requests with validation and session management
• api_session_status: Query API test session status and logs
• api_session_report: Generate comprehensive HTML test reports

Key Features:

• 🤖 AI-Powered Agents: Intelligent test planning, generation, and healing
• ✅ Enhanced Validation: Shows "expected vs actual" values in validation failures
• 🔗 Request Chaining: Use response data in subsequent requests
• 📊 Session Management: Track API test sequences across multiple requests
• 📈 HTML Reports: Beautiful, interactive test reports with detailed validation results
• 🎯 Comprehensive Testing: Support for all HTTP methods with advanced validation options

⚡️ Installation & Setup

Prerequisites

• Node.js 14+
• VS Code with GitHub Copilot extension (for agents)
• MCP-compatible client (Claude Desktop, VS Code, etc.)

🎭 Agent Installation (Recommended)

For GitHub Copilot Users:

The fastest way to get started with API testing agents:

# Install agents in your VS Code project
npx @democratize-quality/mcp-server --agents

This will:

• 📁 Copy chatmode files to .github/chatmodes/
• ⚙️ Set up MCP configuration in .vscode/mcp.json
• 🎯 Enable @🌐 api-planner, @🌐 api-generator, and @🌐 api-healer agents

Alternative one-click installation:

For GitHub Copilot Agents:

🛠️ Manual Installation Options

Option 1: Use with npx (Recommended)

# Run directly without installation
npx @democratize-quality/mcp-server --help

# Use in Claude Desktop (see integration section below)

Option 2: Global Installation

# Install globally 
npm install -g @democratize-quality/mcp-server

# Then run anywhere
democratize-quality-mcp --help
dq-mcp-server --help

Option 3: Local Development

# Clone and install dependencies
git clone https://github.com/uppadhyayraj/democratize-quality-mcp-server.git
cd mcp-server
npm install

# Test the server
npm test

# Start the server (API-only mode by default)
npm start

🔌 Integration Methods

Claude Desktop Integration (Recommended)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "democratize-quality": {
      "command": "npx",
      "args": ["@democratize-quality/mcp-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Note: The server runs in api-only mode by default, providing secure and lightweight API testing capabilities.

Alternative Integration Methods

Global Installation:

npm install -g @democratize-quality/mcp-server

Then configure Claude Desktop:

{
  "mcpServers": {
    "democratize-quality": {
      "command": "democratize-quality-mcp"
    }
  }
}

MCP Inspector (Development/Testing):

npx @modelcontextprotocol/inspector npx @democratize-quality/mcp-server

Direct Usage:

# Run the server directly
npx @democratize-quality/mcp-server

# Or if installed globally
democratize-quality-mcp

📚 Usage Examples

🤖 Agent-Powered API Testing Workflow

Complete end-to-end API testing with intelligent agents:

# 1. 🔍 Analyze API and create comprehensive test plan
@🌐 api-planner analyze our user management API using the OpenAPI spec at https://api.example.com/swagger.json

# 2. ⚡ Generate executable tests in multiple formats
@🌐 api-generator create Jest and Playwright tests from the generated test plan

# 3. 🛠️ Automatically heal any failing tests
@🌐 api-healer fix the failing authentication tests in ./tests/user-api.test.js

Individual agent usage:

# API Planning Agent
@🌐 api-planner create a test plan for our REST API with authentication, CRUD operations, and error handling scenarios

# Test Generation Agent  
@🌐 api-generator generate Postman collection from ./docs/api-test-plan.md with authentication setup

# Test Healing Agent
@🌐 api-healer analyze and fix all failing tests in ./tests/ directory with detailed healing report

🎯 Real-World Agent Scenarios

Scenario 1: New API Testing

# Start with schema analysis
@🌐 api-planner analyze the GraphQL schema at /graphql/schema and create comprehensive test scenarios

# Generate tests for multiple environments
@🌐 api-generator create Jest tests with environment-specific configurations for dev, staging, and prod

# Heal tests after API changes
@🌐 api-healer update tests to handle the new authentication flow and endpoint changes

Scenario 2: Legacy API Modernization

# Document existing API behavior
@🌐 api-planner explore and document our legacy API endpoints by testing various HTTP methods

# Create modern test suite
@🌐 api-generator create comprehensive Playwright tests with modern async/await patterns

# Fix compatibility issues
@🌐 api-healer resolve test failures caused by API versioning and deprecated endpoints

🔧 Manual API Testing (Core Tools)

When you need direct control over API testing:

Basic API Testing

// Single API request with validation
await tools.api_request({
  method: "GET", 
  url: "https://jsonplaceholder.typicode.com/users/1",
  expect: { 
    status: 200,
    contentType: "application/json"
  }
})

Advanced API Testing with Session Management

// 1. Start a test session
await tools.api_request({
  sessionId: "user-workflow-test",
  method: "POST", 
  url: "https://jsonplaceholder.typicode.com/users",
  data: {
    name: "John Doe",
    email: "john@example.com"
  },
  expect: { status: 201 }
})

// 2. Follow up request in same session
await tools.api_request({
  sessionId: "user-workflow-test",
  method: "GET",
  url: "https://jsonplaceholder.typicode.com/users/1",
  expect: { 
    status: 200,
    body: { name: "John Doe" }
  }
})

// 3. Generate comprehensive HTML report
await tools.api_session_report({
  sessionId: "user-workflow-test",
  outputPath: "user_workflow_test_report.html"
})

Request Chaining Example

// Chain requests using response data
await tools.api_request({
  sessionId: "chained-test",
  chain: [
    {
      name: "create_user",
      method: "POST",
      url: "https://jsonplaceholder.typicode.com/users",
      data: { name: "Jane Doe", email: "jane@example.com" },
      expect: { status: 201 },
      extract: { userId: "id" }
    },
    {
      name: "get_user",
      method: "GET", 
      url: "https://jsonplaceholder.typicode.com/users/{{ create_user.userId }}",
      expect: { 
        status: 200,
        body: { name: "Jane Doe" }
      }
    }
  ]
})

📖 For comprehensive API testing examples and advanced usage patterns, see:

⚙️ Configuration

Environment Settings

The server runs in API-only mode by default for secure, lightweight deployments focused on API testing.

NODE_ENV=production                    # Default: API-only mode
OUTPUT_DIR=./output                   # Output directory for reports
MCP_FEATURES_ENABLEDEBUGMODE=true     # Enable debug logging

Command Line Options

npx @democratize-quality/mcp-server [options]

Options:
  --help, -h                Show help
  --version, -v             Show version
  --agents                  Install GitHub Copilot Chat agents and VS Code MCP configuration
  --agents --rollback       Rollback agents installation (future feature)
  --debug                   Enable debug mode
  --verbose                 Enable verbose output (useful with --agents)
  --port <number>           Set server port

Agent Installation Options

# Install agents with default settings
npx @democratize-quality/mcp-server --agents

# Install with verbose output
npx @democratize-quality/mcp-server --agents --verbose

# Future: Rollback installation
npx @democratize-quality/mcp-server --agents --rollback

Configuration Examples

VS Code MCP Configuration (Auto-generated by --agents)

When you run npx @democratize-quality/mcp-server --agents, this configuration is automatically created in .vscode/mcp.json:

{
  "servers": {
    "democratize-quality": {
      "type": "stdio",
      "command": "npx",
      "args": ["@democratize-quality/mcp-server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "NODE_ENV": "production",
        "OUTPUT_DIR": "./api-test-reports"
      }
    }
  },
  "inputs": []
}

Note: If you already have an mcp.json file, the installation will safely merge the configuration and create a backup.

Basic Claude Desktop Configuration

{
  "mcpServers": {
    "democratize-quality": {
      "command": "npx",
      "args": ["@democratize-quality/mcp-server"],
      "env": {
        "OUTPUT_DIR": "~/api-test-reports"
      }
    }
  }
}

Debug Mode Configuration

{
  "mcpServers": {
    "democratize-quality": {
      "command": "npx",
      "args": ["@democratize-quality/mcp-server", "--debug"],
      "env": {
        "MCP_FEATURES_ENABLEDEBUGMODE": "true"
      }
    }
  }
}

Output Directory Behavior

• VS Code/Local: Uses ./output in your project directory
• Claude Desktop: Uses ~/.mcp-browser-control (in your home directory)
• Custom: Set OUTPUT_DIR environment variable to specify location

Note: API test reports and session data will be saved to the configured output directory.

🔧 Troubleshooting

Agent Installation Issues

1. Agents not appearing in GitHub Copilot Chat

• Ensure you've restarted VS Code after running --agents installation
• Check that .vscode/mcp.json was created in your project root
• Verify GitHub Copilot extension is installed and enabled
• Try refreshing the workspace: Ctrl/Cmd + Shift + P → "Developer: Reload Window"

2. "democratize-quality server not found" error

• Check the MCP configuration in .vscode/mcp.json
• Ensure the server is running: Test with npx @democratize-quality/mcp-server --help
• Try manual installation: Copy .github/chatmodes/ files and recreate .vscode/mcp.json

3. Agent installation overwrites existing MCP config

• The installer creates automatic backups with timestamps
• Restore from backup: .vscode/mcp.json.backup.{timestamp}
• The installer safely merges configurations, preserving existing servers

4. Permission errors during installation

• Run with elevated permissions if needed: sudo npx @democratize-quality/mcp-server --agents
• Check directory permissions for .github/ and .vscode/ folders
• Ensure you have write access to the project directory

Common Issues

1. "No such file or directory: mkdir /mcp-output"

• This happens when Claude Desktop runs the server with restricted permissions
• The server automatically creates ~/.mcp-browser-control in your home directory
• API test reports will be saved there instead of your project folder

2. Output files not appearing in expected location

• Check the actual output directory: ~/.mcp-browser-control/
• You can set a custom location with: OUTPUT_DIR=/your/custom/path

3. Server not starting in Claude Desktop

• Verify the npx package is published: npx @democratize-quality/mcp-server --help
• Check Claude Desktop logs for detailed error messages
• Try running directly in terminal first to test functionality

4. API validation failures not showing details

• The enhanced validation feature shows "expected vs actual" values
• Check the generated HTML reports for detailed comparison views
• Enable debug mode for more detailed logging

Debug Mode

# Enable debug output with CLI tool
npx @democratize-quality/mcp-server --debug

# Or via environment variable
MCP_FEATURES_ENABLEDEBUGMODE=true node mcpServer.js

Logging Levels:

• Production Mode: Shows only essential startup messages and errors
• Debug Mode: Shows detailed API request/response logs and validation details

🔍 Advanced API Testing Features

🤖 AI-Powered Testing Agents

• 🧠 Intelligent Planning: Automatically analyze API schemas and generate comprehensive test scenarios
• ⚡ Multi-Format Generation: Create Jest, Playwright, and Postman tests from the same test plan
• 🛠️ Automatic Healing: Detect and fix authentication issues, endpoint changes, and schema updates
• 🔍 Schema Analysis: Parse OpenAPI/Swagger specs and GraphQL schemas automatically
• 🎯 End-to-End Workflow: Complete testing pipeline from planning to generation to maintenance

🔧 Core Testing Capabilities

• 📊 Session Management: Track API test sequences across multiple requests
• 🔗 Request Chaining: Use response data from one request in subsequent requests
• ✅ Enhanced Validation: Shows "expected vs actual" values when validation fails
• 📈 Interactive Reports: Beautiful HTML test reports with detailed validation results
• 🎯 Comprehensive Testing: Support for all HTTP methods (GET, POST, PUT, DELETE, PATCH, etc.)
• 🔄 Response Extraction: Extract and reuse data from API responses
• 📝 Detailed Logging: Complete request/response logging for debugging

📄 License

ISC License

Ready to democratize quality through comprehensive API testing with MCP! 🎯

📚 Documentation

• - Quick start guide
• - Complete tool documentation
• - Comprehensive API testing examples and patterns
• - Extending the server
• - Advanced configuration
• - Real-world usage examples

🏗️ Architecture

src/
├── tools/api/      # API testing tools
├── config/         # Configuration management
└── utils/          # Utility functions

Key Features

• Automatic Tool Discovery: API tools are automatically loaded and registered
• Configuration System: Environment-based configuration with sensible defaults
• Error Handling: Comprehensive error handling and validation with detailed reporting
• Session Management: Track and manage API test sessions

🔧 Development

Adding New API Tools

1. Create tool file in src/tools/api/
2. Extend ToolBase class
3. Define tool schema and implementation
4. Tools are automatically discovered!

Example API Tool

class MyApiTool extends ToolBase {
  static definition = {
    name: "my_api_tool",
    description: "Performs API testing operations",
    input_schema: { /* JSON schema */ },
    output_schema: { /* JSON schema */ }
  };

  async execute(parameters) {
    // API tool implementation
    return { success: true, data: responseData };
  }
}

🧪 Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

🔒 Security Considerations

Default Security Posture

• API-Only Mode: Enabled by default for secure, lightweight deployments
• HTTP Requests: All API requests are performed using standard HTTP libraries
• No File System Access: API tools don't access local file system (except for report generation)
• No Browser Automation: No browser processes are launched in API-only mode

Production Deployment Recommendations

{
  "mcpServers": {
    "democratize-quality": {
      "command": "npx",
      "args": ["@democratize-quality/mcp-server"],
      "env": {
        "NODE_ENV": "production",
        "OUTPUT_DIR": "~/api-test-reports"
      }
    }
  }
}

Security Levels

• 🟢 Low Risk: API Tools - HTTP requests with validation and reporting

Best Practices

1. Secure Output Directory: Ensure output directories have appropriate permissions
2. Regular Updates: Keep the package updated for security patches
3. Environment Separation: Use different configurations for development vs production
4. Monitoring: Enable debug mode during initial deployment to monitor API usage

📄 License

[License Type] - see file for details

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes with tests
4. Update documentation
5. Submit a pull request

📞 Support

• Issues - Bug reports and feature requests
• Discussions - Questions and community support
• - Comprehensive guides and references

Ready to democratize quality through intelligent API testing agents! 🎯

Generated automatically from tool definitions and configuration