UUV MCP Server

Introduction

@uuv/mcp-server is a Model Context Protocol (MCP) server for UUV — a solution that facilitates the writing and execution of end-to-end (E2E) tests understandable by any human being (English or French) using Cucumber (BDD) and Playwright or Cypress.

As an MCP server, @uuv/mcp-server acts as a bridge between AI models and E2E testing capabilities. It enables AI assistants to generate human-readable Gherkin test scenarios for web applications, supporting both English and French languages. The server integrates with popular LLM providers (OpenAI, Anthropic, Google, Ollama) to provide AI-driven test generation and validation.

Key Benefits

• AI-Powered Test Generation: Automatically generates Gherkin scenarios from natural language descriptions
• Accessibility-First: Tests are designed with accessibility in mind using ARIA roles and names
• Framework Agnostic: Works with Playwright and Cypress
• BDD Compliance: Uses Gherkin syntax for clear, readable test specifications
• Multi-Language Support: Test scenarios can be written in English or French

Setup

Requirements

• Node.js 20 or higher

Supported LLMs

@uuv/mcp-server supports the following LLM providers:

• OpenAI: openai/gpt-4.1, openai/gpt-3.5-turbo, etc.
• Anthropic: anthropic/claude-haiku-4-5, anthropic/claude-sonnet-4-6, etc.
• Google: google/gemini-2.0-flash, google/gemini-pro, etc.
• Ollama: ollama/qwen3-coder-next, ollama/llama3, etc.

MCP Configuration

Standard MCP Configuration

{
    "mcpServers": {
        "uuv": {
            "command": "npx",
            "args": ["@uuv/mcp-server@latest"],
            "env": {
                "UUV_LLM_MODEL": "anthropic/claude-haiku-4-5",
                "UUV_JSON_FLAT_MODEL_ENABLED": true
            }
        }
    }
}

Opencode Configuration

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "uuv": {
            "type": "local",
            "command": ["npx", "@uuv/mcp-server@latest"],
            "enabled": true,
            "timeout": 300000,
            "environment": {
                "UUV_LLM_MODEL": "anthropic/claude-sonnet-4-6"
            }
        }
    }
}

For a dedicated agent configuration, see: uuv-assistant.md

Claude Code Configuration

Add the UUV MCP server via CLI:

claude mcp add uuv npx @uuv/mcp-server@latest

Gemini CLI Configuration

gemini extensions install https://github.com/e2e-test-quest/uuv --auto-update

---

Environment Variables

Environment Variable	Required	Description
UUV_LLM_MODEL	Yes	Specifies the LLM model used by the MCP server. Format: <provider>/<modelName>
UUV_JSON_FLAT_MODEL_ENABLED	Recommended (true for Anthropic/Gemini)	Enables flat JSON output formatting (strongly recommended for Anthropic and Gemini models)
UUV_LLM_API	Optional (Ollama only)	Base API endpoint for local Ollama models

Usage (MCP Prompts)

Two generation modes: smart exploration vs. targeted generation

The @uuv/mcp-server offers two complementary approaches to generate your e2e tests.

---

🔍 Prompts with automatic application exploration

These two prompts are unique: they actually navigate your application to understand its structure before generating tests. No more manual parameters to fill in — the AI explores, analyzes, and produces scenarios tailored to your real interface.

Template	Purpose	Key Parameters
genNominalTestCase	Generates a full test scenario (happy path) by exploring the app	testCase
genTestExpectTable	Verifies table content by inspecting real data	baseUrl, innerHtmlFilePath

Why is this powerful? Rather than describing what you want to test, you simply describe your intent — the MCP server takes care of exploring your application, identifying relevant elements, and generating a test that matches your actual interface.

---

⚡ Targeted generation prompts

These prompts generate precise tests from parameters you provide. Perfect for specific use cases when you know exactly which element to target.

Template	Purpose	Key Parameters
installUuvDependency	Install @uuv/playwright	—
checkUuvDependency	Check installation status	—
getUuvVersion	Get package version	—
genTestClickRoleAndName	Click an element via ARIA	accessibleName, accessibleRole
genTestClickDomSelector	Click an element via CSS selector	domSelector
genTestTypeRoleAndName	Type into a field	accessibleName, accessibleRole
genTestExpectDomSelector	Verify element existence (CSS)	domSelector
genTestExpectRoleAndName	Verify element existence (ARIA)	accessibleName, accessibleRole
genTestWithinRoleAndName	Focus within an element (ARIA)	accessibleName, accessibleRole
genTestWithinDomSelector	Focus within an element (CSS)	domSelector

