{"id":33265979,"url":"https://github.com/desplega-ai/qa-use","last_synced_at":"2026-01-18T09:29:05.654Z","repository":{"id":316956208,"uuid":"1065384876","full_name":"desplega-ai/qa-use","owner":"desplega-ai","description":"MCP server for Web UI E2E testing","archived":false,"fork":false,"pushed_at":"2025-12-12T14:31:36.000Z","size":21640,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T05:53:53.109Z","etag":null,"topics":["browser-automation","llm-code","mcp","mcp-server","mcp-tools","qa-automation","qa-automation-test","qatools","testing","testing-tools","vibecoding","webapp"],"latest_commit_sha":null,"homepage":"https://desplega.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/desplega-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T16:07:35.000Z","updated_at":"2025-12-12T14:31:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"7a5dc8c6-0667-496a-aba4-6ad598f132c5","html_url":"https://github.com/desplega-ai/qa-use","commit_stats":null,"previous_names":["desplega-ai/qa-use"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/desplega-ai/qa-use","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desplega-ai%2Fqa-use","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desplega-ai%2Fqa-use/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desplega-ai%2Fqa-use/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desplega-ai%2Fqa-use/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/desplega-ai","download_url":"https://codeload.github.com/desplega-ai/qa-use/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/desplega-ai%2Fqa-use/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-automation","llm-code","mcp","mcp-server","mcp-tools","qa-automation","qa-automation-test","qatools","testing","testing-tools","vibecoding","webapp"],"created_at":"2025-11-17T07:00:34.358Z","updated_at":"2026-01-18T09:29:05.644Z","avatar_url":"https://github.com/desplega-ai.png","language":"TypeScript","funding_links":[],"categories":["Browser Automation","📦 Other"],"sub_categories":["AI Automation"],"readme":"# QA-Use MCP Server\n\nAn MCP (Model Context Protocol) server that provides comprehensive browser automation and QA testing capabilities. This server integrates with desplega.ai to offer automated testing, session monitoring, batch test execution, and intelligent test guidance using AAA (Arrange-Act-Assert) framework templates.\n\n**Modes:**\n- 📟 **stdio** - Standard MCP transport for local integrations (default)\n- 🌐 **HTTP/SSE** - StreamableHTTP transport for remote access and web integrations\n- 🔄 **tunnel** - Persistent WebSocket tunnel for backend-initiated tasks\n\n[![QA-Use Demo](static/demo-thumbnail.png)](https://www.youtube.com/watch?v=ts3XsYneiO4)\n\n\u003e **Learn more:** Check out our comprehensive [MCP integration guide](https://www.desplega.ai/how-to/mcp) for detailed setup instructions and advanced usage patterns.\n\n## Quick Start\n\n```bash\n# Run with stdio transport (for MCP clients)\nnpx @desplega.ai/qa-use-mcp\n\n# Run with HTTP transport (for web/remote access)\nnpx @desplega.ai/qa-use-mcp --http --port 3000\n\n# Run persistent tunnel (for backend-initiated tasks)\nnpx @desplega.ai/qa-use-mcp tunnel\n```\n\n\u003e **For AI Assistants:** See [CLAUDE.md](./CLAUDE.md) for a concise onboarding guide with quick commands, architecture overview, and key concepts.\n\n\u003e **Package Managers:** This project uses **pnpm** as the primary package manager (per `packageManager` field in package.json). **Bun** is used only for test execution and CI speed. Both lock files are maintained for compatibility.\n\n## Table of Contents\n\n- [MCP Client Configuration (stdio mode)](#mcp-client-configuration-stdio-mode)\n- [HTTP Transport Mode (SSE)](#http-transport-mode-sse)\n- [Tunnel Mode](#tunnel-mode)\n- [Features](#features)\n- [Installation](#installation)\n- [Development](#development)\n- [Available Tools](#available-tools)\n\n## MCP Client Configuration (stdio mode)\n\nThe server requires a desplega.ai API key - you can get one by using the `register_user` tool or by signing up at [desplega.ai](https://desplega.ai).\n\n**Standard configuration for most MCP clients:**\n\n```json\n{\n  \"mcpServers\": {\n    \"desplega-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@desplega.ai/qa-use-mcp@latest\"],\n      \"env\": {\n        \"QA_USE_API_KEY\": \"your-desplega-ai-api-key\"\n      }\n    }\n  }\n}\n```\n\n\u003e **Optional:** Add `\"QA_USE_REGION\": \"us\"` to the `env` section to use the US region for faster tunnel connections from North America. If not set, defaults to automatic region selection.\n\n\u003cdetails\u003e\n  \u003csummary\u003eClaude Code\u003c/summary\u003e\n    Use the Claude Code CLI to add the QA-Use MCP server (\u003ca href=\"https://docs.anthropic.com/en/docs/claude-code/mcp\"\u003eguide\u003c/a\u003e):\n\n```bash\nclaude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest --env QA_USE_API_KEY=your-desplega-ai-api-key\n```\n\nFor US region (optional):\n```bash\nclaude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest --env QA_USE_API_KEY=your-desplega-ai-api-key --env QA_USE_REGION=us\n```\n\nOr add without environment variables and configure them later through the interactive setup:\n\n```bash\nclaude mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eClaude Desktop\u003c/summary\u003e\n  Add to your \u003ccode\u003eclaude_desktop_config.json\u003c/code\u003e:\n\n```json\n{\n  \"mcpServers\": {\n    \"desplega-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@desplega.ai/qa-use-mcp@latest\"],\n      \"env\": {\n        \"QA_USE_API_KEY\": \"your-desplega-ai-api-key\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCline\u003c/summary\u003e\n  Follow \u003ca href=\"https://docs.cline.bot/mcp/configuring-mcp-servers\"\u003ehttps://docs.cline.bot/mcp/configuring-mcp-servers\u003c/a\u003e and use the config provided above.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCodex\u003c/summary\u003e\n  Follow the \u003ca href=\"https://github.com/openai/codex/blob/main/docs/advanced.md#model-context-protocol-mcp\"\u003econfigure MCP guide\u003c/a\u003e\n  using the standard config from above. You can also install the QA-Use MCP server using the Codex CLI:\n\n```bash\ncodex mcp add desplega-qa -- npx @desplega.ai/qa-use-mcp@latest\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCopilot / VS Code\u003c/summary\u003e\n  Follow the MCP install \u003ca href=\"https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server\"\u003eguide\u003c/a\u003e,\n  with the standard config from above. You can also install the QA-Use MCP server using the VS Code CLI:\n\n  ```bash\n  code --add-mcp '{\"name\":\"desplega-qa\",\"command\":\"npx\",\"args\":[\"-y\",\"@desplega.ai/qa-use-mcp@latest\"],\"env\":{\"QA_USE_API_KEY\":\"your-desplega-ai-api-key\"}}'\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eCursor\u003c/summary\u003e\n\n**Or install manually:**\n\nGo to `Cursor Settings` -\u003e `MCP` -\u003e `New MCP Server`. Use the config provided above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eContinue\u003c/summary\u003e\n  Add to your Continue \u003ccode\u003econfig.json\u003c/code\u003e:\n\n```json\n{\n  \"mcpServers\": {\n    \"desplega-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@desplega.ai/qa-use-mcp@latest\"],\n      \"env\": {\n        \"QA_USE_API_KEY\": \"your-desplega-ai-api-key\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eGemini CLI\u003c/summary\u003e\nInstall the QA-Use MCP server using the Gemini CLI.\n\n**Project wide:**\n\n```bash\ngemini mcp add desplega-qa npx @desplega.ai/qa-use-mcp@latest\n```\n\n**Globally:**\n\n```bash\ngemini mcp add -s user desplega-qa npx @desplega.ai/qa-use-mcp@latest\n```\n\nAlternatively, follow the \u003ca href=\"https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server\"\u003eMCP guide\u003c/a\u003e and use the standard config from above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eGemini Code Assist\u003c/summary\u003e\n  Follow the \u003ca href=\"https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers\"\u003econfigure MCP guide\u003c/a\u003e\n  using the standard config from above.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eJetBrains AI Assistant \u0026 Junie\u003c/summary\u003e\n\nGo to `Settings | Tools | AI Assistant | Model Context Protocol (MCP)` -\u003e `Add`. Use the config provided above.\nThe same way @desplega.ai/qa-use-mcp can be configured for JetBrains Junie in `Settings | Tools | Junie | MCP Settings` -\u003e `Add`. Use the config provided above.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eZed\u003c/summary\u003e\n  Add to your Zed settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"desplega-qa\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@desplega.ai/qa-use-mcp@latest\"],\n      \"env\": {\n        \"QA_USE_API_KEY\": \"your-desplega-ai-api-key\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Your first prompt\n\nEnter the following prompt in your MCP Client to check if everything is working:\n\n```\nInitialize QA server and test the login form at https://app.example.com\n```\n\nYour MCP client should initialize the server, set up browser automation, and start testing the specified form.\n\n\u003e [!NOTE]\n\u003e The MCP server will start browser and tunnel resources automatically when needed. First-time setup requires running `init_qa_server` with `interactive=true` or providing your desplega.ai API key.\n\n## Features\n\n- **Browser Management**: Launch and control Playwright browser instances with headless/headed modes\n- **Tunneling**: Create public tunnels for browser WebSocket endpoints using localtunnel\n- **API Integration**: Full integration with desplega.ai API for comprehensive QA testing workflows\n- **Session Management**: Create, monitor, and control multiple QA testing sessions with real-time status\n  - Smart session lifecycle management with automatic cleanup\n  - Up to 10 concurrent browser sessions with clear error handling\n  - 30-minute default TTL with automatic deadline refresh on interaction\n  - Background cleanup task for expired sessions\n- **Progress Monitoring**: Real-time progress notifications with MCP timeout protection (25s max per call)\n- **Batch Test Execution**: Run multiple automated tests simultaneously with dependency management\n- **Interactive Elicitation**: Intelligent prompts when remote sessions need user input to continue\n- **Test Discovery**: Search and list automated tests with pagination and filtering\n- **Test Run Analytics**: View test execution history with performance metrics and flakiness scores\n- **AAA Framework Templates**: Pre-built prompts for login, forms, e-commerce, navigation, and comprehensive testing scenarios\n- **User Registration**: Built-in user registration system for new desplega.ai accounts\n- **Comprehensive Documentation**: Built-in MCP resources with guides, workflows, and best practices\n\n## HTTP Transport Mode (SSE)\n\nIn addition to the standard MCP stdio transport, QA-Use can run with StreamableHTTP transport using Server-Sent Events (SSE). This mode implements the official [MCP Streamable HTTP specification](https://spec.modelcontextprotocol.io/specification/basic/transports/#http-with-sse) and is useful for web-based integrations, remote access, or when you need HTTP-based MCP connectivity.\n\n### When to Use Each Mode\n\n| Feature | stdio (default) | HTTP/SSE | Tunnel |\n|---------|----------------|----------|---------|\n| **Use Case** | Local MCP clients (Claude Desktop, Cline, etc.) | Web apps, remote access, API integrations | Backend-initiated tasks, CI/CD |\n| **Setup** | Configured in MCP client settings | Start server, connect via HTTP | Single command, auto-registers |\n| **Authentication** | Via environment variables | Bearer token on each request | Via environment variables |\n| **Network** | Local process only | Can be exposed remotely | Tunneled to backend |\n| **Protocol** | Native MCP stdio | MCP over HTTP with SSE | WebSocket via localtunnel |\n| **Browser** | On-demand | On-demand | Persistent with heartbeat |\n| **Best For** | Desktop IDE integrations | Microservices, web dashboards, custom clients | Backend-controlled testing, CI/CD pipelines |\n\n### Starting the HTTP Server\n\nRun the server with the `--http` or `--api` flag:\n\n```bash\n# Default port (3000)\nnpx @desplega.ai/qa-use-mcp --http\n\n# Custom port\nnpx @desplega.ai/qa-use-mcp --http --port 8080\n\n# Show help\nnpx @desplega.ai/qa-use-mcp --help\n```\n\n### Authentication\n\nAll MCP endpoints (except `/health`) require authentication via Bearer token with a valid desplega.ai API key:\n\n```bash\n# Establish SSE connection\ncurl -N -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  http://localhost:3000/mcp\n```\n\nGet your API key by:\n- Using the `register_user` tool\n- Signing up at [desplega.ai](https://desplega.ai)\n\n### MCP Endpoints\n\nThis server implements the [MCP Streamable HTTP transport specification](https://spec.modelcontextprotocol.io/specification/basic/transports/#http-with-sse):\n\n#### Health Check\n```bash\nGET /health\n# No authentication required\n# Returns server status and version\n```\n\n#### MCP Protocol Endpoint\n```bash\n# Establish SSE connection for receiving messages\nGET /mcp\nHeaders: Authorization: Bearer YOUR_API_KEY\n\n# Send JSON-RPC messages to the server\nPOST /mcp\nHeaders:\n  Authorization: Bearer YOUR_API_KEY\n  Content-Type: application/json\nBody: JSON-RPC 2.0 message\n\n# Close session\nDELETE /mcp\nHeaders:\n  Authorization: Bearer YOUR_API_KEY\n  MCP-Session-ID: \u003csession-id\u003e\n```\n\n### Example Usage\n\n#### Initialize MCP Connection\n```bash\n# Start SSE stream in one terminal\ncurl -N -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  http://localhost:3000/mcp\n\n# In another terminal, send initialize message\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {\n      \"protocolVersion\": \"2024-11-05\",\n      \"capabilities\": {},\n      \"clientInfo\": {\n        \"name\": \"test-client\",\n        \"version\": \"1.0.0\"\n      }\n    }\n  }'\n```\n\n#### Call MCP Tools\n```bash\n# List available tools\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/list\",\n    \"params\": {}\n  }'\n\n# Start automated test session\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 3,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"start_automated_session\",\n      \"arguments\": {\n        \"task\": \"Test login functionality\"\n      }\n    }\n  }'\n```\n\n### MCP Client Support\n\nAny MCP client that supports the StreamableHTTP transport can connect to this server. You'll need to:\n\n1. Configure the client with the HTTP endpoint: `http://localhost:3000/mcp`\n2. Add authentication header: `Authorization: Bearer YOUR_API_KEY`\n3. The client will automatically handle SSE streams and JSON-RPC messaging\n\n\u003e **Note:** Most current MCP clients (Claude Desktop, Cline, etc.) use stdio transport by default. The HTTP mode is primarily for:\n\u003e - Custom integrations and web applications\n\u003e - Remote server deployments\n\u003e - Microservices architectures\n\u003e - API gateways and proxies\n\n### Security Considerations\n\nWhen running in HTTP mode:\n\n- ✅ **Always use HTTPS** in production (consider using a reverse proxy like nginx)\n- ✅ **Protect your API key** - it provides full access to your desplega.ai account\n- ✅ **Use firewall rules** to restrict access to trusted IP addresses\n- ✅ **Consider rate limiting** for public-facing deployments\n- ✅ **Monitor access logs** for suspicious activity\n\nExample nginx configuration for HTTPS:\n\n```nginx\nserver {\n    listen 443 ssl;\n    server_name qa-mcp.example.com;\n\n    ssl_certificate /path/to/cert.pem;\n    ssl_certificate_key /path/to/key.pem;\n\n    location / {\n        proxy_pass http://localhost:3000;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection 'upgrade';\n        proxy_set_header Host $host;\n        proxy_cache_bypass $http_upgrade;\n\n        # Required for SSE\n        proxy_buffering off;\n        proxy_read_timeout 24h;\n    }\n}\n```\n\n### Docker Deployment\n\nThe HTTP mode is perfect for containerized deployments. Example Dockerfile:\n\n```dockerfile\nFROM node:18-slim\n\n# Install dependencies for Playwright\nRUN apt-get update \u0026\u0026 apt-get install -y \\\n    libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 \\\n    libgbm1 libasound2 libxshmfence1 \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/*\n\n# Install qa-use-mcp\nRUN npm install -g @desplega.ai/qa-use-mcp\n\n# Expose port\nEXPOSE 3000\n\n# Set API key via environment variable\nENV QA_USE_API_KEY=your-api-key-here\n\n# Start in HTTP mode\nCMD [\"qa-use-mcp\", \"--http\", \"--port\", \"3000\"]\n```\n\nRun the container:\n\n```bash\ndocker build -t qa-use-mcp .\ndocker run -d -p 3000:3000 \\\n  -e QA_USE_API_KEY=your-api-key \\\n  qa-use-mcp\n```\n\n### Vercel Deployment\n\nDeploy to Vercel for serverless hosting:\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/desplega-ai/qa-use)\n\n**Quick setup:**\n\n```bash\n# Install Vercel CLI\nnpm i -g vercel\n\n# Deploy\nvercel --prod\n```\n\n**Vercel Build Settings:**\n- **Build Command**: `pnpm build`\n- **Output Directory**: `dist`\n- **Install Command**: `pnpm install`\n\n**Environment Variables** (set in Vercel dashboard):\n- `QA_USE_API_KEY` - Your desplega.ai API key\n\n⚠️ **Important**: Vercel has execution time limits (60s max on Pro plan) which may affect long-running SSE connections. For production use with long-running sessions, consider:\n- **Railway** - Better for persistent connections\n- **Render** - Supports long-running services\n- **Fly.io** - Full control over processes\n- **Self-hosted VPS** - No limits\n\nSee [VERCEL_DEPLOYMENT.md](./VERCEL_DEPLOYMENT.md) for detailed deployment guide and limitations.\n\n### Backward Compatibility\n\nAll modes are fully backward compatible. Running without flags uses the standard MCP stdio transport:\n\n```bash\n# Standard MCP mode (stdio) - default\nnpx @desplega.ai/qa-use-mcp\n\n# HTTP transport mode (SSE)\nnpx @desplega.ai/qa-use-mcp --http\n\n# Tunnel mode (persistent WebSocket)\nnpx @desplega.ai/qa-use-mcp tunnel\n```\n\nAll modes support the complete MCP tools and functionality. The HTTP mode follows the official MCP Streamable HTTP specification.\n\n## Tunnel Mode\n\nThe tunnel mode creates a persistent WebSocket tunnel that allows the desplega.ai backend to initiate browser automation tasks using your local browser. This is perfect for scenarios where you want the backend to control test execution while using your local environment's browser.\n\n### When to Use Tunnel Mode\n\n| Scenario | Best Mode |\n|----------|-----------|\n| Backend-initiated tests | **Tunnel** ✅ |\n| CI/CD pipelines with local browsers | **Tunnel** ✅ |\n| Remote test execution on local environment | **Tunnel** ✅ |\n| Interactive MCP client testing | **stdio** |\n| Web dashboard integrations | **HTTP/SSE** |\n\n### How It Works\n\n1. **Start Tunnel**: Creates a Playwright browser and localtunnel\n2. **Register WebSocket**: Sends the tunneled WebSocket URL to desplega.ai backend\n3. **Heartbeat**: Sends keepalive signals every 5 seconds to maintain the connection\n4. **Backend Control**: Backend can now initiate test sessions using your local browser\n\n### Starting Tunnel Mode\n\n```bash\n# Start tunnel with headless browser (default)\nnpx @desplega.ai/qa-use-mcp tunnel\n\n# Start tunnel with visible browser\nnpx @desplega.ai/qa-use-mcp tunnel --visible\n```\n\n### Example Output\n\n```\n🔧 QA-Use Tunnel Mode\n====================\nMode: Headless\n\n🔑 Validating API key...\n✅ API key valid\n\n🌐 Starting browser tunnel...\n✅ Browser started\n✅ Tunnel created\n\n📡 WebSocket URL: wss://qa-use-123456.lt.desplega.ai/...\n✅ Registered with backend\n\n🔄 Heartbeat active (every 5s)\n   Press Ctrl+C to stop\n\n[10:30:15] ✓ Heartbeat #1 sent\n[10:30:20] ✓ Heartbeat #2 sent\n[10:30:25] ✓ Heartbeat #3 sent\n```\n\n### Environment Variables\n\nSet your API key before starting tunnel mode:\n\n```bash\nexport QA_USE_API_KEY=your-desplega-ai-api-key\nnpx @desplega.ai/qa-use-mcp tunnel\n```\n\nOptionally configure the US region for better tunnel performance from North America:\n\n```bash\nexport QA_USE_API_KEY=your-desplega-ai-api-key\nexport QA_USE_REGION=us\nnpx @desplega.ai/qa-use-mcp tunnel\n```\n\nAlternatively, you can use a config file instead of environment variables. See [Configuration File](#configuration-file) for details.\n\n### Options\n\n- **`--visible`**: Show browser window instead of headless mode (useful for debugging)\n\n### Use Cases\n\n#### 1. CI/CD Integration\nRun tunnel mode in your CI/CD pipeline to allow backend-initiated tests:\n\n```yaml\n# .github/workflows/qa.yml\n- name: Start QA Tunnel\n  run: |\n    export QA_USE_API_KEY=${{ secrets.QA_USE_API_KEY }}\n    npx @desplega.ai/qa-use-mcp tunnel \u0026\n    sleep 10  # Wait for tunnel to establish\n```\n\n#### 2. Development Testing\nKeep a tunnel running while developing to allow ad-hoc tests from the backend:\n\n```bash\n# Terminal 1: Keep tunnel running\nnpx @desplega.ai/qa-use-mcp tunnel\n\n# Terminal 2: Trigger tests from backend via API/dashboard\n# The backend will use your local browser through the tunnel\n```\n\n#### 3. Debugging with Visible Browser\nWhen you need to see what's happening:\n\n```bash\nnpx @desplega.ai/qa-use-mcp tunnel --visible\n```\n\n### Graceful Shutdown\n\nPress `Ctrl+C` to stop the tunnel. The server will:\n1. Stop sending heartbeats\n2. Close the tunnel\n3. Shutdown the browser\n4. Clean up resources\n\n### Differences from Other Modes\n\n| Feature | stdio | HTTP/SSE | **Tunnel** |\n|---------|-------|----------|------------|\n| **Control** | Local MCP client | HTTP requests | Backend-initiated |\n| **Browser** | On-demand | On-demand | **Persistent** |\n| **Heartbeat** | N/A | N/A | **Every 5s** |\n| **Use Case** | Desktop IDEs | Web apps | **Backend tasks** |\n| **Visibility** | Configurable | Configurable | **Headless default** |\n\n\n## Installation\n\nInstall and run directly with npx:\n\n```bash\nnpx @desplega.ai/qa-use-mcp\n```\n\nOr install globally:\n\n```bash\nnpm install -g @desplega.ai/qa-use-mcp\nqa-use-mcp  # or: desplega-qa\n```\n\n## Development\n\nClone the repository and install dependencies:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd qa-use-mcp\npnpm install\n```\n\nBuild the project:\n\n```bash\npnpm build\n```\n\nStart the development server:\n\n```bash\npnpm dev\n```\n\n\u003c!-- AUTO-GENERATED-TOOLS-START --\u003e\n## MCP Tools\n\nThe server exposes the following MCP tools for browser automation and QA testing:\n\n### Setup \u0026 Configuration\n\n#### `ensure_installed`\nEnsure API key is set, validate authentication, and install Playwright browsers.\n\n**Parameters:**\n- `apiKey` (string, optional): API key for desplega.ai (optional if QA_USE_API_KEY env var is set)\n\n#### `register_user`\nRegister a new user account with desplega.ai and receive an API key.\n\n**Parameters:**\n- `email` (string, required): Email address for registration\n\n#### `update_configuration`\nUpdate application configuration settings including base URL, login credentials, and viewport type.\n\n**Parameters:**\n- `base_url` (string, optional): Base URL for the application being tested\n- `login_url` (string, optional): Login page URL for the application\n- `login_username` (string, optional): Default username for login testing\n- `login_password` (string, optional): Default password for login testing\n- `vp_type` (string, optional): Viewport configuration type: big_desktop, desktop, mobile, or tablet (default: desktop)\n\n#### `get_configuration`\nGet the current application configuration details including base URL, login settings, and viewport.\n\n**Parameters:** None\n\n### Session Management\n\n#### `search_sessions`\nSearch and list all sessions (automated tests and development sessions) with pagination and filtering.\n\n**Parameters:**\n- `limit` (number, optional): Maximum number of sessions to return (default: 10, min: 1)\n- `offset` (number, optional): Number of sessions to skip (default: 0, min: 0)\n- `query` (string, optional): Search query to filter sessions by task, URL, or status\n\n#### `start_automated_session`\nStart an automated E2E test session for QA flows and automated testing. Returns sessionId for monitoring.\n\n**Parameters:**\n- `task` (string, required): The testing task or scenario to execute\n- `url` (string, optional): Optional URL to test (overrides app config base_url if provided)\n- `dependencyId` (string, optional): Optional test ID that this session depends on (must be a self test ID created by your app configuration)\n- `headless` (boolean, optional): Run browser in headless mode (default: false for better visibility)\n\n#### `start_dev_session`\nStart an interactive development session for debugging and exploration. Session will not auto-pilot and allows manual browser interaction.\n\n**Parameters:**\n- `task` (string, required): Description of what you want to explore or debug. Can be a placeholder like \"Waiting for user input\"\n- `url` (string, optional): Optional URL to start from (overrides app config base_url if provided)\n- `headless` (boolean, optional): Run browser in headless mode (default: false for development visibility)\n\n#### `monitor_session`\nMonitor a session status. Keep calling until status is \"closed\". Will alert if session needs user input, is idle, or pending.\n\n**Parameters:**\n- `sessionId` (string, required): The session ID to monitor\n- `wait` (boolean, optional): Wait for session to reach any non-running state with MCP timeout protection (max 25s per call)\n- `timeout` (number, optional): User timeout in seconds for wait mode (default: 60)\n\n#### `interact_with_session`\nInteract with a session - respond to questions, pause, or close the session.\n\n**Parameters:**\n- `sessionId` (string, required): The session ID to interact with\n- `action` (string, required): Action to perform: respond (answer question), pause (stop session), or close (end session)\n- `message` (string, optional): Your response message (required for \"respond\" action, optional for others)\n\n### Test Management\n\n#### `search_automated_tests`\nSearch for automated tests by ID or query. If testId provided, returns detailed info for that test. Otherwise searches with optional query/pagination.\n\n**Parameters:**\n- `testId` (string, optional): Specific test ID to retrieve detailed information for (if provided, other params ignored)\n- `query` (string, optional): Search query to filter tests by name, description, URL, or task (ignored if testId provided)\n- `limit` (number, optional): Maximum number of tests to return (default: 10, min: 1) (ignored if testId provided)\n- `offset` (number, optional): Number of tests to skip (default: 0, min: 0) (ignored if testId provided)\n- `self_only` (boolean, optional): Filter tests by app configuration. When true, only returns tests created by your application configuration. Default: false to allow running tests from other configs locally.\n\n#### `run_automated_tests`\nExecute multiple automated tests simultaneously.\n\n**Parameters:**\n- `test_ids` (array, required): Array of test IDs to execute\n- `app_config_id` (string, optional): Optional app config ID to run tests against (uses API key default config if not provided)\n- `ws_url` (string, optional): Optional WebSocket URL override (uses global tunnel URL by default)\n\n#### `search_automated_test_runs`\nSearch automated test runs with optional filtering by test ID or run ID.\n\n**Parameters:**\n- `test_id` (string, optional): Filter test runs by specific test ID\n- `run_id` (string, optional): Filter test runs by specific run ID\n- `limit` (number, optional): Maximum number of test runs to return (default: 10, min: 1)\n- `offset` (number, optional): Number of tests to skip (default: 0, min: 0)\n\n\u003c!-- AUTO-GENERATED-TOOLS-END --\u003e\n\n### Built-in Documentation\n\nThe server includes comprehensive MCP resources and prompts:\n\n#### MCP Resources\n- **Getting Started Guide**: Complete setup and usage instructions\n- **Testing Workflows**: Common patterns for interactive, batch, and development testing\n- **Tool Reference**: Detailed documentation for all available MCP tools\n\n#### MCP Prompts\n- **`aaa_test`**: Generate structured test scenarios using the Arrange-Act-Assert (AAA) framework with customizable parameters\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in your project root or set the following environment variables:\n\n```bash\n# Required: Your desplega.ai API key\nQA_USE_API_KEY=your-desplega-ai-api-key\n\n# Optional: Region selection for tunnel and API routing\n# Values: \"us\" | \"auto\"\n# Default: \"auto\" (if not set)\n# - \"us\": Uses lt.us.desplega.ai for localtunnel and routes to US region\n# - \"auto\": Uses default lt.desplega.ai and automatic region routing\nQA_USE_REGION=us\n\n# Optional: Custom API endpoint (default: https://api.desplega.ai)\nQA_USE_API_URL=https://api.desplega.ai\n\n# Optional: Custom app URL (default: https://app.desplega.ai)\nQA_USE_APP_URL=https://app.desplega.ai\n\n# Optional: Custom tunnel host (overrides QA_USE_REGION setting)\nTUNNEL_HOST=https://lt.desplega.ai\n```\n\n#### Regional Configuration\n\nThe `QA_USE_REGION` variable allows you to route your tunnel and API requests to specific regions:\n\n- **Not set** (default): Uses automatic region selection (`lt.desplega.ai`)\n- **`QA_USE_REGION=us`**: Uses US-based tunnel host (`lt.us.desplega.ai`) and routes sessions to the US region. Recommended for users primarily testing from North America.\n- **`QA_USE_REGION=auto`**: Explicitly sets automatic region selection (same as not setting it)\n\nExample configuration for US region:\n```bash\nexport QA_USE_API_KEY=your-api-key\nexport QA_USE_REGION=us\nnpx @desplega.ai/qa-use-mcp\n```\n\n\u003e **Note:** If `QA_USE_REGION` is not set, the system automatically defaults to `\"auto\"` behavior.\n\n### Configuration File\n\nAs an alternative to environment variables, you can store your configuration in `~/.qa-use.json`:\n\n```json\n{\n  \"env\": {\n    \"QA_USE_API_KEY\": \"your-api-key-here\",\n    \"QA_USE_API_URL\": \"https://api.desplega.ai\",\n    \"QA_USE_APP_URL\": \"https://app.desplega.ai\",\n    \"QA_USE_REGION\": \"us\"\n  }\n}\n```\n\n**Priority order:**\n1. Environment variables (highest priority)\n2. Config file (`~/.qa-use.json`)\n3. Default values\n\nThis is useful when you don't want to set environment variables or when using MCP clients that don't support environment configuration.\n\nAn example config file is available at [`.qa-use.example.json`](.qa-use.example.json) in this repository.\n\n## Usage Examples\n\n### Interactive Testing Workflow\n```bash\n# 1. Initialize server and install browsers\nensure_installed\n\n# 2. Configure app settings (one-time setup)\nupdate_configuration with base_url=\"https://app.example.com\" and login_url=\"https://app.example.com/login\" and login_username=\"testuser@example.com\"\n\n# 3. Start an automated test session\nstart_automated_session with task=\"Test user registration flow\"\n\n# 4. Monitor session progress\nmonitor_session with sessionId=\"session-123\" and wait=true and timeout=300\n\n# 5. Interact with session if needed (respond, pause, or close)\ninteract_with_session with sessionId=\"session-123\" and action=\"respond\" and message=\"john.doe@example.com\"\n```\n\n### Development \u0026 Debugging Workflow\n```bash\n# 1. Start an interactive dev session (no auto-pilot)\nstart_dev_session with task=\"Exploring the checkout flow\" and url=\"https://app.example.com/cart\"\n\n# 2. Monitor and interact as needed\nmonitor_session with sessionId=\"dev-session-456\"\n\n# 3. Close when done\ninteract_with_session with sessionId=\"dev-session-456\" and action=\"close\"\n```\n\n### Batch Testing Workflow\n```bash\n# 1. Find available tests\nsearch_automated_tests with query=\"login\" and limit=10\n\n# 2. Run multiple tests simultaneously\nrun_automated_tests with test_ids=[\"login-test-1\", \"signup-test-2\", \"checkout-test-3\"]\n\n# 3. Monitor progress\nsearch_sessions with limit=20\n\n# 4. Check test run history\nsearch_automated_test_runs with limit=50\n```\n\n### Using AAA Framework Template\n```bash\n# Generate a structured test using AAA framework\nUse prompt: aaa_test with test_type=\"login\" and url=\"https://app.example.com/login\" and feature=\"user authentication\"\n```\n\n### Resource Management\n```bash\n# When you hit the 10 session limit or need to free up resources\nreset_browser_sessions\n\n# This will clean up all active browsers and tunnels\n# Useful when sessions aren't closing properly or you need to restart fresh\n```\n\n## Testing\n\nUse the provided test scripts to test MCP server functionality:\n\n```bash\n# Test server initialization (uses env var if available)\n./scripts/test-init.sh\n\n# Test listing sessions\n./scripts/test-list-sessions.sh\n\n# Test starting a session\n./scripts/test-start-session.sh\n\n# Test with real API key from environment\nnode scripts/mcp-test.js\n```\n\n## Architecture\n\nThe project is organized into modular components:\n\n- **`src/`**: Main MCP server implementation with comprehensive tool handlers\n  - MCP protocol implementation with tools, resources, and prompts\n  - Session management and monitoring with timeout protection\n  - BrowserSession management with automatic lifecycle tracking\n    - Each session wraps browser + tunnel with TTL and deadline tracking\n    - Session types: 'dev', 'automated', and 'test_run'\n    - Automatic cleanup on expiration or completion\n  - Real-time progress notifications using MCP logging specification\n  - AAA framework prompt templates for structured testing\n- **`lib/browser/`**: Browser management functionality using Playwright\n  - Headless and headed browser support\n  - WebSocket endpoint management for remote control\n- **`lib/tunnel/`**: Tunneling and port forwarding using localtunnel\n  - Public tunnel creation for browser WebSocket access\n  - Automatic WebSocket URL conversion for remote testing\n- **`lib/api/`**: Complete API client for desplega.ai integration\n  - Session lifecycle management (create, monitor, respond)\n  - Test discovery and execution\n  - Test run analytics and history\n  - User registration and authentication\n  - Batch test execution with dependency handling\n\n### Key Features Implementation\n\n#### MCP Timeout Protection\n- Limited monitoring calls to 25 seconds to prevent MCP timeouts\n- Automatic continuation support for long-running sessions\n- Real-time progress notifications during session monitoring\n\n#### AAA Framework Integration\n- Pre-built templates for login, forms, e-commerce, and navigation testing\n- Comprehensive test scenarios for accessibility, performance, and mobile testing\n- Dynamic argument support for customizable test generation\n\n#### Test Analytics\n- Complete test run history with performance metrics\n- Probabilistic Flakiness Score (PFS) tracking\n- Execution timing and error tracking\n- Filtering and pagination for large datasets\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesplega-ai%2Fqa-use","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdesplega-ai%2Fqa-use","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdesplega-ai%2Fqa-use/lists"}