Standard de code des modules MCP

Pourquoi un standard de code est important

Chaque connecteur que nous livrons se présente de la même manière. Ce n'est pas un accident — c'est une discipline. Lorsqu'une seconde intégration arrive, les capacités de l'agent sont plus faciles à tester, auditer et remplacer parce que chaque module MCP suit la même structure, la même nomenclature et le même contrat d'erreur.

Ce document définit le standard pour tous les modules MCP dans l'épine dorsale d'orchestration d'IdeaBosque. Il couvre la disposition des répertoires, l'enregistrement des outils, les schémas d'entrée/sortie, la gestion des erreurs, les limites de débit, la journalisation d'audit et le traitement de la frontière PII.

Structure de répertoires

Chaque module MCP réside dans son propre répertoire sous app/mcp_modules/ avec une disposition cohérente :

app/mcp_modules/<slug>/
  __init__.py
  module.py          # Enregistrement des outils + handlers
  schemas.py         # Modèles Pydantic d'entrée/sortie
  tests/
    test_module.py
  README.md

Enregistrement des outils

Chaque module enregistre ses outils via une interface standard. L'épine dorsale d'orchestration découvre les outils en scrutant le point d'entrée register_tools() — aucun câblage manuel.

def register_tools(registrar):
    """Register all tools provided by this module."""
    registrar.tool(
        name="search_catalog",
        description="Search supplier catalog by SKU or name",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # appels par minute
    )

Gestion des erreurs

Les modules doivent lever des exceptions typées, pas des chaînes brutes. L'épine dorsale intercepte les sous-classes de MCPToolError et les convertit en réponses structurées que l'agent peut traiter :

• MCPAuthError — identifiants manquants ou expirés
• MCPRateLimitError — limite de débit en amont atteinte
• MCPTimeoutError — l'appel en amont a dépassé le délai configuré
• MCPValidationError — l'entrée n'a pas passé la validation du schéma
• MCPUpstreamError — l'amont a renvoyé un statut d'erreur

Limites de débit

Chaque outil déclare sa propre limite de débit dans l'appel d'enregistrement. L'épine dorsale les applique par agent, par outil et par fenêtre. Lorsqu'une limite est atteinte, l'agent reçoit une réponse 429 avec un en-tête Retry-After — il ne plante pas et ne réessaie pas aveuglément.

Journalisation d'audit

Chaque appel d'outil est journalisé avec : horodatage, ID de l'agent, nom de l'outil, hachage de l'entrée (pas l'entrée brute — frontière PII), statut de sortie, durée et système en amont. Les journaux sont écrits en JSON structuré et envoyés au pipeline d'observabilité.

« Chaque appel d'outil est journalisé et auditable » n'est pas une fonctionnalité que nous ajoutons plus tard. C'est la première chose que le standard exige.

Traitement de la frontière PII

Les modules doivent déclarer quels champs d'entrée contiennent des PII. L'épine dorsale hache ces champs avant la journalisation et n'envoie jamais de PII brutes au pipeline d'audit. Les champs PII sont marqués dans le schéma :

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

Lorsque pii=True est défini, le journaliseseur d'audit remplace la valeur par un hachage SHA-256. Le handler de l'outil reçoit toujours la valeur brute — le traitement des PII est appliqué à la frontière de journalisation, pas à l'intérieur de la logique métier.