MCP Server for Automated Browser QA Testing

Overview

This MCP (Model Context Protocol) server provides a lightweight HTTP service that integrates automated browser QA with model-guided test orchestration. It exposes tools and endpoints that let test runners, CI systems, and language models invoke browser sessions, run scripted or intelligent tests, monitor active sessions, and execute batches of checks. The server can be used as a local service, in CI pipelines, or as a remote endpoint that models call using the MCP pattern.

The service is useful for teams that want to centralize browser QA operations and add intelligence to testing flows. Built to interoperate with desplega.ai for AAA-guided intelligent testing (Arrange-Act-Assert style test generation and verification), the server supports both classical scripted automation and model-driven test generation, session lifecycle controls, and batch execution for large test suites.

GitHub: https://github.com/desplega-ai/qa-use

Features

• Automated browser test execution (scripted and model-guided)
• AAA-guided intelligent testing via desplega.ai (Arrange / Act / Assert generation and evaluation)
• Session lifecycle management and real-time session monitoring
• Batch execution of multiple tests with simple orchestration
• REST endpoints suitable for MCP-style tool integration
• Configurable headless or headed browser runs for local debugging or CI
• Simple webhook or callback support for results and alerts
• Designed to be embedded into CI pipelines or called from LLM agents

Installation / Configuration

Clone the repository and install dependencies. The project typically uses Node.js; substitute the commands below for your stack if different.

git clone https://github.com/desplega-ai/qa-use.git
cd qa-use
npm install

Start the server locally:

# default port 3000; set DESPLEGA_API_KEY to use AAA features
export DESPLEGA_API_KEY="your_api_key_here"
npm start

Docker example:

docker build -t mcp-qa-server .
docker run -p 3000:3000 \
  -e DESPLEGA_API_KEY="your_api_key_here" \
  -e PORT=3000 \
  mcp-qa-server

Common environment variables

Config file example (JSON):

{
  "port": 3000,
  "browser": "chrome",
  "headless": true,
  "desplegaApiKey": "${DESPLEGA_API_KEY}",
  "sessionTimeout": 300
}

Available Tools / Resources

The server exposes a small set of MCP-style “tools” or REST resources that models and clients can call:

• /health — health check for liveness and readiness
• /sessions — create, list, inspect, and terminate browser sessions
• /run — run a single test case (scripted or model-guided)
• /batch — submit a batch of test jobs and track progress
• /results — retrieve results and artifacts (logs, screenshots)
• /webhook — configure a callback endpoint for test completion notifications

Example: check health

curl http://localhost:3000/health
# { "status": "ok", "version": "1.0.0" }

Example: start a session

curl -X POST http://localhost:3000/sessions \
  -H "Content-Type: application/json" \
  -d '{ "browser": "chrome", "headless": true }'

Use Cases

• Continuous regression testing

  • Run a batch of smoke and regression checks on every PR. Use /batch to submit jobs and /results to collect failures and artifacts for CI logs.

• Intelligent test generation and verification

  • Use desplega.ai AAA guidance to automatically generate Arrange-Act-Assert test steps from a high-level prompt (e.g., “verify checkout flow”) and run them via /run. Useful to expand coverage with model-assisted test cases.

• Session monitoring and debugging

  • Create sessions for manual or automated exploration, stream logs and screenshots, then terminate idle sessions via /sessions and sessionTimeout to conserve resources.

• Cross-browser compatibility checks

  • Execute the same test script across Chrome and Firefox by setting “browser” in the session or test payload and collecting comparative results in /results.

• Flakiness detection and batch replays

  • Re-run flaky tests automatically by submitting them to /batch with retry and aggregation logic. Collect flakiness metrics and artifacts for triage.

Example: Run a scripted test via API

curl -X POST http://localhost:3000/run \
  -H "Content-Type: application/json" \
  -d '{
    "type": "script",
    "script": "navigate https://example.com; click #login; fill #user test; fill #pass secret; click #submit; assert textContains Welcome"
  }'

Response contains a run id that you can poll via /results to get status, logs, screenshots, and a pass/fail verdict.

Notes for Developers

• Design clients to handle asynchronous execution: runs and batches may return immediately with an id to poll for completion.
• Secure the DESPLEGA_API_KEY and any webhook endpoints used for callbacks.
• Run headed browsers for debugging locally; use headless in CI to reduce resource usage.
• Integrate with your CI by calling /batch in test stages and failing builds based on /results.

For implementation details, code samples, and API reference, see the repository: https://github.com/desplega-ai/qa-use.