mcp-recursive-qa 0.1.0
Parallelized QA testing MCP server for AI-driven browser automation
License: MIT
Requires Python: >=3.11
Keywords: ai, automation, browser, mcp, qa, testing, visual-testing

<img src="./assets/header.png" alt="Browser Use Web UI" width="full"/>

<br/>

# Recursive - Parallelized QA Testing MCP
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)

> **Project Note**: Recursive transforms browser automation into a powerful QA testing platform, built upon the foundation of mcp-browser-use with extensive enhancements for parallel test execution and agent coordination.

Recursive is a parallelized QA testing MCP that enables AI agents to execute natural language browser automations for comprehensive feature testing. With support for concurrent browser sessions, visual regression testing, and inter-agent communication, Recursive revolutionizes automated QA workflows.

🚀 **Key Innovation**: Run 50+ concurrent browser sessions for parallel test execution with sub-500ms API response times.

## Features

### Core QA Testing Capabilities
-   🎯 **Parallel Test Execution** - Run multiple browser sessions simultaneously with intelligent session management
-   🔍 **Visual Regression Testing** - Automated screenshot comparison and visual diff detection
-   📊 **Test Orchestration** - Comprehensive test suite management with dependency resolution
-   🤝 **Agent Communication** - Inter-agent coordination for distributed testing workflows
-   📈 **Performance Monitoring** - Real-time metrics for page load times and interaction delays

### Technical Features
-   🧠 **MCP Integration** - Full protocol implementation optimized for QA workflows
-   🌐 **Enhanced Browser Automation** - Session-aware browser control with retry logic and validation
-   👁️ **Advanced Visual Testing** - Screenshot analysis with perceptual hashing and pixel comparison
-   🔄 **Session Management** - Robust lifecycle management for concurrent browser instances
-   🔌 **Multi-LLM Support** - Integrates with all major LLM providers for flexible test generation
-   ⚡ **Browser Pool Management** - Efficient resource allocation with queuing and health checks
-   📝 **Test Reporting** - Comprehensive reports in HTML, JSON, and JUnit XML formats
-   🔗 **CDP Connection** - Connect to existing browser instances for integrated testing
-   ⌨️ **CLI Interface** - Direct access to testing tools for automation and CI/CD integration

## Quick Start

### The Essentials

1. Install UV - the rocket-powered Python installer:
`curl -LsSf https://astral.sh/uv/install.sh | sh`

2. Get Playwright browsers (required for automation):
`uvx --from mcp-recursive-qa@latest python -m playwright install`

### Integration Patterns

For MCP clients like Claude Desktop, add a server configuration that's as simple as:

```json
// Example 1: One-Line Latest Version (Always Fresh)
"mcpServers": {
    "mcp-recursive-qa": {
      "command": "uvx",
      "args": ["--from", "mcp-recursive-qa", "python", "-m", "recursive.server"],
      "env": {
        "MCP_LLM_GOOGLE_API_KEY": "YOUR_KEY_HERE_IF_USING_GOOGLE",
        "MCP_LLM_PROVIDER": "google",
        "MCP_LLM_MODEL_NAME": "gemini-2.0-flash",
        "MCP_BROWSER_HEADLESS": "true"
      }
    }
}
```

```json
// Example 2: Advanced QA Testing Configuration
"mcpServers": {
    "mcp-recursive-qa": {
      "command": "uvx",
      "args": ["--from", "mcp-recursive-qa", "python", "-m", "recursive.server"],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "anthropic/claude-3.5-haiku",
        "MCP_LLM_TEMPERATURE": "0.4",

        "MCP_BROWSER_HEADLESS": "false",
        "MCP_BROWSER_WINDOW_WIDTH": "1440",
        "MCP_BROWSER_WINDOW_HEIGHT": "1080",
        "MCP_AGENT_TOOL_USE_VISION": "true",

        "MCP_TEST_REPORT_DIR": "/path/to/your/test-reports",
        "MCP_MAX_PARALLEL_SESSIONS": "10",
        "MCP_VISUAL_REGRESSION_THRESHOLD": "0.95",

        "MCP_PATHS_DOWNLOADS": "/path/to/your/downloads",

        "MCP_BROWSER_USE_OWN_BROWSER": "true",
        "MCP_BROWSER_CDP_URL": "http://localhost:9222",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}
```

