Généré le 14/10/2026 10:01

🛠️ Spécifications Techniques : Couche Universelle des Outils MCP & Outil Pilote (JUTL)

Projet : Jarvis Universal Tool Layer (JUTL)
Auteur : Antigravity (IA Assistant Système)
Date d'émission : 08 Octobre 2026
Localisation de référence : Guadeloupe (UTC-4)
Statut du jalon : Jalon 1 Réalisé & Validé (5/5 tests unitaires et d'intégration réussis)


1. Contexte & Objectif de la Phase 1

Faisant suite à la validation par Raphaël de l'étude de faisabilité technique sur le Model Context Protocol (MCP) et la convergence du Function Calling in-context, cette phase concrétise le premier palier de l'architecture :
1. Établir le Registre Canonique Universel (tools/registry.py) : point unique de définition, de typage strict et de validation des outils.
2. Mettre en place le Serveur MCP Pivot (tools/jarvis_mcp_server.py) : passerelle JSON-RPC 2.0 stdio consommable nativement par Claude Code, Antigravity, Cursor, ou un moteur DeepSeek.
3. Déployer et éprouver deux outils pilotes représentatifs :
- Un outil système instantané à effet nul (Zero Side-Effect) : meteo_guadeloupe.
- Un outil métier e-commerce complexe à forte valeur ajoutée : generer_rapport_produit_jarvis.
4. Valider l'ensemble par une suite de tests automatisés (tools/test_mcp_pilot.py).


2. Spécifications Techniques du Registre Canonique (registry.py)

2.1 Modèle de Données Canonique (ToolDefinition)

Chaque script ou fonction exposé dans l'écosystème est modélisé de manière immuable :

classDiagram
    class ToolDefinition {
        +str name
        +str description
        +Type[BaseModel] args_model
        +Callable handler
        +str category
        +int timeout_seconds
        +get_json_schema() dict
        +to_mcp() dict
        +to_openai() dict
        +to_anthropic() dict
        +to_gemini() dict
        +execute(dict arguments) dict
    }

2.2 Traduction Multi-LLM Isomorphe

Le Registre agit comme un adaptateur universel vers les 4 principaux formats d'inférence sans perte d'information :

Cible Méthode d'Export Structure Produite Compatibilité Modèles
MCP (Standard Ouvert) to_mcp() {"name": ..., "description": ..., "inputSchema": ...} Claude Desktop, Claude Code, Antigravity CLI
OpenAI / DeepSeek to_openai() {"type": "function", "function": {"name": ..., "description": ..., "parameters": ...}} DeepSeek-V3/R1, GPT-4o, Mistral, Groq, Ollama
Anthropic Claude Native to_anthropic() {"name": ..., "description": ..., "input_schema": ...} Claude 3.5 Sonnet / Claude 3.7
Google Gemini Native to_gemini() {"name": ..., "description": ..., "parameters": {"type": "OBJECT", ...}} Gemini 2.5 / 3.8 Flash, Gemini Live API

[!IMPORTANT]
Règle de conversion Gemini : Les types scalaires JSON Schema (string, integer, boolean, array, object) sont traduits récursivement en majuscules (STRING, INTEGER, BOOLEAN, ARRAY, OBJECT) conformément aux spécifications de l'API Google GenAI.

2.3 Garde-Fous Systèmes Windows

  1. Encodage UTF-8 robuste : Remplacement de l'ancien mécanisme de re-wrapping io.TextIOWrapper (qui provoquait des fermetures intempestives de descripteurs sous Python 3.13) par sys.stdout.reconfigure(encoding="utf-8", errors="replace").
  2. Isolation des Processus Métiers : Les scripts effectuant des écritures disques ou des appels réseau sont invoqués via subprocess.run isolé pour éviter tout effet de bord sur le processus serveur (ex: capture de sys.exit()).

3. Spécifications du Serveur MCP Pivot (jarvis_mcp_server.py)

3.1 Protocole et Transports

3.2 Cycle de Vie des Messages JSON-RPC 2.0

sequenceDiagram
    autonumber
    actor Client as Agent LLM (Claude / Antigravity / DeepSeek)
    participant MCP as Serveur jarvis_mcp_server.py
    participant Reg as Registre Canonique (registry.py)
    participant Tool as Script Métier (tools/*.py)

    Client->>MCP: initialize (protocolVersion, capabilities)
    MCP-->>Client: initialize result (serverInfo: jarvis-universal-tools)
    Client->>MCP: notifications/initialized
    Client->>MCP: tools/list
    MCP->>Reg: export_mcp(pole)
    Reg-->>MCP: [tool1, tool2, ...]
    MCP-->>Client: tools result: {tools: [...]}
    Client->>MCP: tools/call (name, arguments)
    MCP->>Reg: execute(name, arguments)
    Reg->>Reg: Pydantic Validation
    Reg->>Tool: Handler invocation
    Tool-->>Reg: Données retournées
    Reg-->>MCP: {success: true, result: ...}
    MCP-->>Client: content: [{type: "text", text: JSON}]

3.3 Préservation de la Fenêtre de Contexte (Namespaces)

Le serveur accepte l'argument optionnel --pole :
* --pole system : Outils de supervision, météo, statut serveurs.
* --pole ecommerce : Rapports produits, requêtes tracker, jugements.
* --pole studio : Montage UGC, génération d'images et animations.
* --pole reporting : Tableaux de bord, stats de rejets, bilans.


4. Spécifications et Détails des Deux Outils Pilotes

4.1 Pilote 1 : meteo_guadeloupe (Système / Zero-Side-Effect)

4.2 Pilote 2 : generer_rapport_produit_jarvis (Métier E-commerce)


5. Banc d'Essai & Résultats des Tests (test_mcp_pilot.py)

Une suite de validation complète a été exécutée sur l'environnement de Raphaël. Tous les valideurs ont été exécutés avec succès :

ID Test Valideur Objectif Résultat Obtenu
TEST 1 Registre Canonique Vérification de l'enregistrement, des clés et des catégories 🟢 SUCCÈS (2/2 indexés)
TEST 2 Isomorphisme Multi-LLM Validation de conformité des exports MCP, OpenAI, Claude, Gemini 🟢 SUCCÈS (Types alignés)
TEST 3 Exécution Pilote Système Appel direct de meteo_guadeloupe, vérification UTC-4 et repli réseau 🟢 SUCCÈS (UTC-4 garanti)
TEST 4 Validation Typée Pydantic Rejet strict des types non conformes (ligne: "non_int") 🟢 SUCCÈS (Rejet immédiat)
TEST 5 Intégration Bout-en-Bout Dialogue complet client/serveur stdio MCP JSON-RPC 2.0 🟢 SUCCÈS (Handshake & Call OK)

6. Prochaines Étapes : Feuille de Route pour le Jalon 2

La réussite de cette étape pilote permet d'engager immédiatement le déploiement opérationnel :
1. Élargissement du Registre aux 8 outils majeurs :
- tools/juge_produit_orchestrateur.py
- tools/chasse_orchestrateur.py
- tools/telegram_reliable.py
- tools/fast_check_daemons.py
- studio/tools/extract_ads_library.py
- studio/cli.py
- tools/stats_rejets.py
- tools/jarvis_inbox_engine.py
2. Déclaration dans les configurations d'agents :
- Ajout du serveur universel dans la configuration MCP globale (~/.gemini/antigravity-cli/mcp/ et configuration Claude Code).
3. Branchement sur Jarvis Live Voice (server.py) :
- Remplacement de la liste statique d'outils par l'appel dynamique à registry.export_gemini().