# Universal Test Framework

> Universal Test Framework is an open-source MCP server for developer tools. MCP server that enforces a quality contract on AI-generated tests across several languages. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** vscode, CLI, API, self-hosted, Linux, macOS, Windows
- **Repository:** https://github.com/phoenice-labs/universal-test-framework
- **MCP Registry name:** io.github.phoenice-labs/universal-test-framework
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

The README describes UTF as a contract enforcement engine that sits behind AI coding assistants rather than replacing them. Each generated test must pass an eight-section contract covering its ID, requirement link, GIVEN/WHEN/THEN scenario, expected outcome, known gaps and a self-assessment, with a minimum score of 0.85 before it is kept.

Tests and their results are stored in a per-project SQLite registry under a .utf folder, so coverage gaps, traceability and compliance reports can be reviewed across sessions. The README says the server can also import JUnit XML from existing test runs and produce HTML, JUnit or JSON compliance reports.

The README positions it for developers and teams who already use AI assistants such as Copilot, Claude or Cursor and want a verification and reporting layer on the generated tests. It can be run over stdio via uvx, from a local clone, in Docker over HTTP/SSE, or as a Python SDK in CI scripts.

## Features

- **Eight-section test contract:** Each test must include an ID, requirement mapping, scenario, expected outcome, gaps and a self-check, or it is blocked.
- **Per-project test registry:** Generated and executed test records are kept in a local SQLite database inside each project's .utf folder.
- **Traceability and gap analysis:** Builds requirement-to-test traceability matrices and reports uncovered symbols and missing paths.
- **Compliance reporting:** Produces HTML, JUnit XML and JSON reports that show contract detail cards alongside pass and fail results.
- **Multi-language test support:** Generates tests for Python, TypeScript, JavaScript, Java, Go and C++ using the frameworks listed in the README.
- **Multiple install modes:** Runs via uvx, a local clone with a VS Code install script, Docker over HTTP/SSE, or a pip-installed Python SDK.

## Good for

- Reviewing AI-generated unit tests before merging them into a codebase
- Mapping requirement IDs such as user stories to the tests that cover them
- Gating pull requests in CI by validating test files against the contract
- Importing JUnit XML results from an existing pytest or Maven run into a compliance report
- Tracking coverage gaps and trends for a project across sessions

## Install

### Claude Code (Terminal)

```sh
claude mcp add universal-test-framework -- uvx universal-test-framework
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "universal-test-framework": {
      "command": "uvx",
      "args": [
        "universal-test-framework"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "universal-test-framework": {
      "command": "uvx",
      "args": [
        "universal-test-framework"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "universal-test-framework": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "universal-test-framework"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "universal-test-framework": {
      "command": "uvx",
      "args": [
        "universal-test-framework"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "universal-test-framework": {
      "command": "uvx",
      "args": [
        "universal-test-framework"
      ]
    }
  }
}
```

## Tools

- `generate_tests`: Generate a complete test suite satisfying the 8-section contract
- `validate_test_contract`: Validate any test (generated or hand-written) against the contract
- `analyze_coverage`: Identify coverage gaps in an existing test suite
- `build_traceability_matrix`: Build a requirements to tests traceability matrix
- `suggest_test_types`: Recommend test types with rationale from source code
- `detect_language_framework`: Auto-detect programming language and test framework
- `import_test_results`: Import JUnit XML from any test run into the UTF registry
- `query_registry`: Query the persistent per-project test registry
- `run_tests`: Execute test files and return structured CI results
- `run_mutation_tests`: Run mutation testing and return mutation score
- `feedback_status`: Get gap analysis, coverage health, and trend report
- `generate_report`: Generate HTML / JUnit / JSON contract compliance report
- `health`: Server health check: version, uptime, tool count

## FAQ

### How do I install UTF in VS Code?

The README gives a uvx entry for mcp.json that runs the universal-test-framework package with utf-server, with cwd and UTF_PROJECT_DIR set to the workspace folder.

### Where is the test registry stored?

The README says it is stored at .utf/utf.db inside the project directory, isolated per project and persistent across sessions.

### What is the minimum passing score for a generated test?

The README states the minimum passing score is 0.85, and tests below that are blocked.

### Which languages and test frameworks are supported?

The README lists Python with pytest, TypeScript with Jest, Vitest or Playwright, JavaScript, Java with JUnit 5, Go with go-test and testify, and C++ with Google Test.

### Is UTF open source?

The README says it is released under the MIT licence.

### Is Universal Test Framework free?

Yes. Universal Test Framework is open source, so you can use and self-host it for free.

### How do I add Universal Test Framework to Claude Code?

Run this command in your terminal: claude mcp add universal-test-framework -- uvx universal-test-framework

### What are the best alternatives to Universal Test Framework?

The closest alternatives to Universal Test Framework are Testing, Ai Test Process MCP, Test Intel, TestMu AI (formerly LambdaTest) and MCP Test Utils.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Testing](https://ai-powered.com/mcp/testing): Testing is an open-source MCP server for developer tools.
- [Ai Test Process MCP](https://ai-powered.com/mcp/ai-test-process-mcp): Ai Test Process MCP is an open-source MCP server for developer tools.
- [Test Intel](https://ai-powered.com/mcp/test-intel): Test Intel is an open-source MCP server for developer tools.
- [TestMu AI (formerly LambdaTest)](https://ai-powered.com/mcp/testmu-ai-formerly-lambdatest): TestMu AI (formerly LambdaTest) is a freemium MCP server for developer tools.
- [MCP Test Utils](https://ai-powered.com/mcp/mcp-test-utils): MCP Test Utils is a free MCP server for developer tools.
- [Testiny Test Management](https://ai-powered.com/mcp/testiny-test-management): Testiny Test Management is a paid MCP server for developer tools.
- [MCP Test Runner](https://ai-powered.com/mcp/mcp-test-runner): MCP Test Runner is an open-source MCP server for developer tools.
- [Api Test MCP](https://ai-powered.com/mcp/api-test-mcp): Api Test MCP is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/universal-test-framework