```json
// Example 3: Enterprise QA Configuration
"mcpServers": {
    "recursive": {
      "command": "uvx",
      "args": ["recursive@latest"],
      "env": {
        "MCP_LLM_OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        "MCP_LLM_PROVIDER": "openai",
        "MCP_LLM_MODEL_NAME": "gpt-4.1-mini",
        "MCP_LLM_TEMPERATURE": "0.2",

        "MCP_BROWSER_HEADLESS": "false",

        "MCP_BROWSER_BINARY_PATH": "/path/to/your/chrome/binary",
        "MCP_BROWSER_USER_DATA_DIR": "/path/to/your/user/data",
        "MCP_BROWSER_DISABLE_SECURITY": "true",
        "MCP_BROWSER_KEEP_OPEN": "true",
        "MCP_BROWSER_TRACE_PATH": "/path/to/your/trace",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}
```

```json
// Example 4: Local Development Flow
"mcpServers": {
    "recursive": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/dev/path",
        "run",
        "recursive-server"
      ],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "openai/gpt-4o-mini",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}
```

**Key Insight:** The best configurations emerge from starting simple (Example 1). The .env.example file contains all possible dials.

## MCP Tools

Recursive exposes comprehensive QA testing tools via the Model Context Protocol:

### Core Browser Tools (Enhanced for QA)

1.  **`start_browser_session`**
    *   **Description:** Initialize a new browser session with unique session ID for parallel testing
    *   **Arguments:**
        *   `session_config` (object, optional): Browser configuration overrides
    *   **Returns:** Session ID and browser instance details

2.  **`navigate_to_url`**
    *   **Description:** Navigate to URL with session context and performance tracking
    *   **Arguments:**
        *   `session_id` (string, required): Active session identifier
        *   `url` (string, required): Target URL
        *   `wait_strategy` (string, optional): Page load strategy
    *   **Returns:** Navigation timing metrics and page state

3.  **`click_element`**
    *   **Description:** Enhanced click with retry logic and validation
    *   **Arguments:**
        *   `session_id` (string, required): Active session identifier
        *   `selector` (string, required): Element selector
        *   `retry_count` (integer, optional): Number of retry attempts
    *   **Returns:** Click success status and timing

### QA-Specific Testing Tools

1.  **`run_test_suite`**
    *   **Description:** Execute a collection of tests in parallel with dependency management
    *   **Arguments:**
        *   `suite_config` (object, required): Test suite definition
        *   `parallelism` (integer, optional): Max concurrent tests
    *   **Returns:** Aggregated test results and performance metrics

2.  **`validate_element_state`**
    *   **Description:** Comprehensive element validation for QA assertions
    *   **Arguments:**
        *   `session_id` (string, required): Active session identifier
        *   `selector` (string, required): Element selector
        *   `expected_state` (object, required): Expected element properties
    *   **Returns:** Validation results with detailed differences

3.  **`compare_screenshots`**
    *   **Description:** Visual regression testing with configurable thresholds
    *   **Arguments:**
        *   `session_id` (string, required): Active session identifier
        *   `baseline` (string, required): Baseline image path or ID
        *   `threshold` (float, optional): Similarity threshold (0-1)
    *   **Returns:** Visual diff results and similarity score

4.  **`measure_performance`**
    *   **Description:** Capture page load and interaction timing metrics
    *   **Arguments:**
        *   `session_id` (string, required): Active session identifier
        *   `metric_type` (string, required): Type of metric to capture
    *   **Returns:** Performance timing data

### Parallel Execution Tools

1.  **`create_test_session`**
    *   **Description:** Initialize parallel testing session with resource allocation
    *   **Arguments:**
        *   `test_config` (object, required): Test configuration
        *   `priority` (string, optional): Session priority level
    *   **Returns:** Test session ID and allocated resources

2.  **`broadcast_test_update`**
    *   **Description:** Share test status with other agents for coordination
    *   **Arguments:**
        *   `session_id` (string, required): Test session identifier
        *   `status` (object, required): Test status update
    *   **Returns:** Broadcast confirmation

## CLI Usage

Recursive provides a command-line interface `recursive-cli` for QA testing automation and CI/CD integration.

**Global Options:**
*   `--env-file PATH, -e PATH`: Path to a `.env` file to load configurations from.
*   `--log-level LEVEL, -l LEVEL`: Override the logging level (e.g., `DEBUG`, `INFO`).

**Commands:**

1.  **`recursive-cli run-test-suite [OPTIONS] SUITE_PATH`**
    *   **Description:** Execute a QA test suite with parallel execution
    *   **Arguments:**
        *   `SUITE_PATH` (string, required): Path to test suite definition
    *   **Options:**
        *   `--parallel INTEGER, -p INTEGER`: Number of parallel sessions
        *   `--report-format FORMAT`: Output format (html, json, junit)
    *   **Example:**
        ```bash
        recursive-cli run-test-suite tests/e2e-suite.yaml --parallel 10 -e .env
        ```

