test-intelligence-mcp/
  src/test_intelligence/
    server.py       # FastMCP server + tool registration
    config.py        # typed settings, loaded from .env
    safety.py         # repo-path allowlist gate (see Safety below)
    paths.py            # cross-platform file-path normalization
    runners/               # pytest/coverage execution, JUnit + coverage.json parsing
    flaky/                   # multi-run comparison logic, order/seed control
    ml/                        # features.py, synthetic.py, training.py, prediction.py, model_store.py
    db/                        # SQLAlchemy models, session, query helpers
    git/                        # commit/branch metadata (repo_info.py), diff stats (diff.py)
  tests/                       # tests for THIS project's own code
    fixtures/                  # tiny throwaway repos the runner tests execute for real
  scripts/
    ci_report.py         # flaky-check + coverage summary, invoked by CI (see below)
  alembic/             # migration scripts
  .github/workflows/
    ci.yml              # runs on every PR — see Continuous Integration below
  docker-compose.yml  # local Postgres
  pyproject.toml
  .env.example

uv sync

docker-compose up -d

docker-compose ps

cp .env.example .env

uv run alembic upgrade head

claude mcp add test-intelligence -- uv run --directory "C:\path\to\test-intelligence-mcp" test-intelligence-mcp

{
  "mcpServers": {
    "test-intelligence": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\test-intelligence-mcp", "run", "test-intelligence-mcp"]
    }
  }
}

{
  "status": "ok",
  "tests_passed": true,
  "overall_coverage_percent": 87.5,
  "total_statements": 120,
  "total_covered_lines": 105,
  "total_uncovered_lines": 15,
  "files": [
    {
      "file": "pkg/calculator.py",
      "coverage_percent": 80.0,
      "num_statements": 10,
      "covered_lines": 8,
      "uncovered_line_count": 2,
      "uncovered_lines": [12, 13]
    }
  ]
}

{
  "status": "ok",
  "run_id": 3,
  "repo_id": 1,
  "commit_sha": "a1b2c3d...",
  "branch": "main",
  "duration_seconds": 0.52,
  "total_tests": 3,
  "passed_count": 1,
  "failed_count": 1,
  "skipped_count": 1
}

{
  "status": "ok",
  "count": 2,
  "history": [
    {
      "repo_name": "C:\\path\\to\\some-repo",
      "run_id": 3,
      "commit_sha": "a1b2c3d...",
      "branch": "main",
      "started_at": "2026-08-16T00:20:11+00:00",
      "node_id": "tests/test_calculator.py::test_divide",
      "file_path": "tests/test_calculator.py",
      "outcome": "passed",
      "duration_seconds": 0.001,
      "error_message": null
    }
  ]
}

{
  "status": "ok",
  "repo_id": 2,
  "runs_requested": 5,
  "runs_completed": 5,
  "total_tests_observed": 2,
  "flaky_test_count": 1,
  "flaky_tests": [
    {
      "node_id": "tests/test_flaky.py::test_alternates",
      "runs_observed": 5,
      "inconsistency_count": 2,
      "flakiness_rate": 0.4,
      "outcomes": ["passed", "failed", "passed", "failed", "passed"],
      "majority_outcome": "passed"
    }
  ],
  "run_failures": []
}

{
  "status": "ok",
  "model_path": "models/risk_model.joblib",
  "real_sample_count": 0,
  "synthetic_sample_count": 500,
  "total_sample_count": 500,
  "test_set_size": 125,
  "metrics": {
    "accuracy": 0.6,
    "precision": 0.5962,
    "recall": 0.5167,
    "f1": 0.5536
  },
  "caveat": "Only 0 real training example(s) recorded so far (via record_test_run) — this training run is dominated by synthetic, artificially-generated bootstrap data. These metrics describe how well the model fits that synthetic relationship, NOT real predictive power on an actual repository. Keep calling record_test_run on real repos, then retrain, before trusting these numbers for anything beyond confirming the training pipeline itself works."
}

