ShopGravity - POC Architecture Multi-Agent MCP

Ce dépôt contient l'implémentation de la stack d'agents MCP démontrant un workflow de développement logiciel augmenté par l'intelligence artificielle.

🧭 Schéma d'Architecture Multi-Agent

🔗 Voir le schéma d'architecture dynamique sur Excalidraw

Le schéma présente une organisation où le Développeur IA-augmented travaille au sein de son IDE dans un cycle d'itération autonome (workflow/tests). Il collabore via le protocole MCP (Model Context Protocol) avec des agents spécialisés :

1. 🔌 Gravity Oracle : Répond à "Comment je m'intègre ?" (connaissance des contrats API et mock de référence).
2. 🧪 Gravity Shield : Répond à "Comment je teste ?" (connaissance des contraintes de qualité et validation de l'intégration continue).
3. 🛠️ Gravity Deploy : Répond à "Comment je déploie ?" (connaissance des règles de déploiements et modélisation pour dev/uat/prd).
4. 📋 Gravity Reports : Répond à "Comment je reporte ?" (connaissance des besoins, roadmap, ticketing, documentation).

---

🏗️ Composition du POC

Le projet est composé des conteneurs suivants orchestrés par docker-compose.yml :

1. agent-gravity-oracle (Le Registre & Mock) :

   • Expose une API REST sur le port 3000 et un serveur MCP SSE sur le port 3001.
   • Gère le mock dynamique de 10 microservices e-commerce.

2. agent-gravity-shield (La Validation CI) :

   • Expose une API REST (Healthcheck) sur le port 3010 et un serveur MCP SSE sur le port 3011.
   • Analyse le code produit (via AST Python) pour valider la qualité, l'intégration des contrats (gestion du 404) et la sécurité.

3. agent-gravity-deploy (Le Platform Engineer) :

   • Expose une API REST (Healthcheck) sur le port 3040 et un serveur MCP SSE sur le port 3041.
   • Permet de générer les configurations Docker et Helm Kubernetes standard, ainsi que de valider le déploiement sur les environnements cibles.

4. agent-gravity-reports (La Roadmap et Documentation) :

   • Expose une API REST (Healthcheck) sur le port 3030 et un serveur MCP SSE sur le port 3031.
   • Met à jour le backlog/ticketing et documente l'état d'architecture globale du projet.

5. services-simulator (Les Backends) :

   • Génère et enregistre les spécifications OpenAPI 3.0 des 10 microservices auprès de agent-gravity-oracle.

---

🚀 Démarrage Rapide

1. Lancer la stack avec Docker Compose

docker compose up --build -d

2. Vérifier que les services sont prêts

• Gravity Oracle : curl http://localhost:3000/services (doit lister les 10 services).
• Gravity Shield : curl http://localhost:3010/ (doit retourner le statut online).
• Gravity Reports : curl http://localhost:3030/ (doit retourner le statut online).
• Gravity Deploy : curl http://localhost:3040/ (doit retourner le statut online).

---

🔌 Connexion des Serveurs MCP (Configuration IDE)

Pour connecter les agents à votre IDE (Cursor, Cline, Antigravity, etc.), ajoutez-les dans votre fichier de configuration MCP (mcp_config.json) :

{
  "mcpServers": {
    "gravity-oracle": {
      "command": "/Users/sebastien.lavayssiere/Code/mcp-openapi-agent/run-gravity-oracle-bridge.sh"
    },
    "gravity-shield": {
      "command": "/Users/sebastien.lavayssiere/Code/mcp-openapi-agent/run-gravity-shield-bridge.sh"
    },
    "gravity-deploy": {
      "command": "/Users/sebastien.lavayssiere/Code/mcp-openapi-agent/run-gravity-deploy-bridge.sh"
    },
    "gravity-reports": {
      "command": "/Users/sebastien.lavayssiere/Code/mcp-openapi-agent/run-gravity-reports-bridge.sh"
    }
  }
}

N.B. : Assurez-vous d'installer les dépendances locales requises : pip install mcp fastapi uvicorn pydantic

---

🎬 Déroulé de la Démo (L'effet "Wow")

Ouvrez le fichier demo/demo.py dans votre IDE et exécutez les étapes suivantes.

Étape 1 : La Découverte à l'aveugle (Gravity Oracle)

• Prompt :

  "Je dois créer une fonction pour récupérer les points de fidélité de l'utilisateur 'user-123'. Cherche la bonne API interne et génère le client Python."

• Comportement : L'agent appelle search_api_endpoints({ query: "points de fidélité" }) puis récupère la spécification de LoyaltyService via get_openapi_spec. Il écrit ensuite le client Python.

Étape 2 : Le Data Mocker Autonome (Gravity Oracle)

• Prompt :

  "Génère un appel à notre serveur de mock dynamique pour cette route avec des données réalistes pour un client VIP."

• Comportement : L'agent écrit l'appel HTTP ciblant http://localhost:3000/mocks/LoyaltyService/v1/loyalty/accounts/user-123?tier=VIP.

Étape 3 : Gestion du Versioning (Gravity Oracle)

• Prompt :

  "Génère la fonction Python pour créer un paiement."

• Comportement : L'agent cherche l'API de paiement, détecte la v1 (obsolète) et la v2 (sécurisée 3DS), puis choisit et implémente automatiquement la spécification v2.

Étape 4 : Validation de Code & Commande /tests (Gravity Shield)

• Prompt (Virtuel / Commande chat) :

  /tests

• Comportement (Intégration Continue) :
  1. Lecture : L'agent lit le code généré dans demo/demo.py.
  2. Validation : Il transmet le code à l'outil run_integration_tests({ service_name: "LoyaltyService", code_snippet: ... }) de l'agent gravity-shield.
  3. Échec attendu : L'agent gravity-shield renvoie un échec (FAILED) car le code client ne gère pas le retour HTTP 404 (scénario où l'utilisateur n'existe pas dans la base de fidélité).
  4. Correction automatique : L'agent de codage analyse le retour de l'outil et modifie instantanément demo.py pour y ajouter un bloc try/except interceptant le 404 et retournant par exemple 0 point.
  5. Validation finale : L'utilisateur relance la commande /tests. L'agent ré-analyse le code et affiche un rapport vert PASSED.

Étape 5 : Conteneurisation & Configuration Infra (Gravity Deploy)

• Prompt :

  "Génère le Dockerfile, le requirements.txt, et le chart Helm (deployment + service ClusterIP) dans le dossier demo/ en utilisant les outils de l'agent gravity-deploy."

• Comportement : L'agent Gravity Deploy génère automatiquement un Dockerfile optimisé pour l'application Python et configure les manifestes Helm Kubernetes (y compris deployment.yaml et service.yaml) nécessaires au déploiement de l'application dans un conteneur standardisé.

Étape 6 : Validation de Déploiement en Dev (Gravity Deploy)

• Prompt :

  "Fait le déploiement de l'application en environnement de dev avec l'agent gravity-deploy."

• Comportement : L'agent fait appel à l'outil de simulation de déploiement en dev (deploy_dev) pour s'assurer que l'image Docker est buildée avec succès, la release Helm mise à niveau, et vérifie la création correcte des pods et services au sein du cluster de développement.

Étape 7 : Roadmap, Alignement & Clôture (Gravity Reports)

• Prompt :

  "Met à jour le ticket de la roadmap et la documentation pour indiquer que l'intégration du LoyaltyService et de PaymentService est terminée avec succès."

• Comportement : L'agent Gravity Reports met à jour le statut du ticket associé (ticket-update) pour le marquer comme complété et met à jour la documentation d'architecture et de spécification (doc-update) afin de garantir que l'architecture réelle reflète fidèlement la roadmap projet.