universal-test-framework

通用测试框架（UTF）

通过 MCP、VS Code、Copilot CLI、Claude、Cursor 或 Python SDK，为大模型生成的代码提供契约驱动的测试强制执行和报告。

UTF 是一个MCP 服务和契约强制执行引擎。它不会取代你的 AI 编码助手，而是为 AI 编写的每项测试设置强制质量门槛、提供结构化审计跟踪，并生成全面的合规报告。

---

为什么选择 UTF？（不只是另一个测试生成器）

AI 工具——GitHub Copilot、Claude、Cursor、Gemini——生成测试很快。问题在于：快 ≠ 可信。

不使用 UTF	使用 UTF
测试已存在，但没人知道原因	每项测试都关联一项需求
“覆盖了所有内容”——却无人能证明	可追溯性矩阵将需求映射到测试
CI 通过了，实际行为却未经过测试	差距分析会标记未覆盖的内容
大模型编写的测试断言 True	有效性检查会拒绝琐碎断言
没有测试记录	持久化注册表可在会话重启后保留
报告只显示通过/失败计数	HTML 报告中每项测试都有包含 8 个部分的详情卡片

UTF 与 Markdown 指令文件 / 提示词文件

你可能已经在使用 Markdown 文件（AGENTS.md、copilot-instructions.md、.cursorrules）来指导 AI。UTF 与这些文件互为补充，而非相互竞争：

Markdown 指令	UTF
描述测试该如何编写	对每项生成的测试强制执行契约
依赖大模型遵循指令	在生成时阻止不符合契约的测试
生成后不做验证	根据 8 项可衡量标准为每项测试评分，范围为 0–1
会话之间没有持久状态	SQLite 注册表会持久保存所有测试及结果
没有合规报告	HTML 报告包含每项测试的 8 部分详情卡片

使用 Markdown 指令来塑造 AI 的思考方式。使用 UTF 来验证并报告 AI 的产出。

---

主要功能

• 13 个 MCP 工具——生成、验证、注册、分析、追溯、执行、变异、报告和查询测试
• 6 种语言——Python、TypeScript、JavaScript、Java、Go、C++
• 7 种测试类型——单元、集成、API、E2E、契约、性能、安全
• 8 部分契约——每项测试都必须通过全部 8 个部分，否则会被阻止（最低分数：0.85）
• 3 段式测试 ID——接受 TC-{PRJ}-{MODULE}-{NNN} 和经典格式 TC-{MODULE}-{NNN}
• 五种安装方式——uvx（无需克隆）、本地克隆、Docker、GitHub MCP Registry、pip SDK
• VS Code @utf——带斜杠命令的聊天参与者
• 支持 CI/CD——GitHub Actions、GitLab CI、pre-commit hooks
• 项目级覆盖规则——.utf/rules/ 中的 YAML 规则可覆盖全局默认值

---

快速开始

设置方式比较

#	方式	启动方式	注册表位置	@utf 斜杠命令	最适合
1	uvx（零安装）	mcp.json + uvx	<workspace>/.utf/utf.db	❌ 使用自然语言	使用 uv 的任何开发者
2	本地克隆	install-vscode-mcp.ps1	<workspace>/.utf/utf.db	✅ 使用扩展	为 UTF 贡献代码／自定义 UTF
3	Docker／HTTP	docker compose up	命名卷或绑定挂载	❌ 使用自然语言	团队／远程／CI
4	GitHub MCP Registry	由客户端自动启动	<workspace>/.utf/utf.db	❌ 使用自然语言	通过 MCP 市场发现
5	pip + SDK	Python 导入	由调用方控制 cwd	不适用	CI 脚本／编程调用

所有使用 stdio 传输的方式（1、2、4）都会将注册表写入 ${workspaceFolder}/.utf/utf.db——每个项目独立，并在会话间持久保存。

---

方式 1 — uvx（零安装，推荐）

需要 uv。无需克隆，无需 venv。

添加到 %APPDATA%\Code\User\mcp.json（Windows）或 ~/.config/Code/User/mcp.json（macOS/Linux）：

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

注册表：${workspaceFolder} 内的 .utf/utf.db——每个项目独立，并在会话间持久保存。
编辑 mcp.json 后，重新加载 VS Code。

