UUV MCP Server: Human-Readable End-to-End Tests

Overview

The UUV MCP Server implements the Model Context Protocol (MCP) to produce human-readable end-to-end tests from model-driven prompts. It acts as a lightweight HTTP server that accepts structured MCP requests, forwards them to a configured language model and any registered tools, and returns deterministic, reviewable test artifacts. The result is an automated way to generate end-to-end test scenarios that are easy for engineers and reviewers to read, modify, and run in CI pipelines.

This approach separates intent (what to test) from format (how the test should look) by using MCP as the exchange format. That makes test generation reproducible, auditable, and easier to iterate on: a single server can be run locally, in CI, or as part of a microservice architecture to centralize test generation and review workflows.

Features

• Generate human-readable end-to-end tests from structured MCP prompts.
• Pluggable model backends (OpenAI-compatible or other LLMs).
• Tool integration: shell, HTTP client, file system, test runner hooks.
• Simple HTTP API with endpoints for generation, validation, and history.
• Configurable output templates so tests match your project style.
• Docker-friendly for CI and ephemeral environments.
• Request/response logging for auditability and review.

Installation / Configuration

Prerequisites: Node.js 18+ and npm or yarn.

Clone and install dependencies:

git clone https://github.com/e2e-test-quest/uuv.git
cd uuv/packages/mcp-server
npm install

Run locally in development:

# start dev server
npm run dev
# or start in production mode
npm run build
npm start

Environment variables (example):

export MCP_PORT=8080
export MODEL_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export MCP_STORAGE_DIR=./mcp-data

Minimal config file (mcp-config.json):

{
  "port": 8080,
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.0
  },
  "templatesDir": "./templates",
  "tools": ["http", "shell", "filesystem"]
}

Run with Docker:

docker build -t uuv-mcp-server .
docker run -p 8080:8080 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e MCP_PORT=8080 \
  uuv-mcp-server

Available Resources

API endpoints (default base: http://localhost:8080):

Example /generate request body (MCP-style):

{
  "mcp_version": "1.0",
  "intent": "Create e2e test for user signup flow",
  "context": {
    "app_url": "https://staging.example.com",
    "auth": { "type": "oauth" }
  },
  "output_format": "jest-playwright",
  "options": { "locale": "en-US" }
}

Typical response:

{
  "status": "ok",
  "test_name": "signup.spec.js",
  "test_body": "describe('User signup', () => { ... })",
  "metadata": { "model": "gpt-4o-mini", "seed": "..." }
}

Available Tools

The server supports a set of tool integrations that MCP prompts can request during generation. Tools are implemented as pluggable handlers.

Common built-in tools:

• http — make authenticated HTTP calls to verify external APIs or gather fixtures.
• shell — run shell commands to inspect repository structure or run linters.
• filesystem — read/write project files for templating or snapshot comparison.
• test-runner — invoke local test runners to validate a generated test quickly.

Register additional tools by adding modules to the server’s tools directory and referencing them in the config. Each tool exposes a small JSON-based RPC surface that MCP can call as part of generation.

Use Cases

1. CI-driven E2E test generation

   • Generate human-readable tests during PR checks to validate new features.
   • Example: A PR creates an API; MCP generates a Playwright test that hits the new endpoints, and the CI runs the test in a temp environment.

2. Test scaffolding for new features

   • Generate starter tests from a feature description so engineers can quickly iterate.
   • Example request: intent “e2e test for checkout with coupon” → server returns a complete test file matching project test style.

3. Reviewable test diffs

   • Use /history to surface generated tests for code review, making AI-generated changes auditable.
   • Preserve generation seed and model metadata to reproduce results.

4. Continuous validation

   • Run /validate as a final gate to ensure generated tests conform to linters, coding standards, and internal test policies before merging.

Getting Started Examples

Generate a test with curl:

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_version": "1.0",
    "intent": "e2e test user login",
    "context": {"app_url":"http://localhost:3000"},
    "output_format": "playwright"
  }'

Fetch recent generations:

curl http://localhost:8080/history

Where to find the code

Source and issues: https://github.com/e2e-test-quest/uuv/tree/main/packages/mcp-server

For contributions, review the repository README and open issues for feature requests or bug reports.