Collègue

Collègue MCP

🇫🇷 フランス語版 | 🇬🇧 英語版

MCP（Model Context Protocol）サーバーとして提供される、専門分野に特化した AI エキスパートのチームです。各ツールは、コード分析、リファクタリング、テスト、セキュリティ、アーキテクチャなどの分野に精通したエージェントです。自動委任システム、永続メモリ、プロアクティブなモニタリングを通じて、連携して動作します。

---

🚀 クイックスタート（Docker）

git clone https://github.com/VynoDePal/Collegue.git
cd Collegue
cp .env.example .env   # renseigner LLM_API_KEY (Gemini)
docker compose up -d

エンドポイント：

URL	役割
http://localhost:4121/mcp/	MCP サーバー（HTTP トランスポート）
http://localhost:4122/_health	ヘルスチェック

ネットワーク：デフォルトではループバックです。 docker compose up はすべてのポートを 127.0.0.1 に公開します （MCP 4121、ヘルス 4122、Keycloak 4123、ダッシュボード 4125、nginx 8088）。ネットワークからは接続できません。 サーバーはコンテナ内で 0.0.0.0 をリッスンしますが、ホスト側での公開先のみが制限されています。公開アドレスは、独立した 3 つの変数（.env 内）で変更できます：

変数	対象ポート
COLLEGUE_PUBLISH_HOST	MCP 4121、ヘルス 4122、nginx 8088
COLLEGUE_DASHBOARD_PUBLISH_HOST	Streamlit ダッシュボード 4125（認証なし）
COLLEGUE_KEYCLOAK_PUBLISH_HOST	Keycloak 4123（start-dev。そのまま外部に公開しないでください）

リモートへの公開（例：COLLEGUE_PUBLISH_HOST=0.0.0.0）は、明示的な選択であり、OAUTH_ENABLED=true の場合にのみ使用してください。 これは必須ではありません。OAuth なしの場合、サーバーは警告をログに記録するだけで、認証なしで接続可能な状態を維持します。MCP を公開しても、ダッシュボードや Keycloak が公開されることはありません。TLS 対応リバースプロキシの使用を推奨します。

OAuth はフェイルクローズです。 OAUTH_ENABLED=true の場合、認証を確立できなければ（JWTVerifier がない、コンストラクターでエラーが発生する、OAUTH_JWKS_URI と OAUTH_PUBLIC_KEY の両方がない、または OAUTH_ISSUER や OAUTH_ALGORITHM が空）、サーバーは起動を拒否し、コンテナはゼロ以外のコードで終了します（Compose は restart: always に従って再起動します。ログを確認してください）。認証なしのモードは、明示的に指定してログに記録される OAUTH_ENABLED=false（デフォルト）の場合にのみ利用できます。 OAUTH_ALGORITHM と OAUTH_REQUIRED_SCOPES はすべてのトークンに実際に適用されます。設定されたスコープを含まないトークンは拒否されます（更新前にトークンを確認してください）。 Docker を使用しない場合、HOST のデフォルト値は 127.0.0.1 になりました。

IDE の設定

Claude Code（CLI）

claude mcp add --transport http collegue http://localhost:4121/mcp/

Windsurf / Cursor / Antigravity

{
  "mcpServers": {
    "collegue": {
      "serverUrl": "http://localhost:4121/mcp/"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "collegue": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4121/mcp/"]
    }
  }
}

stdio モード（コンテナをオンデマンドで起動）

{
  "mcpServers": {
    "collegue": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "LLM_API_KEY=votre_clé_gemini",
        "collegue-mcp"
      ]
    }
  }
}

ローカルでビルドするイメージ：docker build -f docker/collegue/Dockerfile -t collegue-mcp .

---

✨ 10 の AI エキスパート

各エキスパートは LLM を使用し、エージェントループを通じて反復処理を行い、ほかのエキスパートに委任できます。

エキスパート	説明
コードレビュー	品質、命名、複雑さ、セキュリティ、DRY、SOLID
アーキテクチャ分析	パターン、依存関係、循環、結合度、技術的負債
パフォーマンス分析	O(n²)、ブロッキング I/O、ループ内の文字列連結、ホットスポット
コードリファクタリング	構造の変更、最適化、AST の検証、メトリクスの比較
テスト生成	実行可能なユニットテスト（pytest、jest、phpunit）
コードドキュメント	Docstring、技術ドキュメント、カバレッジ
IaC ガードレールスキャン	Terraform、Kubernetes、Dockerfile のセキュリティ
影響分析	変更前の予測的なリスク分析
リポジトリ整合性チェック	未使用のインポート、デッドコード、重複
スマートオーケストレーター	複数のエキスパートの計画と調整

追加ツール

