Définir des outils avec MCP

La construction d’un serveur MCP devient beaucoup plus simple avec le SDK Python officiel. Au lieu d’écrire des schémas JSON complexes à la main, vous définissez vos outils avec des décorateurs et vous laissez le SDK produire le schéma. Cette leçon écrit les deux premiers outils de notre serveur de documents : un pour lire, un pour modifier.

Initialiser le serveur MCP

Le SDK MCP Python rend la création de serveur très simple — une seule ligne suffit :

from mcp.server.fastmcp import FastMCP

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

L’objet mcp ainsi créé est le registre central du serveur : c’est lui qui portera les décorateurs de tous les outils, ressources et prompts que nous ajouterons. Le premier argument est le nom sous lequel le serveur se présente aux clients, et log_level="ERROR" limite la sortie aux vraies erreurs, ce qui évite de polluer le canal stdio utilisé pour la communication.

Vos documents peuvent être stockés dans un dictionnaire simple :

docs = {
    "deposition.md": "Ce document couvre le témoignage d'Angela Smith, P.E.",
    "rapport.pdf": "Ce rapport détaille l'état d'une tour de condensation de 20m.",
    "finances.docx": "Ces finances décrivent le budget et les dépenses du projet.",
    "perspectives.pdf": "Ce document présente les performances futures projetées.",
    "plan.md": "Ce plan décrit les étapes de mise en œuvre du projet.",
    "spec.txt": "Ces spécifications définissent les exigences techniques."
}

Définir des outils avec des décorateurs

Le SDK utilise des décorateurs pour définir les outils. Vous n’écrivez pas de schéma JSON : vous annotez les types des paramètres Python et documentez chaque champ, puis le SDK génère le schéma que Claude comprend. La signature de votre fonction devient donc le contrat exposé au modèle, avec une conséquence pratique importante : la qualité de vos descriptions détermine la qualité des appels que fera Claude.

Outil de lecture de documents

Le premier outil lit le contenu d’un document par son identifiant :

from pydantic import Field

@mcp.tool(
    name="read_doc_contents",
    description="Lit le contenu d'un document et le retourne 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} introuvable")
    
    return docs[doc_id]

Le décorateur spécifie le nom et la description de l’outil, tandis que les paramètres de la fonction définissent les arguments requis. La classe Field de Pydantic fournit les descriptions d’arguments qui aident Claude à comprendre ce que chaque paramètre attend. Notez aussi le traitement de l’erreur : si l’identifiant n’existe pas, la fonction lève une ValueError plutôt que de retourner silencieusement None. Quand un utilisateur demandera le contenu d’un document mal orthographié, Claude recevra un message explicite et pourra réagir en conséquence.

Outil d’édition de documents

Le deuxième outil effectue des opérations de recherche-remplacement sur les documents :

@mcp.tool(
    name="edit_document",
    description="Modifie 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, espaces compris."),
    new_str: str = Field(description="Le nouveau texte à insérer à la place de l'ancien.")
):
    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)

Cet outil prend trois paramètres : l’identifiant du document, le texte à trouver, et le texte de remplacement. Observez la description de old_str, qui précise « doit correspondre exactement, espaces compris ». Cette phrase n’est pas là pour le lecteur humain : elle indique au modèle qu’il ne peut pas approximer la chaîne recherchée. C’est un bon exemple de ce qu’apporte une description soignée par rapport à un simple nom de paramètre.

Avantages de l’approche SDK

Le tableau résume ce que le SDK vous épargne par rapport à une définition écrite entièrement à la main.

Pourquoi cette approche fonctionne

Le SDK transforme la création d’outils : d’un exercice de rédaction de schémas, on passe à de simples définitions de fonctions Python. Le gain est surtout de maintenance — ajouter un paramètre revient à ajouter un argument, et le schéma exposé à Claude suit automatiquement, sans divergence possible entre la documentation et le code exécuté.

Il reste à vérifier que tout cela fonctionne. Dans la prochaine leçon, nous testerons ces deux outils avec l’inspecteur MCP intégré, sans écrire une ligne de code de test.