Collegue

Collègue MCP

🇫🇷 Version française | 🇬🇧 English version

Un collectif d'experts IA spécialisés sous forme de serveur MCP (Model Context Protocol). Chaque outil est un agent expert dans son domaine — analyse de code, refactoring, tests, sécurité, architecture — et ils travaillent ensemble via un système de délégation automatique, mémoire persistante et monitoring proactif.

---

🚀 Démarrage Rapide (Docker)

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

Endpoints :

URL	Rôle
http://localhost:4121/mcp/	Serveur MCP (transport HTTP)
http://localhost:4122/_health	Healthcheck

Réseau : loopback par défaut. docker compose up publie tous les ports sur 127.0.0.1 (MCP 4121, health 4122, Keycloak 4123, dashboard 4125, nginx 8088) : rien n'est joignable depuis le réseau. Le serveur écoute sur 0.0.0.0 à l'intérieur du conteneur ; seule la publication côté hôte est restreinte. Trois variables indépendantes (dans .env) changent l'adresse de publication :

Variable	Ports concernés
COLLEGUE_PUBLISH_HOST	MCP 4121, health 4122, nginx 8088
COLLEGUE_DASHBOARD_PUBLISH_HOST	dashboard Streamlit 4125 (aucune authentification)
COLLEGUE_KEYCLOAK_PUBLISH_HOST	Keycloak 4123 (start-dev, à ne pas exposer tel quel)

Exposition distante (par ex. COLLEGUE_PUBLISH_HOST=0.0.0.0) : choix explicite, à n'utiliser qu'avec OAUTH_ENABLED=true. Ce n'est pas imposé : sans OAuth, le serveur journalise seulement un avertissement et reste joignable sans authentification. Exposer le MCP n'ouvre ni le dashboard ni Keycloak. Un reverse proxy TLS reste recommandé.

OAuth fail-closed. Avec OAUTH_ENABLED=true, si l'authentification ne peut pas être établie (JWTVerifier absent, constructeur en erreur, ni OAUTH_JWKS_URI ni OAUTH_PUBLIC_KEY, OAUTH_ISSUER ou OAUTH_ALGORITHM vides), le serveur refuse de démarrer et le conteneur sort en code non nul (Compose le relance selon restart: always : lire ses logs). Le mode sans authentification n'existe que via OAUTH_ENABLED=false (défaut), explicite et journalisé. OAUTH_ALGORITHM et OAUTH_REQUIRED_SCOPES sont effectivement appliqués à chaque jeton : un jeton sans les scopes configurés est refusé (vérifier vos jetons avant de mettre à jour). Hors Docker, HOST vaut désormais 127.0.0.1 par défaut.

Configurer votre 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/"]
    }
  }
}

Mode stdio (container à la volée)

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

Image à construire localement : docker build -f docker/collegue/Dockerfile -t collegue-mcp .

---

✨ Les 10 Experts IA

Chaque expert utilise un LLM, itère via une boucle agentique, et peut déléguer à d'autres experts.

Expert	Description
Code Review	Qualité, naming, complexité, sécurité, DRY, SOLID
Architecture Analysis	Patterns, dépendances, cycles, couplage, dette technique
Performance Analysis	O(n²), I/O bloquant, concat en boucle, hotspots
Code Refactoring	Restructure, optimise, valide AST, compare métriques
Test Generation	Tests unitaires exécutables (pytest, jest, phpunit)
Code Documentation	Docstrings, documentation technique, couverture
IaC Guardrails Scan	Sécurité Terraform, Kubernetes, Dockerfile
Impact Analysis	Analyse prédictive de risques avant changement
Repo Consistency Check	Imports inutilisés, code mort, duplication
Smart Orchestrator	Planifie et coordonne plusieurs experts

Outils supplémentaires

Catégorie	Outils
Statiques	Dependency Guard, Secret Scan, Run Tests
Intégrations	PostgreSQL, GitHub, Sentry, Kubernetes

---

🤖 Système Multi-Agents

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

Composant	Rôle
Boucle Agentique	Exécute → valide → corrige → re-exécute jusqu'à convergence
Délégation	14 règles automatiques (ex: code_review → refactoring si score < 0.5)
Mémoire	Stocke les résultats dans .collegue/memory/ pour les sessions futures
Moniteur	Détecte les fichiers modifiés et déclenche les experts pertinents
Dashboard	Agrège les scores de santé du projet

---

🔑 Configuration

Variables d'environnement (.env)

Aperçu par thème (liste exhaustive et valeurs par défaut dans .env.example) :