カテゴリ	ツール
静的解析	Dependency Guard、Secret Scan、Run Tests
統合	PostgreSQL、GitHub、Sentry、Kubernetes

---

🤖 マルチエージェントシステム

┌─────────────────────────────────────────────────────┐
│                 Collègue MCP Server                   │
│                                                     │
│  Code Review ─── Architecture ─── Performance       │
│       │               │               │             │
│  Refactoring ─── Test Gen ─── Documentation         │
│       │               │               │             │
│  IaC Scan ─── Consistency ─── Impact Analysis       │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │ Délégation · Mémoire · Monitor · Dashboard   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

コンポーネント	役割
エージェントループ	実行 → 検証 → 修正 → 収束するまで再実行
委任	14 個の自動ルール（例：スコアが 0.5 未満の場合、code_review → refactoring）
メモリ	結果を .collegue/memory/ に保存し、今後のセッションで利用します
モニター	変更されたファイルを検出し、関連するエキスパートを起動します
ダッシュボード	プロジェクトの健全性スコアを集約します

---

🔑 設定

環境変数（.env）

テーマ別の概要（全項目とデフォルト値については .env.example を参照してください）：

変数	説明	必須
LLM_API_KEY	LLM プロバイダーの API キー（デフォルトは Gemini）	✓
LLM_PROVIDER / LLM_MODEL	デフォルトの LLM プロバイダーとモデル
LLM_MODEL_* / LLM_PROVIDER_*	役割別のモデル／プロバイダー（CODER、QA、PLANNER、REVIEWER）
LLM_RATE_LIMIT_*	クライアントごとの LLM 呼び出し制限（分単位／日単位）
CACHE_ENABLED / CACHE_TTL	ツール応答のキャッシュ
OAUTH_ENABLED（および OAUTH_*、Keycloak）	OAuth 認証（デフォルトは off。有効時はフェイルクローズ：上記の「ネットワーク」を参照）
COLLEGUE_PUBLISH_HOST / COLLEGUE_DASHBOARD_PUBLISH_HOST / COLLEGUE_KEYCLOAK_PUBLISH_HOST	Docker ポートの公開アドレス（デフォルトは 127.0.0.1）
GITHUB_TOKEN / GITHUB_OWNER / GITHUB_REPO	GitHub 統合（ウォッチドッグ、PR）
SENTRY_DSN / SENTRY_ENVIRONMENT	Sentry オブザーバビリティ
STATE_DATABASE_URL	自律エンジンの永続状態（Postgres/SQLite）
MAX_COST_USD / MAX_TOKENS_BUDGET / COLLEGUE_RUN_DEADLINE_SECONDS	永続予算レジストリによって適用される実行上限（計画、BUILD、IMPROVE、再試行）。上限到達時に一時停止します
BUDGET_MODE	strict（デフォルト：フレームワークが発行する各呼び出しの前に予約し、使用量が不明な場合は永続的にブロック）または advisory（ブロックせずに記録し、保証なし）。保証の対象はフレームワークが発行する呼び出しであり、キーを持つワークスペースのプログラムは対象外です。w2-budget を参照してください（受け入れおよび拒否されるトランスポート）
COLLEGUE_HOME	永続化のルート（メトリクス、チェックポイント、編集可能なプロンプト。以前のインストールにある旧プロンプト状態は初回起動時に引き継がれます。w2-installation を参照してください）
CODER_SUBSCRIPTION（および CODER_SUBSCRIPTION_MODEL、SANDBOX_SUBSCRIPTION_AUTH_DIR）	API キーの代わりに、ChatGPT/Codex サブスクリプションを利用したコーディング（API コスト $0）
BUILD_AUTO_MERGE	ビルドフェーズのマージボット（タスク PR の自動マージ。デフォルトは off。明示的な有効化が必要です）。永続的なデリバリーの証拠があり、必須チェックに合格し、ベースが変更されておらず、厳格な保護が実際に適用可能な場合にのみマージします（w3-merge）。Phase 5 とは別機能です	false
GATE_ACCEPTANCE_TESTS	QA 役割が計画時に生成し、計画とともに封印した後、LLM を使わずに再実行する pytest オラクル（デフォルトは off）
SANDBOX_NETWORK / SANDBOX_MEMORY / SANDBOX_CPUS / SANDBOX_TIMEOUT	コーダーコンテナーのネットワークとリソース
AUTO_MERGE_ENABLED / AUTO_REVERT_ENABLED / PILOT_TOOL_ENABLED	リスクゲート付きの自律機能（オプトイン、デフォルトは off）

自律エンジンの詳細設定（予算、自動マージ／リバート、パイロットの MCP ツール）： docs/moteur_autonome.md。

---

🧭 自律開発エンジン

