Claude Academy
Chargement

Définir des outils avec MCP

Leçon 519 min

La création d'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 travail le plus lourd.

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 contenu.

Avantages du SDK Python de 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 approprié que Claude peut comprendre et utiliser.

Configuration du serveur

Ce cours utilise la version 1 du SDK Python de 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, la même contrainte 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"
}

Implémentation 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

Implémentation de l'outil de modification

Le second outil effectue de simples opérations de recherche et 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 plus de simplicité.

Détails clés de l'implémentation

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 de MCP convertit automatiquement la signature de votre fonction en un schéma JSON approprié

Le SDK Python de 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 autrefois 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 de 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.