Définir des outils avec MCP

La création d'un serveur MCP devient beaucoup plus simple lorsque vous utilisez le SDK Python officiel. Au lieu d'écrire des schémas JSON complexes à la main, vous pouvez définir des outils avec des décorateurs et laisser le SDK se charger du travail le plus lourd.



Dans cet exemple, nous créons un serveur de gestion de documents avec deux outils principaux : l'un pour lire des documents et l'autre pour les mettre à jour. Tous les documents existent en mémoire sous la forme d'un simple dictionnaire où les clés sont des identifiants de documents et les valeurs sont le contenu.

Récupérer le projet

Les leçons de ce cours s'appuient sur un petit projet de démarrage, un chatbot en ligne de commande doté d'un client MCP et d'un serveur MCP. Téléchargez cli_project.zip depuis la section Téléchargements à la fin de cette leçon et extrayez-le dans le répertoire de développement de votre choix. Ouvrez votre éditeur de code dans le dossier du projet.

Le projet inclut un fichier README contenant les instructions d'installation. Ajoutez votre clé API Anthropic au fichier .env. Installez ensuite les dépendances en utilisant soit uv (recommandé), soit pip. Le projet utilise la version 1 du SDK Python MCP, et son installation installe cette version pour vous.

Configurer le serveur MCP

Le SDK Python MCP simplifie la création de serveurs. Ouvrez mcp_server.py. Il initialise déjà un serveur en une seule ligne. Les outils ci-dessous nécessitent également l'import Field :

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

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

Vos documents peuvent être stockés dans une structure de dictionnaire simple :

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

Définition d'outils avec des décorateurs

Le SDK utilise des décorateurs pour définir les outils. Au lieu d'écrire des schémas JSON manuellement, vous pouvez utiliser des indications de type Python et des descriptions de champs. Le SDK génère automatiquement le schéma approprié que Claude peut comprendre.

Créer un outil de lecture de documents

Le premier outil lit le contenu d'un document par son identifiant. Voici l'implémentation complète :

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    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 des descriptions d'arguments qui aident Claude à comprendre ce qu'attend chaque paramètre.

Créer un outil d'édition de documents

Le second outil effectue de simples opérations de recherche et remplacement sur les documents :

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Cet outil prend trois paramètres : l'identifiant du document, le texte à rechercher et le texte de remplacement. L'implémentation inclut une gestion des erreurs pour les documents manquants et effectue un remplacement de chaîne simple.

Principaux avantages de l'approche par SDK

• Aucune écriture manuelle de schéma JSON requise
• Les indications de type fournissent une validation automatique
• Des descriptions de paramètres claires aident Claude à comprendre l'utilisation de l'outil
• La gestion des erreurs s'intègre naturellement aux exceptions Python
• L'enregistrement des outils se fait automatiquement via les décorateurs

Le SDK Python MCP transforme la création d'outils, qui passe d'un exercice complexe d'écriture de schémas à de simples définitions de fonctions Python. Cette approche facilite grandement la création et la maintenance de serveurs MCP tout en garantissant que Claude reçoit des spécifications d'outils correctement formatées.