Chargement

Définir des outils avec MCP

Leçon 519 min
Chargement

Créer un serveur MCP devient beaucoup plus simple lorsque vous utilisez le SDK Python officiel de MCP. Au lieu d'écrire manuellement des schémas JSON complexes pour les outils, vous pouvez les définir avec des décorateurs et laisser le SDK se charger du plus gros du travail.

Les outils de lecture et de mise à jour de notre serveur MCP connectés à quatre fichiers : document.pdf, spreadsheet.xlsx, report.txt et spec.md.

Dans cet exemple, nous créons un serveur MCP qui gère des opérations sur des documents. Le serveur disposera de deux outils principaux : l'un pour lire le contenu 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 les chaînes de caractères du contenu.

Avantages du SDK Python MCP

Le projet MCP fournit des SDK officiels pour créer des serveurs et des clients dans plusieurs langages de programmation. L'utilisation du SDK Python offre plusieurs avantages :

  • Crée des serveurs MCP avec un minimum de code répétitif
  • Génère automatiquement des schémas JSON à partir des signatures de fonctions Python
  • Simplifie la définition des outils grâce à des décorateurs
  • Gère la validation des types et la gestion des erreurs

Les outils de lecture et de mise à jour de notre serveur MCP connectés à quatre fichiers : document.pdf, spreadsheet.xlsx, report.txt et spec.md.

Voici à quel point il est facile de définir un outil avec le SDK. Le décorateur @mcp.tool, combiné à des indications de type et à des descriptions de champs, crée automatiquement le schéma d'outil adéquat que Claude peut comprendre et utiliser.

Configuration du serveur

Ce cours utilise la version 1 du SDK Python MCP. L'importation ci-dessous échoue avec la version 2, qui a renommé FastMCP. Si vous configurez le projet vous-même, conservez une version du SDK inférieure à la version 2 :

bash
uv add "mcp[cli]<2"

Avec pip, le même blocage de version s'écrit pip install "mcp[cli]<2".

La configuration de base du serveur ne nécessite que quelques lignes :

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

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

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"
}

Mise en œuvre de l'outil de lecture

Le premier outil permet à Claude de lire le contenu d'un document en fournissant un identifiant de document :

python
@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]

La définition de l'outil comprend :

  • Un nom clair qui décrit l'action
  • Une description expliquant ce que fait l'outil
  • Des paramètres typés avec des descriptions de champs
  • Une gestion des erreurs pour les identifiants de documents invalides

Mise en œuvre de l'outil de modification

Le deuxième outil effectue de simples opérations de recherche et de remplacement sur le contenu d'un document :

python
@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 utilise la méthode intégrée de Python replace() pour les chaînes de caractères, par souci de simplicité.

Points clés de mise en œuvre

Lorsque vous définissez des outils avec le SDK MCP, gardez à l'esprit ces points importants :

  • Importez Field depuis pydantic pour ajouter des descriptions de paramètres
  • Utilisez des indications de type pour spécifier les types de paramètres
  • Incluez une gestion des erreurs pour les cas limites
  • Rédigez des noms et des descriptions d'outils clairs et explicites
  • Le SDK Python MCP convertit automatiquement la signature de votre fonction en schéma JSON adéquat

Le SDK Python MCP réduit considérablement la complexité de la création d'outils par rapport à l'écriture manuelle de schémas JSON. Ce qui nécessitait auparavant des dizaines de lignes de définition de schéma ne prend désormais que quelques lignes de fonctions Python décorées.

Le décorateur @mcp.tool et sa génération de schéma basée sur la signature proviennent du SDK Python MCP. Le Claude Agent SDK fournit un décorateur @tool distinct pour définir des outils personnalisés, et il attend un argument input_schema explicite plutôt que des annotations pydantic Field sur la signature de la fonction. En Python, ce schéma est un dictionnaire associant des noms de paramètres à des types, comme {"latitude": float}, que l'Agent SDK convertit pour vous en JSON Schema, ou un dictionnaire JSON Schema complet lorsque vous avez besoin d'énumérations, de plages, de champs optionnels ou d'objets imbriqués. Lorsque vous lisez du code d'outil ailleurs, vérifiez quel SDK il importe, car les deux décorateurs sont faciles à confondre.