リアクティブなエキスパートにとどまらず、Collègue は開発をエンドツーエンドで進められます。予算内で GitHub を基盤として、計画 → コーディング → テスト → PR の作成を行います。階層：planner → pilote → executor → improve。永続状態基盤（Postgres/SQLite）と Docker サンドボックス上で動作します。

デフォルトで安全：--execute を指定しない限り、実行は dry_run（書き込みなし）のままです。plan draft では永続的な下書きのみが保存されます。その後、オペレーターが表示されたハッシュを承認し、GitHub に変更を加えるのは plan sync --execute のみです。strict モードでは予算を永続的に管理し、上限に達した場合や使用量が不明な場合は一時停止します。上限を定められないトランスポートは、上限を管理できるかのように扱わず、拒否します。実際の BUILD では、検証済みの納品証跡に基づき、マージボット（オプトイン：BUILD_AUTO_MERGE、デフォルトでは無効）が各タスクを自動マージして MVP を構築できます。改善フェーズでは、デフォルトで PR を人間によるマージのためにオープンのままにします（§6）。リスクゲート付きの Phase 5 自動マージは実際に接続されていますが、オプトインのままです。完全な CI、安定した SHA、再同期、main の健全性確認が必須です。健全性が低下し、AUTO_REVERT_ENABLED が有効な場合は、以前のツリーを完全に復元するコミットが公開され、CI で検証され、SHA ガードのもとでマージされた後、最後に再確認されます。マージ前に書き込まれる永続トランザクションにより、クラッシュ後もマージやリバートを重複させずに再開できます。ロールバックではワーカー間で CAS リースを使用し、人間が確認する（phase5 show/ack）まで recovered 状態を維持するため、同じ変更が繰り返し提案されることはありません。これらの機能はすべてデフォルトで無効であり、フェイルクローズです。 コーダーは ChatGPT/Codex のサブスクリプションで実行でき、API コストは $0 です。

# Phase 1 : trois gestes séparés — le processus LLM ne s'auto-approuve jamais
python -m collegue.pilot plan draft --name app --problem "..." --owner org --repo app --base main
python -m collegue.pilot plan approve --project-id 1 --expected-plan-hash SHA256_AFFICHE
python -m collegue.pilot plan sync --project-id 1 --execute

# Build : aperçu (dry_run) puis exécution réelle
python -m collegue.pilot --project-id 1 --repo-source /chemin/clone --owner org --repo app
python -m collegue.pilot ... --execute            # écritures réelles (PR + état)
python -m collegue.pilot ... --execute --improve  # + cycle d'amélioration

--improve は、MVP が実際にマージされ、origin/<base> に再同期された後に、継続的改善ループ（Phase 4）を開始します。決定論的な品質目標（LLM の意見を用いず、カバレッジ・セキュリティ・lint・複雑度を評価）に基づき、差分が回帰なしで改善する場合に限りPR を作成します（フェイルクローズのゲート）。PR はスタックされ、改善が頭打ちになると停止します。最後の BUILD PR が未マージの場合や git の再同期に失敗した場合は、誤って completed とするのではなく、Phase 4 をブロックします。

アーキテクチャ、改善ループ、保護策、可観測性／監査、クラッシュ後の再開、設定については、docs/moteur_autonome.md をご覧ください。

---

🤖 Watchdog エージェント（セルフヒーリング）

Sentry を監視し、エラーを修正するための GitHub PR を自動生成します。

Sentry (erreurs) → Watchdog (analyse) → LLM (fix) → GitHub (PR)

デプロイについては、docs/watchdog_deployment.md をご覧ください。

---

📚 ドキュメント

ドキュメント	説明
ユーザーガイド	インストール、設定、初期手順、ベストプラクティス
統合ガイド	Claude Desktop、Cursor、Windsurf、CI/CD との統合
エキスパートリファレンス	各エキスパートのパラメーター、出力、使用例
マルチエージェントシステム	技術アーキテクチャ、委任、メモリー
自律開発エンジン	自律パイロット：アーキテクチャ、継続的改善（Phase 4）、保護策、監査、再開、設定
LLM 評価	LLM 出力品質のベンチマーク
レート制限	クォータと制限

---

🛠️ 開発

python -m venv .venv && source .venv/bin/activate
pip install --require-hashes --no-deps -r locks/dev.txt   # dépendances verrouillées et hachées (outils de test inclus)
python -m collegue.migrations upgrade                      # schéma de l'état durable (STATE_DATABASE_URL)
python -m collegue.app

依存関係の唯一の情報源は pyproject.toml です。locks/*.txt ファイルはそこから生成されます（python scripts/locks.py。w2-installation を参照）。パッケージにはリソース（スキル、プロンプトのシード、マイグレーション）が同梱されており、リポジトリ外でも wheel からインストールして実行できます。

テスト：

python -m pytest --tb=short -q
ruff check collegue tests