npm.io
0.26.0 • Published 2d agoCLI

@uuv/mcp-server

Licence
MIT
Version
0.26.0
Deps
19
Size
176 kB
Vulns
0
Weekly
0
Stars
156
SummaryDependencyVersions

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 Format Required Description examples
UUV_LLM_MODEL <provider>/<modelName> Yes Specifies the LLM model used by the MCP server. -anthropic/claude-sonnet-4-6
-ollama/qwen3.6:35b
UUV_JSON_FLAT_MODEL_ENABLED boolean Recommended (true for Anthropic/Gemini) Enables flat JSON output formatting (strongly recommended for Anthropic and Gemini models) -true
-false
UUV_LLM_API url Optional (Required only for Ollama) Base API endpoint for local Ollama models http://localhost:11434
UUV_API_ENABLED boolean Optional (true by default) Enables the internal image-classification API server powered by the configured LLM model -true
-false

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