@muggleai/mcp-qa-gateway 1.0.1

package/README.md

@@ -0,0 +1,185 @@
+# MCP QA Gateway
+
+A hosted MCP (Model Context Protocol) 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
+- **Streamable HTTP Transport**: Uses MCP's remote transport for hosted deployment
+- **Rate Limiting**: Configurable rate limits per credential
+- **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
+
+```bash
+# 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
+npm start
+```
+
+### Docker
+
+```bash
+# 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
+
+```bash
+curl http://localhost:3002/health
+```
+
+## Development
+
+```bash
+# 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.
+
+```bash
+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

package/dist/scripts/phase0-smoke.d.ts

@@ -0,0 +1,7 @@
+import { SmokeTestResult } from "./types/phase0-smoke-types.js";
+/**
+ * Execute the Phase 0 MCP QA workflow end-to-end against the gateway.
+ * Returns a structured result instead of throwing errors.
+ */
+export declare function runPhase0SmokeAsync(): Promise<SmokeTestResult>;
+//# sourceMappingURL=phase0-smoke.d.ts.map

package/dist/scripts/phase0-smoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase0-smoke.d.ts","sourceRoot":"","sources":["../../scripts/phase0-smoke.ts"],"names":[],"mappings":"AAoBA,OAAO,EAMH,eAAe,EAWlB,MAAM,+BAA+B,CAAC;AA4SvC;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CA6NpE"}