{
  "status": "ok",
  "repo_id": 3,
  "base_ref": "0bcbeba860df0457c55ad3c1d3826ed5fd941506",
  "commit_sha": "8306f4598275f92907de89e1161f982772f3aac7",
  "model_trained_at": "2026-08-17T19:03:42.707577+00:00",
  "model_real_sample_count": 0,
  "predictions": [
    { "file": "tests/test_calculator.py", "predicted_risk_probability": 0.0743, "lines_added": 9, "lines_deleted": 1 },
    { "file": "pkg/calculator.py", "predicted_risk_probability": 0.0457, "lines_added": 7, "lines_deleted": 0 }
  ]
}
```</s>

`model_real_sample_count` はモデルのトレーニングメタデータから引き継がれます。これにより、呼び出し元は別途ルックアップすることなく、これらの予測が合成データ主体のモデル（[コールドスタート戦略](#cold-start-strategy-for-the-ml-model)を参照）に基づくものかを一目で確認できます。`train_risk_model` が少なくとも1回実行されている必要があります（そうでない場合は `no_trained_model` エラー）。このツールは暗黙的にモデルをトレーニングすることはありません。すべての予測は `risk_predictions` テーブルに保存され、`actual_outcome` は `NULL` のままとなります。これにより、実際のリポジトリの予測を後で実際の結果と照合できます。この評価機能はまだ構築されていませんが、初日からデータを取得しておくことで、スキーマ変更なしで後から追加できるようになっています。</s>

## 継続的インテグレーション (GitHub Actions)</s>

GitHub Actions は GitHub に組み込まれた CI です。**ワークフロー**（1つのYAMLファイル、[.github/workflows/ci.yml](.github/workflows/ci.yml)）が、リポジトリイベント（ここでは、プルリクエストの作成/更新、または `main` ブランチへのプッシュ）に応じて自動的に実行される **ジョブ** を記述します。各ジョブは、新しく使い捨ての仮想マシン（「ランナー」）上で実行されます。明示的にキャッシュまたはアップロードされたものを除き、実行間で永続化されるものはありません。ジョブは **ステップ** のシーケンスであり、各ステップはシェルコマンドまたは再利用可能な **アクション**（他の誰かが公開したパッケージ化されたステップで、`actions/checkout@v4` のように参照されます）のいずれかです。</s>

このプロジェクトのワークフローは、プロジェクト自身をエンドツーエンドでテストします。</s>

1. **リポジトリをチェックアウト** し、**`uv` + 依存関係をインストール** します。これはコントリビューターがローカルでインストールするものと同じツールです。</s>
2. **Postgres をサービスコンテナとして起動** します。GitHub Actions がジョブと一緒に実行する2つ目のコンテナで、すべてのステップから `localhost:5433` でアクセス可能です。これはローカルでの `docker-compose up -d` とまったく同じですが、Docker Desktop ではなく GitHub によって管理されます。ジョブのステップは、ヘルスチェックが成功するまで開始されません。手書きの「Postgres を待つ」ポーリングループは不要です。</s>
3. **Alembic マイグレーションを適用** し、**`--cov-fail-under=$COVERAGE_THRESHOLD` を付けてプロジェクト自身のテストスイートを実行** します。pytest-cov の組み込みゲートです。カバレッジがしきい値を下回ると（現在は80%、実際の約93%未満に余裕を持たせて設定）、ビルドは即座に失敗します。</s>
4. **`detect_flaky_tests` をプロジェクト自身のテストに対して実行** します。[scripts/ci\_report.py](scripts/ci_report.py) 経由で実行されます。このスクリプトは、ショートカットではなく、*実際の* MCP レイヤー（`fastmcp.Client` が実際のサーバーオブジェクトと通信）を介してツールを呼び出します。これは情報提供のみであり、ビルドを失敗させることはありません。失敗させるのはカバレッジのみです。</s>
5. **両方のレポートをワークフローアーティファクトとしてアップロード** します（`actions/upload-artifact`）。デフォルトで90日間、ワークフロー実行ページからダウンロード可能です。</s>
6. **ジョブサマリーを書き込み**（`$GITHUB_STEP_SUMMARY`、実行ページにMarkdownとして直接レンダリングされます）、**それを PR コメントとして投稿** します（`actions/github-script`、実行に組み込まれた `GITHUB_TOKEN` を使用。追加のシークレットは不要）。ステップサマリーは常に動作するフォールバックであり、フォークからのPR（コメントを投稿できない読み取り専用トークンが付与される。これはGitHubのセキュリティ制限であり、このワークフローのバグではありません）を含む場合でも機能します。コメントステップは `continue-on-error: true` でラップされているため、この制限はジョブ全体を失敗させるのではなく、グレースフルに低下します。</s>

**これを実際に実行するには**、プロジェクトが実際のGitHubリポジトリに存在し、コミットがプッシュされている必要があります。このローカルビルドプロセスではまだ作成されていません。それが存在すれば、PRを開くだけで、Actionsタブ（およびPR自体、コメントが投稿された後）にライブで実行されている様子が表示されます。</s>

## ビルドステータス</s>

このプロジェクトはマイルストーンごとに構築され、それぞれが次の段階に進む前に動作が確認されています。</s>

* [x] **マイルストーン 1** — プロジェクトスケルトン、docker-compose Postgres、`.env.example`、この README</s>
* [x] **マイルストーン 2** — データベース層 (SQLAlchemy モデル + Alembic)</s>
* [x] **マイルストーン 3** — FastMCP サーバースケルトン (6つのツール登録、プレースホルダーの本体)</s>
* [x] **マイルストーン 4** — `analyze_coverage`</s>
* [x] **マイルストーン 5** — `record_test_run` + `get_test_history`</s>
* [x] **マイルストーン 6** — `detect_flaky_tests`</s>
* [x] **マイルストーン 7** — ML コールドスタート戦略、特徴量抽出、`train_risk_model`</s>
* [x] **マイルストーン 8** — `predict_pr_risk`</s>
* [x] **マイルストーン 9** — GitHub Actions CI (構築 + ローカル検証済み。ライブPR実行は実際のGitHubリポジトリを待つ)</s>
* [ ] **マイルストーン 10** — 最終仕上げ</s>

## このプロジェクト自身のテストの実行</s>

```bash
uv sync --extra dev     # installs pytest-asyncio + ruff on top of the base deps
uv run pytest -v
uv run pytest --cov --cov-report=term-missing   # with coverage
uv run ruff check .                              # lint
```</s>

DB層のテストは、実際の使い捨てのPostgresデータベース (`test_intelligence_test`、自動的に作成および破棄) を使用し、データベースをモックしたり `create_all()` を使用したりする代わりに、実際のAlembicマイグレーションをそれに対して実行します。これはCIがPostgresサービスコンテナ（マイルストーン9）を介して使用するのと同じアプローチです。詳細については `tests/conftest.py` を参照してください。</s>

## データモデル</s>

6つのテーブルがあり、Alembicマイグレーションによって管理されています。</s>

* **repositories** — 追跡対象のリポジトリ（名前 + ローカルパスまたはリモートURL）</s>
* **test\_runs** — `pytest` の呼び出しごとに1行（リポジトリ、コミットSHA、ブランチ、タイムスタンプ、期間、成功/失敗/スキップ数）</s>
* **test\_results** — 実行内のテストノードIDごとに1行（結果、期間、エラーメッセージ）</s>
* **file\_changes** — 実行のファイルごとの差分統計（追加/削除行数、変更後にテストが失敗したかどうか）</s>
* **flaky\_reports** — テストノードごとのフレーキネスサマリー（観測された実行回数、不一致数、検出タイムスタンプ）</s>
* **risk\_predictions** — コミットのファイルごとのMLリスクスコア。実際の結果が判明したらそれも保存されます（モデルのオフライン評価用）</s>

## ライセンス</s>

MIT