---

方式 2 — 本地克隆（VS Code + Copilot）

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

重新加载 VS Code → 打开 Copilot Chat → 用自然语言提问：generate e2e tests for my backend。

安装脚本会将此条目写入 mcp.json：

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

注册表：${workspaceFolder}/.utf/utf.db——每个项目独立。
安装 VSIX 扩展后，即可使用 @utf 斜杠命令。

---

方式 3 — Docker（团队／远程）

# 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

在 VS Code 中连接：将以下内容添加到 mcp.json：

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

注册表：持久保存在 Docker 命名卷中（utf_registry → /app/.utf/utf.db）。
如需通过 Docker 实现项目级隔离，请在 docker-compose.yml 中使用绑定挂载：

volumes:
  - /path/to/your/project/.utf:/app/.utf

由于 Docker 使用 HTTP/SSE 传输（不支持 ${workspaceFolder} 模板），请在工具调用中显式传递 project_dir， 或在容器环境中设置 UTF_PROJECT_DIR。

按项目使用 Docker 的工作流：

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

---

方式 4 — GitHub MCP Registry

发布后，即可通过 MCP 市场发现 UTF。支持 server.json 的客户端会自动安装。生成的 mcp.json 条目与方式 1（uvx）等效。

注册表隔离：MCP 注册表架构不支持在注册表级别设置 cwd 字段。
UTF 按以下优先顺序实现项目隔离：

1. 传递给每次工具调用的 project_dir 参数
2. UTF_PROJECT_DIR 环境变量
3. 回退到 Path.cwd()（服务的工作目录）

为确保正确隔离，请确保 MCP 客户端在生成的条目中写入 "cwd": "${workspaceFolder}" 和 "UTF_PROJECT_DIR": "${workspaceFolder}"（UTF 的 mcp-gallery.json 已设置这些内容）。

---

方式 5 — pip + Python SDK

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"])

注册表：传递 project_dir 时使用 <project_dir>/.utf/utf.db；否则回退到 Path.cwd()。

---

MCP 工具参考

工具	描述
generate_tests	生成满足 8 部分契约的完整测试套件
validate_test_contract	根据契约验证任意测试（生成或手写）
analyze_coverage	识别现有测试套件中的覆盖缺口
build_traceability_matrix	构建需求 → 测试可追溯矩阵
suggest_test_types	根据源代码推荐测试类型并说明理由
detect_language_framework	自动检测编程语言和测试框架
import_test_results	从任意测试运行中导入 JUnit XML 到 UTF 注册表
query_registry	查询持久化的项目级测试注册表
run_tests	执行测试文件并返回结构化的 CI 结果
run_mutation_tests	运行变异测试并返回变异分数
feedback_status	获取缺口分析、覆盖率健康状况和趋势报告
generate_report	生成 HTML / JUnit / JSON 契约合规报告
health	服务健康检查：版本、运行时间、工具数量

---

8 部分测试契约

UTF 生成的每个测试都必须满足全部 8 个部分。未通过任何硬性部分的测试都会被拦截——列入 blocked_tests，绝不会静默纳入。

#	部分	必须包含的内容	权重
1	test_id	唯一 ID：TC-{TYPE}-{NNN}（例如 TC-US-042）	10%
2	why_generated	与某项需求相关的理由（≥50 个字符）	10%
3	requirement_mapping	至少一个 US-、AC-、REQ-、JIRA-、BUG- 或 NFR- 引用	15%
4	how_it_exercises	包含输入、模拟对象和断言的 GIVEN / WHEN / THEN（≥100 个字符）	20%
5	coverage_contribution	覆盖类型 + 模块 + 估算百分比	15%
6	expected_outcome	明确的返回值、状态代码和状态变化（≥50 个字符）	15%
7	gaps_missing	如实列出此测试未覆盖的内容（≥40 个字符）	10%
8	meaningfulness_check	自我评估：有意义 / 冗余 / 幻觉（≥50 个字符）	5%

最低通过分数：0.85。 低于此阈值的测试无论各部分是否齐全都会被拦截。在缺口中填写“none”，或使用“用于测试该函数”这类含糊理由，都会被拒绝。

---

支持矩阵