Variable(s)	Description	Requis
LLM_API_KEY	Clé API du provider LLM (Gemini par défaut)	✓
LLM_PROVIDER / LLM_MODEL	Provider et modèle LLM par défaut
LLM_MODEL_* / LLM_PROVIDER_*	Modèle/provider par rôle (CODER, QA, PLANNER, REVIEWER)
LLM_RATE_LIMIT_*	Limites d'appels LLM par client (minute / jour)
CACHE_ENABLED / CACHE_TTL	Cache des réponses d'outils
OAUTH_ENABLED (+ OAUTH_*, Keycloak)	Authentification OAuth (off par défaut ; fail-closed si activée : voir « Réseau » plus haut)
COLLEGUE_PUBLISH_HOST / COLLEGUE_DASHBOARD_PUBLISH_HOST / COLLEGUE_KEYCLOAK_PUBLISH_HOST	Adresse de publication des ports Docker (127.0.0.1 par défaut)
GITHUB_TOKEN / GITHUB_OWNER / GITHUB_REPO	Intégration GitHub (watchdog, PR)
SENTRY_DSN / SENTRY_ENVIRONMENT	Observabilité Sentry
STATE_DATABASE_URL	État durable du moteur autonome (Postgres/SQLite)
MAX_COST_USD / MAX_TOKENS_BUDGET / COLLEGUE_RUN_DEADLINE_SECONDS	Plafonds du run, appliqués par le registre de budget durable (planification, BUILD, IMPROVE, reprises) ; pause à l'atteinte
BUDGET_MODE	strict (défaut : réservation avant chaque appel émis par le framework, usage inconnu = blocage durable) ou advisory (enregistre sans bloquer, aucune garantie). La garantie porte sur les appels que le framework émet, pas sur un programme du workspace qui disposerait d'une clé : voir w2-budget (transports acceptés et refusés)
COLLEGUE_HOME	Racine de persistance (métriques, checkpoints, prompts modifiables ; l'ancien état de prompts d'une installation précédente est repris au premier démarrage, voir w2-installation)
CODER_SUBSCRIPTION (+ CODER_SUBSCRIPTION_MODEL, SANDBOX_SUBSCRIPTION_AUTH_DIR)	Codage par abonnement ChatGPT/Codex (coût API $0) au lieu d'une clé
BUILD_AUTO_MERGE	Merge-bot de la phase build (auto-merge des PR de tâches ; off par défaut, activation explicite). Ne fusionne que sur preuve de livraison durable, checks requis réussis, base inchangée et protection stricte réellement applicable (w3-merge). Distinct de Phase 5	false
GATE_ACCEPTANCE_TESTS	Oracles pytest générés au plan-time par le rôle QA, scellés avec le plan puis rejoués sans LLM (off par défaut)
SANDBOX_NETWORK / SANDBOX_MEMORY / SANDBOX_CPUS / SANDBOX_TIMEOUT	Réseau et ressources du conteneur coder
AUTO_MERGE_ENABLED / AUTO_REVERT_ENABLED / PILOT_TOOL_ENABLED	Capacités autonomes risk-gated (opt-in, off par défaut)

Réglages détaillés du moteur autonome (budget, auto-merge/revert, outil MCP du pilote) : docs/moteur_autonome.md.

---

🧭 Moteur de développement autonome

Au-delà des experts réactifs, Collègue peut piloter un développement de bout en bout : planifier → coder → tester → ouvrir des PR, sous budget, avec GitHub comme substrat. Étages : planner → pilote → executor → improve, sur un socle d'état durable (Postgres/SQLite) et de sandbox Docker.

Sûr par défaut : un run reste en dry_run (aucune écriture) tant qu'on ne passe pas --execute ; plan draft persiste seulement son brouillon durable ; l'opérateur approuve ensuite le hash affiché, et seul plan sync --execute touche GitHub ; budget durable en mode strict (pause à l'atteinte d'un plafond ou d'un usage inconnu ; les transports non bornables sont refusés plutôt que prétendus). En BUILD réel, un merge-bot (opt-in : BUILD_AUTO_MERGE, off par défaut) peut auto-merger chaque tâche pour construire le MVP, sur preuve de livraison validée ; la phase amélioration laisse ses PR ouvertes pour merge humain (§6) par défaut. L'auto-merge risk-gated Phase 5 est réellement câblé mais reste opt-in : CI complète, SHA stable, resync et santé de main sont obligatoires. Si cette santé régresse et que AUTO_REVERT_ENABLED est actif, un commit qui restaure exactement l'arbre précédent est publié, validé par CI, fusionné sous gardes SHA puis contrôlé une dernière fois. Une transaction durable écrite avant le merge permet de reprendre après un crash sans dupliquer le merge ou le revert. Le rollback utilise un lease CAS entre workers et reste en état recovered jusqu'à acquittement humain (phase5 show/ack), ce qui empêche de reproposer en boucle le même changement. L'ensemble reste désactivé par défaut et fail-closed. Le codeur peut tourner via abonnement ChatGPT/Codex (coût 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 enchaîne, une fois le MVP réellement mergé puis resynchronisé sur origin/<base>, la boucle d'amélioration continue (Phase 4) : un objectif de qualité déterministe (couverture − sécu − lint − complexité, sans avis de LLM) ouvre des PR seulement quand le diff progresse sans régression (gate fail-closed) ; les PR sont stackées et s'arrêtent au plateau. Une dernière PR BUILD non mergée ou un resync git en échec bloque Phase 4 au lieu de produire un faux succès completed.

Architecture, boucle d'amélioration, garde-fous, observabilité/audit, reprise après crash et réglages : docs/moteur_autonome.md.

---

🤖 Agent Watchdog (Self-Healing)

Surveille Sentry et génère des PRs GitHub automatiques pour corriger les erreurs.

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

Voir docs/watchdog_deployment.md pour le déploiement.

---

📚 Documentation

Document	Description
Guide Utilisateur	Installation, configuration, premiers pas, bonnes pratiques
Guide d'Intégration	Intégration Claude Desktop, Cursor, Windsurf, CI/CD
Référence des Experts	Paramètres, sorties et cas d'usage de chaque expert
Système Multi-Agents	Architecture technique, délégation, mémoire
Moteur de développement autonome	Pilote autonome : architecture, amélioration continue (Phase 4), garde-fous, audit, reprise, réglages
Évaluations LLM	Benchmarks qualité des sorties LLM
Rate Limiting	Quotas et limites

---

🛠️ Développement

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 est la source unique des dépendances ; les fichiers locks/*.txt en sont générés (python scripts/locks.py, voir w2-installation). Le paquet embarque ses ressources (skills, graines de prompts, migrations) : il s'exécute aussi installé depuis un wheel, hors du dépôt.

Tests :

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