Définir des outils avec MCP

Place au code du serveur. Le SDK Python officiel de MCP simplifie radicalement la construction de serveurs : au lieu d’écrire manuellement des schémas JSON complexes pour les outils — le travail fastidieux de la section Tool Use —, vous les définissez avec des décorateurs, et le SDK gère le reste. Si vous gardez en mémoire l’effort qu’exigeait chaque schéma, la suite va vous paraître délicieusement courte.

Avantages du SDK Python MCP

Ce que le SDK prend à sa charge :

• Création de serveurs MCP avec un minimum de code boilerplate
• Génération automatique de schémas JSON depuis les signatures de fonctions Python
• Définition simplifiée des outils via des décorateurs
• Validation des types et gestion des erreurs intégrées

Le principe sous-jacent : tout ce que vous écririez à la main est déjà exprimé par votre code Python. La signature donne les paramètres et leurs types, les Field donnent les descriptions, les exceptions donnent les erreurs — le SDK ne fait que traduire.

Configuration du serveur

from mcp.server.fastmcp import FastMCP
from pydantic import Field

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

docs = {
    "deposition.md": "Ce document couvre le témoignage d'Angela Smith...",
    "report.pdf": "Le rapport detaille l'etat d'une tour de condensation...",
    "financials.docx": "Ces données financières décrivent le budget du projet...",
    "outlook.pdf": "Ce document presente les performances projetees...",
    "plan.md": "Le plan décrit les étapes de mise en oeuvre...",
    "spec.txt": "Ces spécifications définissent les exigences techniques..."
}

FastMCP est l’interface haut niveau du SDK — elle fournit les décorateurs et gérera tout le protocole. Le dictionnaire docs est notre « base documentaire » en mémoire : six faux documents suffisent au projet, et remplacer ce dictionnaire par un vrai système de fichiers ou une base de données ne changerait rien aux outils qui suivent.

Implémenter l’outil de lecture

@mcp.tool(
    name="read_doc_contents",
    description="Lire le contenu d'un document et le renvoyer sous forme de chaîne."
)
def read_document(
    doc_id: str = Field(description="Id du document a lire")
):
    if doc_id not in docs:
        raise ValueError(f"Document avec l'id {doc_id} introuvable")

    return docs[doc_id]

Tout le pattern est là : le décorateur @mcp.tool déclare le nom et la description — le texte que Claude lira pour décider d’appeler l’outil —, le paramètre typé avec son Field documente l’argument, et le corps applique les réflexes des fonctions d’outils : valider l’entrée, lever une erreur explicite. Cette exception ne tuera pas le serveur — le SDK la convertira en erreur MCP correctement formée, que Claude recevra comme message exploitable.

Implémenter l’outil d’édition

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

    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. Notez 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, espaces compris. SDK ou pas, les descriptions restent votre principal levier de fiabilité.

Points clés

Les réflexes à emporter :

• Importez Field de pydantic pour les descriptions de paramètres
• Utilisez les type hints pour spécifier les types de paramètres
• Incluez la gestion d’erreurs pour les cas limites
• Écrivez des noms et descriptions d’outils clairs et descriptifs
• Le SDK convertit automatiquement votre signature de fonction en schéma JSON

Un outil complet tient désormais en une fonction annotée — et le schéma ne peut plus diverger de l’implémentation, puisqu’il en est dérivé. Le SDK réduit considérablement la complexité par rapport à l’écriture manuelle de schémas JSON ; reste à vérifier que ces outils fonctionnent, et c’est le rôle de l’inspecteur, à la prochaine leçon.

Points clés à retenir

• @mcp.tool fusionne fonction et déclaration : le schéma JSON est généré depuis la signature
• Les descriptions (outil et Field) sont ce que Claude lit — rédigez-les comme des instructions
• Les exceptions Python deviennent des erreurs MCP propres : validez et levez explicite
• Le stockage en mémoire est interchangeable — les outils survivraient tels quels à une vraie base
• Schéma dérivé du code = plus jamais de divergence schéma/implémentation