语言	框架	测试类型
Python	pytest	单元、集成、API、端到端、安全、性能
TypeScript	Jest、Vitest、Playwright	单元、集成、端到端、API
JavaScript	Jest、Vitest	单元、集成
Java	JUnit 5 + AssertJ、Maven	单元、集成、API
Go	go-test + testify	单元、集成、API
C++	Google Test	单元

---

UTF 3 阶段端到端工作流

这是在任何 AI 命令行工具（Copilot、Claude、Cursor）或 VS Code 中使用 UTF 的标准流程。请按顺序执行各阶段——跳过阶段 1 注册会导致报告中没有“逐测试契约详情”卡片。

┌─────────────────────────────────────────────────────────────────────────┐
│  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                         │
└─────────────────────────────────────────────────────────────────────────┘

为什么要在运行前注册？ UTF 注册表有两种记录类型。status=generated 记录（由 register_contracts 创建） 会生成 HTML 报告中的“逐测试契约详情”卡片。status=executed/failed 记录 （由 import_test_results 创建）会生成“执行结果”表。测试必须同时存在这两种记录， 才会同时显示在这两个部分中。在注册之前运行 pytest，意味着你只能看到执行行， 而不会看到 8 部分详情卡片。

每个方法的 8 部分注释块（必填）

每个测试方法都必须有自己的内联注释块——不能使用类文档字符串：

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

接受的测试 ID 格式：TC-HLT-001（2 段）或 TC-FIQ-HLT-001（带项目前缀的 3 段）。

---

从 AI 命令行工具调用 UTF

GitHub Copilot CLI

通过自然语言调用 UTF 工具——无需特殊语法：

# 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

Claude (claude.ai / Claude CLI / MCP 客户端)

Claude 原生支持 MCP 服务。在 MCP 配置中添加 UTF 后：

# 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]"

要将 UTF 添加到 Claude 的 MCP 配置（~/.config/claude/mcp.json 或同等配置文件）：

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

Cursor

在 Cursor 中，将 UTF 添加为 MCP 服务，配置在 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）中：

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

然后用自然语言向 Cursor 提问：

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

任意兼容 MCP 的客户端（Windsurf、Continue 等）

无论使用哪种客户端，MCP 配置项都相同：

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

UTF 使用自然语言检测，因此相同的提示词可在所有兼容 MCP 的 AI 客户端中使用。

---

GitHub Copilot CLI 用法

在 GitHub Copilot CLI 中，通过自然语言调用 UTF——CLI 提示符下没有特殊的斜杠命令或 @utf 语法。只需描述你的需求，MCP 工具就会自动调用。

如何从 CLI 调用 UTF

# 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

完整命令参考（自然语言 → MCP 工具）

你说的话	调用的 UTF MCP 工具	执行内容
generate unit tests for <file>	generate_tests	扫描源代码、推断需求并生成包含 8 个部分的测试套件
generate e2e tests	generate_tests	生成包含正常流程、负向测试和边界情况的端到端测试套件
generate api tests	generate_tests	生成包含 HTTP 断言的 API 契约测试
generate security tests	generate_tests	生成认证、注入和边界安全测试
register contracts for <test_file.py>	register_contracts	解析测试文件，提取每个方法的 8 部分区块，并插入或更新生成的行
validate this test	validate_test_contract	根据全部 8 个契约部分为测试评分，范围为 0–1
utf status / show utf status	feedback_status	差距分析、覆盖率健康状况和趋势报告
utf report / generate report	generate_report	生成 HTML、JUnit 和 JSON 格式的契约合规报告
import junit xml <path>	import_test_results	从现有的 pytest/Maven 运行中注册结果
coverage gaps	analyze_coverage	识别未覆盖的符号和缺失的测试路径
traceability matrix	build_traceability_matrix	需求到测试的覆盖映射
suggest test types	suggest_test_types	根据源代码或需求推荐测试类型
query registry	query_registry	列出当前项目中已注册的测试
run tests	run_tests	执行测试文件并在注册表中记录结果
run mutation tests	run_mutation_tests	提供变异测试分数，并细分被杀死和存活的变异
utf health	health	服务运行时间、版本和工具数量

注册表持久化

