OpenTester MCP Server

OpenTester

MCP-First Testing Execution Infrastructure

OpenTester is a testing execution engine designed for AI coding tools (Claude Code, Cursor, OpenCode, etc.). It provides a unified DSL format and MCP interface, enabling Agents to generate, execute, and manage test cases, achieving an automated "code-test-fix" workflow.

Core Positioning

┌─────────────────────────────────────────┐
│  AI Agent (Claude Code / Cursor / ...)  │
│  ├─ Generate DSL test cases             │
│  ├─ Decide testing strategies           │
│  └─ Analyze failure reasons             │
├─────────────────────────────────────────┤
│  OpenTester (MCP Server)                │
│  ├─ Validate DSL syntax                 │
│  ├─ Execute tests (CLI/Web)             │
│  ├─ Store cases/projects                │
│  └─ Return structured results           │
├─────────────────────────────────────────┤
│  Web UI (Auxiliary Observation Panel)   │
│  ├─ View execution progress             │
│  ├─ Debug cases (create/edit)           │
│  └─ View history reports                │
└─────────────────────────────────────────┘

Design Principles:

• Agent Intelligence: Test generation and failure analysis are handled by the Agent
• OpenTester Execution: Focuses on DSL validation and test execution
• MCP-First: All core features exposed through MCP
• Web UI Auxiliary: Visual monitoring and debugging, not required

Installation

Option 1: Install from PyPI (Recommended)

pip install opentester

# Or with uv
uv pip install opentester

Option 2: Install from Source

# Clone repository
git clone https://github.com/kznr02/OpenTester.git
cd OpenTester

# Install backend
uv pip install ./backend

# Install frontend dependencies (optional)
cd frontend
npm install

Option 3: Direct Run (Development)

cd backend
uv run opentester start

Quick Start

Start Services

# Start both FastAPI + MCP (foreground mode with prefixed logs)
opentester start

# Daemon mode (detached background with log files)
opentester start --daemon

# Start only API
opentester start --api

# Start only MCP
opentester start --mcp

# Custom ports
opentester start --api-port 8080 --mcp-port 8081

# Check status
opentester status

# Stop services
opentester stop

# Environment check
opentester doctor

Foreground Mode Log Output:

[API] INFO:     Started server process [12345]
[API] INFO:     Waiting for application startup.
[MCP] INFO:     Started MCP server on port 8001
[API] INFO:     Application startup complete.

Configure Claude Code (Streamable HTTP)

Add MCP configuration in .claude/settings.json:

{
  "mcpServers": {
    "opentester": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

Note: Current runtime transport is Streamable HTTP.

Usage Example

Conversation with Claude Code:

You: Help me test the login functionality

Claude: I'll create tests for the login feature...
        [Generate DSL test case]
        [Call MCP: validateDSL] ✓ Validation passed
        [Call MCP: createProject] ✓ Project created
        [Call MCP: saveCase] ✓ Case saved
        [Call MCP: runCase]
        Executing...
        ✓ All passed

Project Structure

OpenTester/
├── backend/              # FastAPI + Python
│   ├── opentester/
│   │   ├── api/         # REST API (for Web UI)
│   │   ├── core/        # Execution engine, storage
│   │   ├── models/      # Pydantic models (DSL, Project)
│   │   └── mcp/         # MCP Server (core)
│   └── pyproject.toml
├── frontend/            # React + TypeScript + Vite
│   └── src/             # Web UI (observation panel)
├── docs/
│   ├── SKILL_PROMPT.md  # Agent Skill Prompt template
│   ├── DSL_SPEC.md      # DSL syntax specification
│   └── MCP.md           # MCP interface documentation
├── README.md            # This document
└── LICENSE              # MIT License

Core Features

1. DSL Validation

After Agent generates DSL, OpenTester validates syntax correctness:

version: "1.0"
meta:
  name: "Login Test"
steps:
  - action: exec
    command: "curl http://localhost:3000/login"
  - action: assert
    assertion:
      type: stdout_contains
      expected: "token"

2. Test Execution

Supports execution targets:

• CLI: subprocess command execution (implemented)
• WEB: Playwright-based browser automation (implemented)
• GUI: experimental executor routing (disabled by default)
• TUI: experimental executor routing (disabled by default)

3. Web Testing MVP + AI DOM Analysis

• Web