@muggleai/mcp-qa-gateway

MCP QA Gateway

A Model Context Protocol (MCP) server that exposes Muggle Test QA APIs as MCP tools. This gateway enables AI assistants and MCP clients to run end-to-end QA analysis workflows on websites.

Features

• E2E URL Analysis: Complete workflow from project setup to test report generation
• Multi-tenant Auth: Forwards caller credentials (Auth0 JWT or API key) to prompt-service
• Dual Transport Modes:
  • HTTP: Hosted server for remote access (default)
  • Stdio: Local subprocess for direct agent integration
• Rate Limiting: Configurable rate limits per credential (HTTP mode)
• Docker Ready: Production-optimized container image

Quick Start

Prerequisites

• Node.js 18+
• Access to Muggle AI prompt-service
• Valid API key or Auth0 credentials

Installation from npm

# Install globally
npm install -g @muggleai/mcp-qa-gateway

# Run in stdio mode (for local agent integration)
MCP_API_KEY=mai_sk_xxx PROMPT_SERVICE_BASE_URL=https://promptservice.muggle-ai.com mcp-qa-gateway --stdio

# Run in HTTP mode (hosted server)
PROMPT_SERVICE_BASE_URL=https://promptservice.muggle-ai.com mcp-qa-gateway

Installation from Source

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your PROMPT_SERVICE_BASE_URL

# Build
npm run build

# Start (HTTP mode)
npm start

# Start (stdio mode)
npm start -- --stdio

Transport Modes

Stdio Mode (Recommended for Local Agents)

In stdio mode, the gateway runs as a subprocess of your AI agent. The agent communicates via stdin/stdout using the MCP protocol.

Pros:

• No network latency
• Credentials managed by the agent
• Session context stays with agent

Configuration for Claude Desktop / Cursor:

{
  "mcpServers": {
    "muggle-qa": {
      "command": "npx",
      "args": ["@muggleai/mcp-qa-gateway", "--stdio"],
      "env": {
        "PROMPT_SERVICE_BASE_URL": "https://promptservice.muggle-ai.com",
        "MCP_API_KEY": "mai_sk_your_api_key_here"
      }
    }
  }
}

HTTP Mode (For Hosted Deployment)

In HTTP mode, the gateway runs as an HTTP server that accepts remote connections.

Pros:

• Single server for multiple agents
• Centralized logging/monitoring
• Rate limiting per credential

# Start HTTP server
PROMPT_SERVICE_BASE_URL=https://promptservice.muggle-ai.com npm start

# Connect from MCP client
curl -X POST http://localhost:3002/mcp \
  -H "Content-Type: application/json" \
  -H "x-api-key: mai_sk_xxx" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Docker

# Build image
docker build -t mcp-qa-gateway .

# Run container
docker run -p 3002:3002 \
  -e PROMPT_SERVICE_BASE_URL=https://promptservice.muggle-ai.com \
  -e RATE_LIMIT_ENABLED=true \
  mcp-qa-gateway

Configuration

Environment Variable	Description	Default
PROMPT_SERVICE_BASE_URL	Base URL of prompt-service (required)	-
PORT	Server port	3002
MCP_PUBLIC_BASE_URL	Public URL of this gateway	http://localhost:3002
NODE_ENV	Environment (development/staging/production)	development
LOG_LEVEL	Log level (debug/info/warn/error)	info
RATE_LIMIT_ENABLED	Enable rate limiting	true
RATE_LIMIT_WINDOW_SECONDS	Rate limit window	60
RATE_LIMIT_MAX_REQUESTS	Max requests per window	60
REQUEST_TIMEOUT_MS	Default request timeout	30000
WORKFLOW_TIMEOUT_MS	Workflow request timeout	120000

Authentication

The gateway requires authentication on every request. Provide one of:

• Bearer Token: Authorization: Bearer <Auth0_JWT>
• API Key: x-api-key: mai_sk_...

