Définir des outils avec MCP

Le projet est en place ; écrivons le serveur. Le SDK Python officiel de MCP simplifie considérablement la création de serveurs : au lieu d’écrire manuellement des schémas JSON complexes — le travail laborieux de la section outils —, le SDK gère toute cette complexité grâce aux décorateurs et aux annotations de type Python. Si vous vous souvenez de l’effort qu’exigeait chaque schéma, la suite va vous sembler délicieusement courte.

Initialisation du serveur

Créer un serveur MCP complet ne nécessite qu’une seule ligne :

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("DocumentMCP", log_level="ERROR")

FastMCP est l’interface haut niveau du SDK — c’est elle qui fournira les décorateurs et gérera tout le protocole. Le nom « DocumentMCP » identifie le serveur auprès des clients ; le niveau de log réduit garde la sortie standard propre — un détail qui compte, puisque le transport stdio passe justement par elle.

Les documents sont stockés dans un simple dictionnaire Python :

docs = {
    "rapport.md": "Ce rapport détaille l'état d'une tour de condensation.",
    "financials.docx": "Ces données financières décrivent le budget du projet.",
    "plan.md": "Le plan décrit les étapes de mise en oeuvre du projet.",
}

Ce dictionnaire est notre « base documentaire » : volontairement simpliste, et interchangeable — le remplacer par un accès au système de fichiers ou à une vraie base ne changerait rien aux outils qui suivent, ni à ce qu’en verront les clients.

Définir des outils avec des décorateurs

Outil de lecture de document

@mcp.tool(
    name="read_doc_contents",
    description="Lire le contenu d'un document et le retourner sous forme de chaîne."
)
def read_document(
    doc_id: str = Field(description="Identifiant du document à lire")
):
    if doc_id not in docs:
        raise ValueError(f"Document avec l'id {doc_id} non trouvé")
    return docs[doc_id]

Le décorateur @mcp.tool génère automatiquement le schéma JSON dont Claude a besoin — le nom et la description viennent du décorateur, les paramètres et leurs types de la signature, les descriptions d’arguments des Field. Tout ce que vous écriviez à la main est désormais dérivé du code. Et les réflexes des fonctions d’outils s’appliquent inchangés : validation de l’entrée, erreur explicite — ce ValueError ne tuera pas le serveur, le SDK le convertira en erreur MCP propre que Claude recevra comme message exploitable.

Outil de modification de document

@mcp.tool(
    name="edit_document",
    description="Modifier un document en remplaçant une chaîne par une nouvelle."
)
def edit_document(
    doc_id: str = Field(description="Identifiant du document à modifier"),
    old_str: str = Field(description="Le texte à remplacer. Doit correspondre exactement."),
    new_str: str = Field(description="Le nouveau texte à insérer.")
):
    if doc_id not in docs:
        raise ValueError(f"Document avec l'id {doc_id} non trouvé")
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Vous reconnaissez le mécanisme d’édition par remplacement exact — celui du text editor tool et des agents de code. Regardez la description de old_str : « Doit correspondre exactement » n’est pas décoratif, c’est une instruction opérationnelle que Claude appliquera en fournissant le texte à l’identique. SDK ou pas, les descriptions restent votre principal levier de fiabilité — c’est toujours ce texte, et lui seul, que le modèle lit.

Avantages de cette approche

Le bénéfice de fond dépasse le confort : puisque le schéma est dérivé de la fonction, il ne peut plus diverger de l’implémentation — la classe de bugs « le schéma promet ce que le code ne fait pas » disparaît par construction. Un outil complet tient en une fonction annotée ; reste à prouver que ces outils fonctionnent, et c’est le rôle de l’inspecteur, à la prochaine leçon.

Points clés à retenir

• FastMCP + @mcp.tool : le serveur en une ligne, chaque outil en une fonction décorée
• Le schéma JSON est généré depuis signature, types et Field — il ne peut pas diverger du code
• Les descriptions restent le levier de fiabilité : Claude ne lit qu’elles
• Exceptions Python → erreurs MCP propres : validez et levez explicite, comme toujours
• Le stockage en dictionnaire est interchangeable — le protocole n’en verrait aucune différence