GroundNG (QA for Cursor) MCP server

This MCP server provides an AI-powered agent for streamlining web testing workflows. It integrates with AI coding assistants through the Machine Command Protocol (MCP), allowing you to automate test recording, execution, and discovery using natural language.

Features

• AI-Assisted Test Recording: Generate Playwright test scripts from natural language descriptions
• Deterministic Test Execution: Run recorded JSON test files reliably with Playwright
• Test Discovery: Crawl websites and use any OpenAI-compatible LLM to suggest test steps
• Regression Testing: Catch regressions by running existing test suites
• Self-Healing Tests: Tests adapt to code changes without manual updates
• UI Testing: Supports tests beyond standard Playwright capabilities
• Visual Regression Testing: Combines traditional pixel matching with vision LLM approach

Installation

Prerequisites

• Python 3.10+
• Access to any LLM (Gemini 2.0 Flash recommended for free tier)
• MCP installed
• Playwright browsers installed

Setup Steps

1. Clone the repository:

   git clone <repository-url>
   cd <repository-name>
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   # venv\Scripts\activate  # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Install Playwright browsers:

   playwright install --with-deps
   

Configuration

1. Rename .env.example to .env in the project root directory
2. Add your LLM API key:

   LLM_API_KEY="YOUR_LLM_API_KEY"
   

Adding the MCP Server

Add this to your MCP config:

{
  "mcpServers": {
    "Web-QA": {
      "command": "uv",
      "args": ["--directory", "path/to/cloned_repo", "run", "mcp_server.py"]
    }
  }
}

Usage

Interact with the agent through your MCP-enabled AI coding assistant using natural language.

Example Commands

Record a Test:

"Record a test: go to https://practicetestautomation.com/practice-test-login/, type 'student' into the username field, type 'Password123' into the password field, click the submit button, and verify the text 'Congratulations student' is visible."

The agent will perform these actions automatically and save a test JSON file in the output/ directory.

Execute a Test:

"Run the regression test output/test_practice_test_login_20231105_103000.json"

The agent will execute the steps in the file and report PASS/FAIL status with details.

Discover Test Steps:

"Discover potential test steps starting from https://practicetestautomation.com/practice/"

The agent will crawl the site, analyze pages, and return suggested test steps.

List Recorded Tests:

"List the available recorded web tests."

The agent will return a list of JSON files found in the output/ directory.

Output

• Recorded Tests: Saved as JSON files in the output/ directory
• Execution Results: Returned as a JSON object summarizing the run
• Discovery Results: Returned as a JSON object with discovered URLs and suggested steps

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.