Credentials are forwarded unchanged to prompt-service, which enforces authorization.

Available Tools

Phase 0: E2E URL Analysis (Current)

Project Initialization

• qa_project_create - Create a new QA project
• qa_project_get - Get project details
• qa_project_update - Update project
• qa_project_list - List projects
• qa_prd_file_upload - Upload PRD document
• qa_prd_file_list_by_project - List PRD files
• qa_workflow_start_prd_file_process - Start PRD processing workflow
• qa_workflow_get_prd_file_process_latest_run - Get PRD processing status
• qa_secret_create/get/update/delete/list - Manage credentials

Use Case Discovery

• qa_use_case_discovery_memory_get - Get discovered use case candidates
• qa_use_case_candidates_approve - Approve candidates into use cases
• qa_use_case_list/get - List and view use cases

Workflow Execution

• qa_workflow_start_website_scan - Start website scan workflow
• qa_workflow_start_test_case_detection - Generate test cases
• qa_workflow_start_test_script_generation - Generate test scripts
• qa_workflow_start_test_script_replay - Execute test script
• qa_workflow_start_test_script_replay_bulk - Execute multiple scripts
• qa_workflow_*_latest_run - Get workflow status
• qa_workflow_cancel_* - Cancel workflows

Artifact Inspection

• qa_test_case_list/get - View test cases
• qa_test_script_list/get - View test scripts
• qa_project_test_*_summary_get - View summaries

Reports & Delivery

• qa_report_stats_summary_get - Get report statistics
• qa_report_preferences_upsert - Configure delivery (email/sms/webhook)
• qa_report_final_generate - Generate final report

Recommendations (No Side Effects)

• qa_recommend_schedule - Get scheduling recommendations
• qa_recommend_cicd_setup - Get CI/CD integration templates

Typical Workflow

1. qa_project_create          → Create project
2. qa_workflow_start_website_scan → Discover use cases from URL
3. qa_use_case_discovery_memory_get → Review candidates
4. qa_use_case_candidates_approve → Approve selected use cases
5. qa_workflow_start_test_case_detection → Generate test cases
6. qa_workflow_start_test_script_generation → Generate scripts
7. qa_workflow_start_test_script_replay_bulk → Run all tests
8. qa_report_final_generate   → Generate report
9. qa_report_preferences_upsert → Configure delivery

MCP Endpoint

The MCP protocol endpoint is available at:

POST/GET/DELETE http://localhost:3002/mcp

Headers:

• Content-Type: application/json
• Authorization: Bearer <token> or x-api-key: <key>

Health Check

curl http://localhost:3002/health

Development

# Watch mode
npm run dev

# Lint
npm run lint

# Build
npm run build

Phase 0 Smoke Runner (scripts/phase0-smoke.ts)

Run an end-to-end Phase 0 workflow against the gateway and prompt-service.

cd mcp-gateway
MCP_GATEWAY_BASE_URL=http://localhost:3002 \
MCP_GATEWAY_AUTH_TOKEN="Bearer <jwt>" \   # or MCP_GATEWAY_API_KEY=mai_sk_...
MCP_QA_WEBSITE_URL=https://example.com \
MCP_QA_SCAN_DESCRIPTION="Smoke scan" \
MCP_QA_PROJECT_ID=<existing> \            # or set MCP_QA_PROJECT_NAME + MCP_QA_PROJECT_DESCRIPTION to create
npx tsx scripts/phase0-smoke.ts

Optional env:

• MCP_QA_TEST_REQUIREMENTS
• MCP_QA_ARCHIVE_UNAPPROVED=true
• MCP_QA_PRD_FILE_PATH (+ MCP_QA_PRD_CONTENT_TYPE)
• MCP_QA_REPORT_CHANNELS (comma, e.g., email,sms,webhook) + MCP_QA_REPORT_EMAILS, MCP_QA_REPORT_PHONES, MCP_QA_REPORT_WEBHOOK_URL

License

MIT