{
  "servers": {
    "utf": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "universal-test-framework", "utf-server", "--transport", "stdio"],
      "cwd": "${workspaceFolder}",
      "env": {
        "UTF_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

git clone https://github.com/phoenice-labs/Universal-Test-Framework
cd Universal-Test-Framework

# Register MCP server, install @utf extension, copy global prompts
.\scripts\install-vscode-mcp.ps1

# Optionally scaffold a specific project
.\scripts\install-vscode-mcp.ps1 -InitProject -ProjectDir C:\my-project

{
  "utf": {
    "type": "stdio",
    "command": "<python>",
    "args": ["-m", "mcp_server.server", "--transport", "stdio"],
    "cwd": "${workspaceFolder}",
    "env": { "PYTHONPATH": "<UTF_install_dir>" }
  }
}

# Start the UTF server
cd Universal-Test-Framework
docker compose -f docker/docker-compose.yml up -d

# MCP server available at http://localhost:8765/sse

{
  "servers": {
    "utf-remote": {
      "type": "sse",
      "url": "http://localhost:8765/sse"
    }
  }
}

# docker-compose.override.yml
services:
  utf-server:
    volumes:
      - ./my-project/.utf:/app/.utf
    environment:
      UTF_PROJECT_DIR: /app

pip install universal-test-framework

from mcp_server.tools.generate_tests import generate_tests
from pathlib import Path

result = generate_tests(
    test_type="unit",
    source_code=open("src/auth.py").read(),
    project_dir=str(Path.cwd()),   # ← pass explicitly for correct registry isolation
)
print(result["suite_code"])

┌─────────────────────────────────────────────────────────────────────────┐
│  PHASE 1 — CONTRACT GENERATION (LLM writes, UTF validates + registers) │
│                                                                         │
│  ① generate_tests (scaffold)                                           │
│  ② LLM writes real test methods — each with its own TC-ID and         │
│     8-section comment block (WHY / REQ / HOW / COV / OUT / GAP / MEAN)│
│  ③ validate_test_contract — score must be ≥ 0.85 per test             │
│  ④ register_contracts — parse test file, upsert status=generated rows  │
│  ⑤ generate_report — verify Per-Test Contract Detail cards appear      │
│                                                                         │
│  PHASE 2 — EXECUTION (pytest/jest/maven runs, results captured)        │
│                                                                         │
│  ⑥ pytest --junit-xml=utf-tests/reports/results.xml                   │
│  ⑦ import_test_results — upsert executed/failed rows                   │
│  ⑧ generate_report — now shows contract cards AND pass/fail status     │
│                                                                         │
│  PHASE 3 — HEALTH (ongoing coverage quality)                           │
│                                                                         │
│  ⑨ feedback_status — gap analysis, drift alerts, trend over 30 days   │
│  ⑩ Address gaps → add tests → back to Phase 1                         │
└─────────────────────────────────────────────────────────────────────────┘

def test_health_returns_200(self, live_backend):
    # ─── TC-FIQ-HLT-001 ──────────────────────────────────────────────────────
    # WHY_GENERATED: The /health endpoint is the primary liveness signal for
    #   load balancers and K8s probes. Non-200 = platform unavailable.
    # REQUIREMENT_MAPPING: REQ-E2E-001
    # HOW_IT_EXERCISES: GIVEN backend is running at http://localhost:8001
    #   WHEN GET /health is called THEN HTTP 200 is returned.
    # COVERAGE_CONTRIBUTION: Line coverage of health route; ~15% of health module
    # EXPECTED_OUTCOME: HTTP 200; elapsed < 500ms
    # GAPS_MISSING: Does not test health under load; no auth header tested
    # MEANINGFULNESS_CHECK: Meaningful — gateway test for all other tests
    # ─────────────────────────────────────────────────────────────────────────
    r = requests.get(f"{live_backend}/health", timeout=5)
    assert r.status_code == 200

# Phase 1 — Generate and register
generate e2e tests for backend/app/api/routes/
register contracts for utf-tests/test_myapp_e2e.py
utf report

# Phase 2 — After running pytest
import junit xml utf-tests/reports/results.xml
utf report

# Phase 3 — Health check
utf status
what are my coverage gaps?
build a traceability matrix

# Natural language triggers UTF MCP tools automatically
"Generate e2e tests for my FastAPI backend at backend/app/"
"Register contracts for utf-tests/test_myapp_e2e.py"
"Generate the UTF report"
"Show UTF status and gaps"
"Validate this test against the 8-section contract: [paste test]"

{
  "mcpServers": {
    "utf": {
      "command": "uvx",
      "args": ["--from", "universal-test-framework", "utf-server", "--transport", "stdio"],
      "env": { "UTF_PROJECT_DIR": "/path/to/your/project" }
    }
  }
}

{
  "mcpServers": {
    "utf": {
      "command": "uvx",
      "args": ["--from", "universal-test-framework", "utf-server", "--transport", "stdio"],
      "cwd": "${workspaceFolder}",
      "env": { "UTF_PROJECT_DIR": "${workspaceFolder}" }
    }
  }
}

Generate unit tests for src/auth.py using UTF
UTF report
Register contracts for tests/test_api.py

{
  "utf": {
    "type": "stdio",
    "command": "uvx",
    "args": ["--from", "universal-test-framework", "utf-server", "--transport", "stdio"],
    "cwd": "${workspaceFolder}",
    "env": { "UTF_PROJECT_DIR": "${workspaceFolder}" }
  }
}

# In the GitHub Copilot CLI terminal (gh copilot / copilot-cli)
generate unit tests for backend/app/routes/auth.py
generate e2e tests covering REQ-001 through REQ-024
register contracts for utf-tests/test_myapp_e2e.py
utf report
show utf status
validate this test against the 8-section contract
what are the coverage gaps?
suggest test types for my project
build a traceability matrix

your-project/
└── .utf/
    ├── utf.db          ← SQLite registry (persists between sessions)
    ├── utf-config.yaml ← Optional project overrides
    ├── rules/          ← Optional YAML rule overrides
    └── reports/
        ├── contract_YYYYMMDD_HHMMSS.html
        ├── contract_YYYYMMDD_HHMMSS.xml
        └── contract_YYYYMMDD_HHMMSS.json

generate unit tests for src/auth.py in project C:/my-project

generate unit tests for this file
show utf status
utf report
what are my coverage gaps?
validate this test against the contract

from mcp_server.tools.generate_tests import generate_tests
from mcp_server.tools.validate_contract import validate_test_contract

# Generate tests — UTF infers language, framework, and requirements
result = generate_tests(
    test_type="unit",
    source_code=open("src/auth.py").read(),
    requirements_text="US-101: Users must be authenticated before accessing dashboard",
)

print(result["suite_code"])          # Executable test file
print(result["traceability_matrix"]) # Requirements → tests mapping
print(result["gaps"])                # Identified coverage gaps

# Validate any existing test
validation = validate_test_contract(test_content=my_test_markdown)
print(f"Score: {validation['score']:.0%}  Valid: {validation['is_valid']}")

# .github/workflows/test-quality-gate.yml
name: UTF Contract Gate
on: [push, pull_request]
jobs:
  contract-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pip install universal-test-framework
      - name: Validate test contract
        run: |
          python - <<'EOF'
          from mcp_server.tools.validate_contract import validate_test_contract
          import glob, sys, pathlib

          failures = []
          for f in glob.glob("tests/**/*.py", recursive=True):
              content = pathlib.Path(f).read_text()
              result = validate_test_contract(test_content=content)
              if not result["is_valid"]:
                  failures.append(f"{f}: score {result['score']:.0%}")
          if failures:
              print("Contract failures:\n" + "\n".join(failures))
              sys.exit(1)
          print("All tests passed contract validation")
          EOF

# Raise minimum score for safety-critical code
contract:
  min_score: 0.90          # default: 0.85
  hard_block_below: 0.75

# Match your Jira project key
traceability:
  requirement_id_pattern: "^(PROJ-\\d+|AC-\\d+(\\.\\d+)?|NFR-\\d+)$"

# Tests generated per requirement per type
scenario_counts:
  happy_path: 1
  negative: 2
  boundary: 1
  edge_case: 1

# Coverage advisory thresholds (appear in report, do not block)
coverage:
  line_target: 85
  branch_target: 75
  mutation_score_target: 70

UTF MCP Server (stdio or HTTP/SSE)
│
├── mcp_server/server.py         — FastMCP entrypoint, 13 registered tools
│
├── mcp_server/engine/           — Core processing
│   ├── language_detector.py     — Detects language + framework from code/path
│   ├── rule_engine.py           — Loads and merges YAML rules
│   ├── contract_validator.py    — Enforces 8-section contract, scores tests
│   ├── template_renderer.py     — Jinja2 test file generation
│   ├── context_resolver.py      — Resolves project context for generation
│   └── framework_mapper.py      — Maps language → framework → test runner
│
├── mcp_server/tools/            — One module per MCP tool
├── mcp_server/registry/         — SQLite per-project test registry
├── mcp_server/execution/        — pytest, Vitest, Maven, go-test adapters
├── mcp_server/mutation/         — mutmut, Stryker, PIT, Gremlins adapters
├── mcp_server/reporting/        — HTML, JUnit XML, JSON report generation
├── mcp_server/feedback/         — CI listener, trend analysis, gap reopener
│
├── rules/                       — Global YAML rules (language, framework, type)
├── templates/                   — Jinja2 test templates per language/framework
├── agent-customization/         — VS Code copilot-instructions + prompt palette
└── vscode-extension/            — @utf VS Code Chat Participant (VSIX)

1. project_dir argument (explicit per-tool call)
2. UTF_PROJECT_DIR environment variable
3. Path.cwd() at server start (fallback — avoid for multi-project use)