2.  **`recursive-cli visual-test [OPTIONS] URL BASELINE`**
    *   **Description:** Perform visual regression testing
    *   **Arguments:**
        *   `URL` (string, required): Page URL to test
        *   `BASELINE` (string, required): Baseline screenshot path
    *   **Options:**
        *   `--threshold FLOAT`: Similarity threshold (0.0-1.0)
    *   **Example:**
        ```bash
        recursive-cli visual-test https://example.com baseline/home.png --threshold 0.95
        ```

All other configurations (LLM keys, paths, browser settings) are picked up from environment variables (or the specified `.env` file) as detailed in the Configuration section.

## Configuration (Environment Variables)

Configure the server and CLI using environment variables. You can set these in your system or place them in a `.env` file in the project root (use `--env-file` for CLI). Variables are structured with prefixes.

| Variable Group (Prefix)             | Example Variable                               | Description                                                                                                | Default Value                     |
| :---------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| **Main LLM (MCP_LLM_)**             |                                                | Settings for the primary LLM used by agents.                                                               |                                   |
|                                     | `MCP_LLM_PROVIDER`                             | LLM provider. Options: `openai`, `azure_openai`, `anthropic`, `google`, `mistral`, `ollama`, etc.         | `openai`                          |
|                                     | `MCP_LLM_MODEL_NAME`                           | Specific model name for the provider.                                                                      | `gpt-4.1`                         |
|                                     | `MCP_LLM_TEMPERATURE`                          | LLM temperature (0.0-2.0).                                                                                 | `0.0`                             |
|                                     | `MCP_LLM_BASE_URL`                             | Optional: Generic override for LLM provider's base URL.                                                    | Provider-specific                 |
|                                     | `MCP_LLM_API_KEY`                              | Optional: Generic LLM API key (takes precedence).                                                          | -                                 |
|                                     | `MCP_LLM_OPENAI_API_KEY`                       | API Key for OpenAI (if provider is `openai`).                                                              | -                                 |
|                                     | `MCP_LLM_ANTHROPIC_API_KEY`                    | API Key for Anthropic.                                                                                     | -                                 |
|                                     | `MCP_LLM_GOOGLE_API_KEY`                       | API Key for Google AI (Gemini).                                                                            | -                                 |
|                                     | `MCP_LLM_AZURE_OPENAI_API_KEY`                 | API Key for Azure OpenAI.                                                                                  | -                                 |
|                                     | `MCP_LLM_AZURE_OPENAI_ENDPOINT`                | **Required if using Azure.** Your Azure resource endpoint.                                                 | -                                 |
|                                     | `MCP_LLM_OLLAMA_ENDPOINT`                      | Ollama API endpoint URL.                                                                                   | `http://localhost:11434`          |
|                                     | `MCP_LLM_OLLAMA_NUM_CTX`                       | Context window size for Ollama models.                                                                     | `32000`                           |
| **Planner LLM (MCP_LLM_PLANNER_)**  |                                                | Optional: Settings for a separate LLM for agent planning. Defaults to Main LLM if not set.                |                                   |
|                                     | `MCP_LLM_PLANNER_PROVIDER`                     | Planner LLM provider.                                                                                      | Main LLM Provider                 |
|                                     | `MCP_LLM_PLANNER_MODEL_NAME`                   | Planner LLM model name.                                                                                    | Main LLM Model                    |
| **Browser (MCP_BROWSER_)**          |                                                | General browser settings.                                                                                  |                                   |
|                                     | `MCP_BROWSER_HEADLESS`                         | Run browser without UI (general setting).                                                                  | `false`                           |
|                                     | `MCP_BROWSER_DISABLE_SECURITY`                 | Disable browser security features (general setting, use cautiously).                                       | `false`                           |
|                                     | `MCP_BROWSER_BINARY_PATH`                      | Path to Chrome/Chromium executable.                                                                        | -                                 |
|                                     | `MCP_BROWSER_USER_DATA_DIR`                    | Path to Chrome user data directory.                                                                        | -                                 |
|                                     | `MCP_BROWSER_WINDOW_WIDTH`                     | Browser window width (pixels).                                                                             | `1280`                            |
|                                     | `MCP_BROWSER_WINDOW_HEIGHT`                    | Browser window height (pixels).                                                                            | `1080`                            |
|                                     | `MCP_BROWSER_USE_OWN_BROWSER`                  | Connect to user's browser via CDP URL.                                                                     | `false`                           |
|                                     | `MCP_BROWSER_CDP_URL`                          | CDP URL (e.g., `http://localhost:9222`). Required if `MCP_BROWSER_USE_OWN_BROWSER=true`.                  | -                                 |
|                                     | `MCP_BROWSER_KEEP_OPEN`                        | Keep server-managed browser open between MCP calls (if `MCP_BROWSER_USE_OWN_BROWSER=false`).               | `false`                           |
|                                     | `MCP_BROWSER_TRACE_PATH`                       | Optional: Directory to save Playwright trace files. If not set, tracing to file is disabled.               | ` ` (empty, tracing disabled)     |
| **Agent Tool (MCP_AGENT_TOOL_)**    |                                                | Settings for the `run_browser_agent` tool.                                                                 |                                   |
|                                     | `MCP_AGENT_TOOL_MAX_STEPS`                     | Max steps per agent run.                                                                                   | `100`                             |
|                                     | `MCP_AGENT_TOOL_MAX_ACTIONS_PER_STEP`          | Max actions per agent step.                                                                                | `5`                               |
|                                     | `MCP_AGENT_TOOL_TOOL_CALLING_METHOD`           | Method for tool invocation ('auto', 'json_schema', 'function_calling').                                    | `auto`                            |
|                                     | `MCP_AGENT_TOOL_MAX_INPUT_TOKENS`              | Max input tokens for LLM context.                                                                          | `128000`                          |
|                                     | `MCP_AGENT_TOOL_USE_VISION`                    | Enable vision capabilities (screenshot analysis).                                                          | `true`                            |
|                                     | `MCP_AGENT_TOOL_HEADLESS`                      | Override `MCP_BROWSER_HEADLESS` for this tool (true/false/empty).                                          | ` ` (uses general)                |
|                                     | `MCP_AGENT_TOOL_DISABLE_SECURITY`              | Override `MCP_BROWSER_DISABLE_SECURITY` for this tool (true/false/empty).                                  | ` ` (uses general)                |
|                                     | `MCP_AGENT_TOOL_ENABLE_RECORDING`              | Enable Playwright video recording.                                                                         | `false`                           |
|                                     | `MCP_AGENT_TOOL_SAVE_RECORDING_PATH`           | Optional: Path to save recordings. If not set, recording to file is disabled even if `ENABLE_RECORDING=true`. | ` ` (empty, recording disabled)   |
|                                     | `MCP_AGENT_TOOL_HISTORY_PATH`                  | Optional: Directory to save agent history JSON files. If not set, history saving is disabled.              | ` ` (empty, history saving disabled) |
| **Research Tool (MCP_RESEARCH_TOOL_)** |                                             | Settings for the `run_deep_research` tool.                                                                 |                                   |
|                                     | `MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS`      | Max parallel browser instances for deep research.                                                          | `3`                               |
|                                     | `MCP_RESEARCH_TOOL_SAVE_DIR`                   | Optional: Base directory to save research artifacts. Task ID will be appended. If not set, operates in memory-only mode. | `None`                           |
| **Paths (MCP_PATHS_)**              |                                                | General path settings.                                                                                     |                                   |
|                                     | `MCP_PATHS_DOWNLOADS`                          | Optional: Directory for downloaded files. If not set, persistent downloads to a specific path are disabled.  | ` ` (empty, downloads disabled)  |
| **Server (MCP_SERVER_)**            |                                                | Server-specific settings.                                                                                  |                                   |
|                                     | `MCP_SERVER_LOG_FILE`                          | Path for the server log file. Empty for stdout.                                                            | ` ` (empty, logs to stdout)       |
|                                     | `MCP_SERVER_LOGGING_LEVEL`                     | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`).                                           | `ERROR`                           |
|                                     | `MCP_SERVER_ANONYMIZED_TELEMETRY`              | Enable/disable anonymized telemetry (`true`/`false`).                                                      | `true`                            |
|                                     | `MCP_SERVER_MCP_CONFIG`                        | Optional: JSON string for MCP client config used by the internal controller.                               | `null`                            |

**Supported LLM Providers (`MCP_LLM_PROVIDER`):**
`openai`, `azure_openai`, `anthropic`, `google`, `mistral`, `ollama`, `deepseek`, `openrouter`, `alibaba`, `moonshot`, `unbound`

*(Refer to `.env.example` for a comprehensive list of all supported environment variables and their specific provider keys/endpoints.)*

## Connecting to Your Own Browser (CDP)

Instead of having the server launch and manage its own browser instance, you can connect it to a Chrome/Chromium browser that you launch and manage yourself.

**Steps:**

1.  **Launch Chrome/Chromium with Remote Debugging Enabled:**
    (Commands for macOS, Linux, Windows as previously listed, e.g., `google-chrome --remote-debugging-port=9222`)

2.  **Configure Environment Variables:**
    Set the following environment variables:
    ```dotenv
    MCP_BROWSER_USE_OWN_BROWSER=true
    MCP_BROWSER_CDP_URL=http://localhost:9222 # Use the same port
    # Optional: MCP_BROWSER_USER_DATA_DIR=/path/to/your/profile
    ```

3.  **Run the Recursive Server or CLI:**
    Start the server (`uv run recursive-server`) or CLI (`recursive-cli ...`) as usual.

**Important Considerations:**
*   The browser launched with `--remote-debugging-port` must remain open.
*   Settings like `MCP_BROWSER_HEADLESS` and `MCP_BROWSER_KEEP_OPEN` are ignored when `MCP_BROWSER_USE_OWN_BROWSER=true`.

## Development

```bash
# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run Recursive server with debugger (Example with parallel testing)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222 --user-data-dir="optional/path/to/user/profile"
# 2. Run inspector command with environment variables:
npx @modelcontextprotocol/inspector@latest \
  -e MCP_LLM_GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -e MCP_LLM_PROVIDER=google \
  -e MCP_LLM_MODEL_NAME=gemini-2.5-flash-preview-04-17 \
  -e MCP_BROWSER_USE_OWN_BROWSER=true \
  -e MCP_BROWSER_CDP_URL=http://localhost:9222 \
  -e MCP_MAX_PARALLEL_SESSIONS=10 \
  -e MCP_TEST_REPORT_DIR=./tmp/test_reports \
  uv --directory . run recursive-server

# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

# Run CLI examples for QA testing
# Create a .env file with your settings or use environment variables
uv run recursive-cli -e .env run-test-suite tests/login-flow.yaml --parallel 5
uv run recursive-cli -e .env visual-test https://app.example.com baseline/dashboard.png --threshold 0.98
```

## QA Test Results Viewer

After running QA tests, you can view the results in a web interface:

```bash
# Quick launch from project root
./view_qa_results.sh

# Or manually from qa_viewer directory
cd qa_viewer && ./run.sh
```

The viewer shows:
- All test runs with summaries
- Individual test details and outcomes  
- Screenshots captured during testing
- Agent reasoning and findings

See [qa_viewer/README.md](qa_viewer/README.md) for more details.

## Troubleshooting

-   **Configuration Error on Startup**: If the application fails to start with an error about a missing setting, ensure all **mandatory** environment variables (like `MCP_RESEARCH_TOOL_SAVE_DIR`) are set correctly in your environment or `.env` file.
-   **Browser Conflicts**: If *not* using CDP (`MCP_BROWSER_USE_OWN_BROWSER=false`), ensure no conflicting Chrome instances are running with the same user data directory if `MCP_BROWSER_USER_DATA_DIR` is specified.
-   **CDP Connection Issues**: If using `MCP_BROWSER_USE_OWN_BROWSER=true`:
    *   Verify Chrome was launched with `--remote-debugging-port`.
    *   Ensure the port in `MCP_BROWSER_CDP_URL` matches.
    *   Check firewalls and ensure the browser is running.
-   **API Errors**: Double-check API keys (`MCP_LLM_<PROVIDER>_API_KEY` or `MCP_LLM_API_KEY`) and endpoints (e.g., `MCP_LLM_AZURE_OPENAI_ENDPOINT` for Azure).
-   **Vision Issues**: Ensure `MCP_AGENT_TOOL_USE_VISION=true` and your LLM supports vision.
-   **Dependency Problems**: Run `uv sync` and `uv run playwright install`.
-   **File/Path Issues**:
    *   If optional features like history saving, tracing, or downloads are not working, ensure the corresponding path variables (`MCP_AGENT_TOOL_HISTORY_PATH`, `MCP_BROWSER_TRACE_PATH`, `MCP_PATHS_DOWNLOADS`) are set and the application has write permissions to those locations.
    *   For deep research, ensure `MCP_RESEARCH_TOOL_SAVE_DIR` is set to a valid, writable directory.
-   **Logging**: Check the log file (`MCP_SERVER_LOG_FILE`, if set) or console output. Increase `MCP_SERVER_LOGGING_LEVEL` to `DEBUG` for more details. For CLI, use `--log-level DEBUG`.

## License

MIT - See [LICENSE](LICENSE) for details.