QA Automation MCP Server

An AI-powered QA automation tool built on the Model Context Protocol (MCP). It crawls web pages, generates Playwright-based pytest tests using an LLM, runs them, and automatically heals failing tests — all driven by natural language instructions.

How It Works

User Instruction
      │
      ▼
 crawl_page(url)
      │  Headless Chromium extracts all interactive elements
      ▼
write_test(crawl_data, instruction, output_dir)
      │  Groq LLM generates a pytest + Playwright test file
      ▼
 run_test(crawl_data, output_dir)
      │  Pytest executes the generated test
      │
      ├── PASS → HTML report + text summary
      │
      └── FAIL (locator/timeout error)
              │
              ▼
         Auto-Healer
              │  Groq rewrites the broken locators
              ▼
         Re-run test
              │
              └── HTML report + text summary (marked "healed")

Features

• Page Crawling — Extracts inputs, buttons, and links with CSS selectors, XPaths, and metadata

• AI Test Generation — Converts a plain-English instruction + crawl data into a complete pytest test file

• Automated Execution — Runs tests programmatically with pytest and captures all output

• Auto-Healing — Detects locator/timeout failures and sends the broken test back to the LLM for repair, then re-runs automatically

• Rich Reporting — Generates an HTML report with screenshots and a text summary; opens in browser automatically

• Headless or Headed — Browser is headless by default; pass show_browser=true to watch it run

Architecture

MCP-server/
├── main.py            # MCP server entry point and request dispatcher
├── pyproject.toml     # Project metadata and dependencies
├── .env               # API keys (not committed)
└── src/
    ├── tools.py       # MCP tool definitions (schemas exposed to the client)
    ├── handlers.py    # Request handlers that wire tools to logic
    ├── crawler.py     # Playwright-based page crawling
    ├── writer.py      # LLM-powered test code generation
    ├── runner.py      # Pytest execution and result parsing
    ├── healer.py      # Auto-healing logic for failing tests
    └── reporter.py    # HTML and text report generation

MCP Tools

The server exposes three tools to any MCP-compatible client.

crawl_page

Crawls a URL and returns structured data about all interactive elements on the page.

Returns: JSON with title, inputs, buttons, and links, each containing locator strategies (CSS selector, XPath) and metadata.

write_test

Generates a pytest + Playwright test file from crawl data and a plain-English instruction.

Returns: Path to the generated test file at {output_dir}/generated_tests/test_*.py.

run_test

Executes the generated test and returns a report. Automatically attempts to heal locator/timeout failures.

Returns: Text summary + path to the HTML report at {output_dir}/test_results/report_*.html.

Prerequisites

• Python 3.12+

• uv (recommended) or pip

• A Groq API key

• Playwright browsers installed

Installation

1. Clone the repository

git clone <repo-url>
cd MCP-server

2. Install dependencies

uv sync

Or with pip:

pip install -e .

3. Install Playwright browsers

uv run playwright install chromium

4. Create a .env file

GROQ_API_KEY=your_groq_api_key_here

Running the Server

The server communicates over stdio, which is the standard transport for MCP clients like Claude Code.

uv run python main.py

Connecting to Claude Code

Add the server to your Claude Code MCP configuration (.claude/settings.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "qa-automation": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/absolute/path/to/MCP-server"
    }
  }
}

Once connected, you can drive the entire QA workflow through natural language in Claude Code:

"Crawl https://example.com, then write a test that fills in the search box and clicks Submit, and run it."

Generated Output

Each test run produces the following structure inside output_dir:

{output_dir}/
├── generated_tests/
│   └── test_<slug>.py          # Generated pytest test file
├── test_results/
│   └── report_YYYYMMDD_HHMMSS.html   # HTML report with screenshot
└── result.png                  # Screenshot from the last test run

The HTML report is opened automatically in your default browser after each run.

Auto-Healing

When a test fails due to a locator or timeout error, the healer:

1. Parses the pytest output to identify the broken locator

2. Sends the original test code, the error, and the fresh crawl data to the LLM

3. Receives a rewritten version with corrected selectors (get_by_role, get_by_text, or CSS)

4. Saves the patched file and re-runs the test

5. Marks the final report with healed: true

Only one healing attempt is made per run. Logic errors (wrong assertions, incorrect flow) are not healed automatically.

Dependencies

LLM Configuration

• Provider: Groq

• Model: llama-3.3-70b-versatile

• Temperature: 0.3 for test generation, 0.1 for healing (tighter, more deterministic)

To switch models or providers, update src/writer.py and src/healer.py.

Limitations

• Auto-healing only addresses locator and timeout errors, not test logic errors

• Only one healing attempt per test run

• Authentication and multi-step login flows are not handled automatically

• Hardcoded to Groq's llama-3.3-70b-versatile model

License

MIT