UTF SQLite 注册表会在所有会话中按项目持久保存：

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_tests）后，测试会注册到 .utf/utf.db 中。后续调用 utf report、utf status 和 query registry 时会从这个持久化存储中读取——不同会话之间无需重新生成。

提供项目上下文

当 MCP 服务无法自动推断项目根目录时，请显式传入 project_dir：

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

或者在 mcp.json 中配置 "cwd": "${workspaceFolder}"（快速入门中已设置），这样服务就会始终从正确的工作区启动。

---

VS Code Copilot Chat 集成

运行 .\scripts\install-vscode-mcp.ps1（选项 2）或添加 uvx MCP 配置项（选项 1）后：

注意： 只有安装了 UTF VS Code Chat Participant 扩展（选项 2 中包含）时，@utf 前缀和 /斜杠命令 语法才可用。在 GitHub Copilot CLI 和未安装该扩展的标准 VS Code Copilot Chat 中，请使用自然语言——MCP 工具会自动调用。请参阅上文的 GitHub Copilot CLI 用法。

VS Code 聊天参与者斜杠命令（需要扩展）

命令	效果
@utf /generate-tests unit	为选定的代码或当前活动代码生成单元测试
@utf /generate-tests api	生成 API 测试
@utf /generate-tests integration	生成集成测试
@utf /generate-tests e2e	生成端到端测试
@utf /generate-tests security	生成安全／身份验证测试
@utf /generate-tests performance	生成性能／负载测试
@utf /validate-contract	根据 8 个部分的契约验证测试
@utf /coverage-gaps	识别当前测试套件中的覆盖缺口
@utf /traceability	构建需求 → 测试可追溯性矩阵
@utf /report	生成 HTML 契约合规报告
@utf /status	查看服务健康状况和安装状态

自然语言（无需扩展）

在标准 VS Code Copilot Chat 或 GitHub Copilot CLI 中，直接提问：

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

UTF 会读取打开的文件、检测语言和框架、根据函数签名推断需求，并生成正常路径、负向和边界情况测试——所有测试均根据 8 个部分的契约进行验证。

---

Python SDK

无需 MCP 服务，即可在脚本或 CI 管道中直接使用 UTF：

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']}")

---

CI/CD 集成

GitHub Actions

# .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

---

按项目配置

在项目根目录创建 .utf/rules/project-overrides.yaml：

# 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 的全局默认值之上。8 个部分的契约结构本身无法覆盖。

---

架构

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)

传输模式：

• stdio — 默认模式，由 VS Code MCP 客户端和 uvx 使用
• HTTP/SSE — 用于远程／团队部署（--transport http --port 8765）

SQLite 注册表会解析为相对于调用方项目根目录的 .utf/utf.db（即 mcp.json 中的 cwd，或传递给任意工具的 project_dir 参数）。每个项目都有独立的注册表，不共享状态。除非明确清除，否则注册表会在所有会话中持续保留。

---

安装选项摘要

方法	命令	cwd / 注册表隔离	要求
uvx（无需克隆）	uvx --from universal-test-framework utf-server	mcp.json 中的 ${workspaceFolder}	uv
本地克隆	.\scripts\install-vscode-mcp.ps1	自动写入 ${workspaceFolder}	Git、Python 3.11+
Docker	docker compose up -d	命名卷；按项目隔离时使用绑定挂载	Docker
GitHub MCP Registry	通过 MCP 客户端自动完成	UTF_PROJECT_DIR 环境变量	uv（自动安装）
pip + SDK	pip install universal-test-framework	每次调用都传入 project_dir	Python 3.11+

注册表隔离规则

所有设置都会按照相同的优先级链解析 SQLite 注册表路径：

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)

对所有设置，推荐采用以下方式：在 mcp.json 条目中同时设置 "cwd": "${workspaceFolder}" 和 "env": { "UTF_PROJECT_DIR": "${workspaceFolder}" }。 这样即使工具调用未提供 project_dir，也能确保注册表隔离正常工作。

安全性

• 所有 MCP 工具输入在处理前都通过 Pydantic 验证
• 不会记录或存储机密、凭据或个人身份信息（PII）
• 注册表（utf.db）位于每个项目本地，绝不会传输
• Docker 镜像以非 root 用户身份运行
• HTTP/SSE 传输会实施速率限制

---

许可证

MIT — 参见 LICENSE