All these prompts follow a consistent three-step pattern:

1. Retrieve the base URL via uuv_getBaseUrl
2. Generate the test with the appropriate uuv_gen* tool
3. Write the .feature file to ./uuv/e2e

---

Examples

Verify element presence — genTestExpectRoleAndName

• baseUrl: https://example.com
• accessibleRole: button
• accessibleName: Login

Click an element — genTestClickRoleAndName

• baseUrl: https://example.com
• accessibleRole: link
• accessibleName: Products

Type into a form field — genTestTypeRoleAndName

• baseUrl: https://example.com
• accessibleRole: textbox
• accessibleName: Search
• value: laptop

MCP Tools

This MCP server exposes the following tools:

getBaseUrl

• Description: Retrieve project base url for generated UUV tests. In terms of priority, the UUV_BASE_URL environment variable is read, and if it is empty, the value of the baseURL field in the projectPath/uuv/playwright.config.ts or projectPath/uuv/cypress.config.ts file is checked.
• Input Schema:
  • projectPath (string): Project absolute path

availableSentences

• Description: List all available UUV test sentences/phrases in Gherkin format.
• Input Schema:
  • category (enum, optional): Filters sentences by action type (general, keyboard, click, contains, type, checkable)
  • role (string, optional): Filters sentences related to an accessible role

genTestExpectRoleAndName

• Description: Generate a complete UUV test scenario (Gherkin format) to verify the presence of an element with specified role and name.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • accessibleRole (string): Accessible role of the element
  • accessibleName (string): Accessible name of the element

genTestExpectDomSelector

• Description: Generate a complete UUV test scenario (Gherkin format) to verify the presence of an element with specified domSelector.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • domSelector (string): Dom selector of the element

genTestClickRoleAndName

• Description: Generate a complete UUV test scenario (Gherkin format) that clicks on html element with specified role and name.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • accessibleRole (string): Accessible role of the element
  • accessibleName (string): Accessible name of the element

genTestClickDomSelector

• Description: Generate a complete UUV test scenario (Gherkin format) that clicks on html element with specified domSelector.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • domSelector (string): Dom selector of the element

genTestWithinRoleAndName

• Description: Generate a complete UUV test scenario (Gherkin format) that focus within a html element with specified role and name.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • accessibleRole (string): Accessible role of the element
  • accessibleName (string): Accessible name of the element

genTestWithinDomSelector

• Description: Generate a complete UUV test scenario (Gherkin format) that focus within a html element with specified domSelector.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • domSelector (string): Dom selector of the element

genTestTypeRoleAndName

• Description: Generate a complete UUV test scenario (Gherkin format) that types a value into an html element with specified role and name.
• Input Schema:
  • baseUrl (string): The base URL of the page where the element is located
  • accessibleRole (string): Accessible role of the element
  • accessibleName (string): Accessible name of the element

genTestExpectTable (Experimental)

• Description: Generate a complete UUV test scenario (Gherkin format) to verify the presence and content of html table, grid or treegrid.
• Input Schema:
  • baseUrl (string): The base URL of the page where the table/grid/treegrid is located
  • innerHtmlFilePath (string): File path containing the raw innerHTML content

genNominalTestCase (Experimental)

Supported LLM provider are openai, anthropic, google and ollama

• Description: Generate a complete UUV test scenario (Gherkin format) for the nominal case using AI-driven browser exploration with Playwright tools.
• Input Schema:
  • testCase (string): Brief description of the test scenario to be generated

installUuvDependency

• Description: Install @uuv/playwright npm package.
• Input Schema:
  • projectPath (string): Path to the project directory
  • packageName (string, optional): Optional package name to install (default: @uuv/playwright)

checkUuvDependency

• Description: Check if @uuv/playwright is installed.
• Input Schema:
  • projectPath (string): Path to the project directory

getUuvVersion

• Description: Get the current version of @uuv/playwright npm package.
• Input Schema:
  • projectPath (string): Path to the project directory