universal-test-framework

Universal Test Framework（UTF）

LLM 生成コードの契約駆動型テスト適用とレポート — MCP、VS Code、Copilot CLI、Claude、Cursor、または Python SDK 経由。

UTF はMCP サーバー兼契約適用エンジンです。AI コーディングアシスタントに取って代わるものではありません。AI が作成するすべてのテストに必須の品質ゲート、構造化された監査証跡、包括的なコンプライアンスレポートを提供します。

---

UTF が選ばれる理由（またテストジェネレーター？）

AI ツール — GitHub Copilot、Claude、Cursor、Gemini — はテストをすばやく生成します。問題は、速さ ≠ 信頼性です。

UTF なし	UTF あり
テストは存在するが、その理由は誰にもわからない	すべてのテストが要件にリンクされる
「すべてをカバー」— その証明は誰にもできない	トレーサビリティマトリクスが REQ → テストを対応付ける
CI は成功するが、実際の動作は未テスト	ギャップ分析でカバーされていない箇所を検出
LLM が True をアサートするテストを作成	意味性チェックが自明なアサーションを拒否
何をテストしたかの履歴がない	永続レジストリがセッション再起動後も保持される
レポートに合格／不合格の件数のみ表示	HTML レポートにテストごとの 8 セクション詳細カードを表示

UTF と Markdown 指示／プロンプトファイルの比較

AI のガイドに Markdown ファイル（AGENTS.md、copilot-instructions.md、.cursorrules）をすでに使っている場合もあるでしょう。UTF は競合するのではなく、相互補完します。

Markdown 指示	UTF
テストの書き方を説明	生成されたすべてのテストに契約を適用
指示に従うかどうかを LLM に委ねる	生成時に契約を満たさないテストをブロック
生成後の検証がない	測定可能な 8 つの基準に照らして各テストを 0～1 で評価
セッション間で状態が保持されない	SQLite レジストリがすべてのテストと結果を保持
コンプライアンスレポートがない	テストごとの 8 セクション詳細カードを含む HTML レポート

Markdown 指示を使って AI の思考の方向性を整えます。UTF を使って、生成されたものを検証し、レポートします。

---

主な機能

• 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} の両方を受け付けます
• 5 種類のインストール方法 — uvx（クローン不要）、ローカルクローン、Docker、GitHub MCP Registry、pip SDK
• VS Code @utf — スラッシュコマンドに対応したチャット参加者
• CI/CD 対応 — GitHub Actions、GitLab CI、pre-commit フック
• プロジェクトごとのオーバーライド — .utf/rules/ の YAML ルールでグローバルのデフォルトを上書き

---

クイックスタート

セットアップ方法の比較

#	方法	起動方法	レジストリの場所	@utf スラッシュコマンド	最適な用途
1	uvx（インストール不要）	mcp.json + uvx	<workspace>/.utf/utf.db	❌ 自然言語を使用	uv を使用するすべての開発者
2	ローカルクローン	install-vscode-mcp.ps1	<workspace>/.utf/utf.db	✅ 拡張機能を使用	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 が必要です。クローンも仮想環境も不要です。

%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 を開いて、バックエンド用の E2E テストを生成して のように自然な言葉で依頼します。

インストールスクリプトにより、次のエントリが 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

公開されると、UTF は MCP マーケットプレイスで検索できるようになります。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	任意のテスト実行から UTF レジストリに JUnit XML をインポートします
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- のいずれかの参照を 1 つ以上含む	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	自己評価：meaningful／redundant／hallucinated（50 文字以上）	5%

合格最低スコア：0.85。 個々のセクションが存在していても、このしきい値を下回るテストはブロックされます。gaps に「none」と記載したり、「関数をテストするため」のような曖昧な根拠を記載したりすると、却下されます。

---

サポート対象マトリクス

言語	フレームワーク	テストの種類
Python	pytest	unit, integration, api, e2e, security, performance
TypeScript	Jest, Vitest, Playwright	unit, integration, e2e, api
JavaScript	Jest, Vitest	unit, integration
Java	JUnit 5 + AssertJ, Maven	unit, integration, api
Go	go-test + testify	unit, integration, api
C++	Google Test	unit

---

UTF の 3 フェーズ E2E ワークフロー

これは、あらゆる AI CLI（Copilot、Claude、Cursor）または VS Code で UTF を使用する際の標準フローです。フェーズの順序に従ってください。フェーズ 1 の登録を省略すると、レポートに Per-Test Contract Detail カードが表示されません。

┌─────────────────────────────────────────────────────────────────────────┐
│  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 レジストリには 2 種類のレコードがあります。status=generated レコード（register_contracts によって作成）は、 HTML レポートの Per-Test Contract Detail カードに使われます。status=executed/failed レコード （import_test_results によって作成）は、Execution Results テーブルに使われます。テストを両方のセクションに表示するには、 どちらのレコードも存在している必要があります。登録前に pytest を実行すると、実行結果の行は表示されますが、 8 セクションの詳細カードは表示されません。

メソッドごとの 8 セクションコメントブロック（必須）

すべてのテストメソッドには、インラインコメントブロックを個別に記述する必要があります。クラスの docstring ではありません。

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 CLI からの 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]"

Claude の MCP 設定（~/.config/claude/mcp.json または同等のファイル）に UTF を追加するには、次のようにします。

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

Cursor

Cursor では、.cursor/mcp.json（プロジェクトレベル）または ~/.cursor/mcp.json（グローバル）に、MCP サーバーとして UTF を追加します。

{
  "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 の使用方法

UTF は GitHub Copilot CLI で自然言語を使って呼び出します。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	ハッピーパス、ネガティブケース、エッジケースを含む E2E テストスイートを生成します
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 プレフィックスと /slash-command 構文は、UTF VS Code Chat Participant 拡張機能がインストールされている場合にのみ使用できます（オプション 2 に含まれています）。GitHub Copilot CLI および拡張機能なしの標準の VS Code Copilot Chat では、自然言語を使用してください。MCP ツールは自動的に呼び出されます。上記のGitHub Copilot CLI の使用方法を参照してください。

VS Code Chat Participant のスラッシュコマンド（拡張機能が必要）

コマンド	効果
@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 レジストリは、呼び出し元のプロジェクトルート（mcp.json 内の cwd、または各ツールに渡される project_dir パラメーター）を基準とした .utf/utf.db に解決されます。各プロジェクトにはそれぞれ独立したレジストリがあり、状態は共有されません。レジストリは、明示的に消去されるまで、すべてのセッションを通じて保持されます。

---

インストール方法の概要

方法	コマンド	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 を参照