Chargement

Définir des ressources

Leçon 5310 min
Chargement

Les ressources dans les serveurs MCP vous permettent d'exposer des données aux clients, de manière similaire aux gestionnaires de requêtes GET dans un serveur HTTP classique. Elles sont idéales pour les scénarios où vous devez récupérer des informations plutôt que d'effectuer des actions.

Comprendre les ressources à travers un exemple

Supposons que vous souhaitiez créer une fonctionnalité de mention de document où les utilisateurs peuvent taper @nom_du_document pour référencer des fichiers. Cela nécessite deux opérations :

  • Obtenir une liste de tous les documents disponibles (pour l'autocomplétion)
  • Récupérer le contenu d'un document spécifique (lorsqu'il est mentionné)

Un « @ » tapé dans une invite de chat ouvre une liste de documents, tels que deposition.md et spec.md, chacun étiqueté « Resource ».

Lorsqu'un utilisateur tape @, vous devez afficher les documents disponibles. Lorsqu'il soumet un message contenant une mention, vous injectez automatiquement le contenu de ce document dans la requête envoyée à Claude.

Taper un arobase liste des documents tels que design.md, chacun étiqueté « Resource », et une mention injecte le contenu de report.pdf.

Comment fonctionnent les ressources

Les ressources suivent un modèle requête-réponse. Votre client envoie une ReadResourceRequest avec un URI, et le serveur MCP répond avec les données. L'URI agit comme une adresse pour la ressource à laquelle vous souhaitez accéder.

Diagramme d'un serveur MCP contenant deux définitions de ressources, list_docs et fetch_doc, présentées dans le code ci-dessous.

Types de ressources

Il existe deux types de ressources :

Code du décorateur pour une ressource directe sans paramètre dans son URI et une ressource avec modèle utilisant doc_id, décrites ci-dessous.

  • Ressources directes : URIs statiques qui ne changent pas, comme docs://documents
  • Ressources avec modèle : URIs avec paramètres, comme docs://documents/{doc_id}

Pour les ressources avec modèle, le SDK Python analyse automatiquement les paramètres de l'URI et les transmet en tant qu'arguments nommés à votre fonction.

Implémenter des ressources

Les ressources sont définies à l'aide du décorateur @mcp.resource(). Voici comment créer les deux types :

Ressource directe (liste de documents)

python
@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

Ressource avec modèle (récupération de document)

python
@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

Types MIME

Les ressources peuvent renvoyer tout type de données - chaînes de caractères, JSON, binaire, etc. Le paramètre mime_type donne aux clients une indication sur le type de données que vous renvoyez :

  • application/json - Données JSON structurées
  • text/plain - Contenu texte brut
  • Tout autre type MIME valide pour différents formats de données

Le SDK Python MCP sérialise automatiquement vos valeurs de retour. Vous n'avez pas besoin de les convertir manuellement en chaînes JSON.

Tester les ressources

Vous pouvez tester vos ressources à l'aide du MCP Inspector. Exécutez votre serveur avec :

bash
uv run mcp dev mcp_server.py

Connectez-vous ensuite à l'inspecteur dans votre navigateur. Vous verrez :

Onglet Resources du MCP Inspector, avec docs://documents répertorié sous Resources et rien répertorié sous Resource Templates.

  • Resources : Liste vos ressources directes/statiques
  • Resource Templates : Affiche les ressources avec modèle qui acceptent des paramètres

Cliquez sur n'importe quelle ressource pour la tester et voir la structure de réponse exacte que votre client recevra.

Onglet Resources du MCP Inspector : la lecture de docs://documents renvoie une liste JSON de noms de fichiers tels que deposition.md et plan.md.

Points clés

  • Les ressources exposent des données, les outils effectuent des actions
  • Utilisez des ressources directes pour les données statiques, des ressources avec modèle pour les requêtes paramétrées
  • Les types MIME aident les clients à comprendre le format de réponse
  • Le SDK gère automatiquement la sérialisation
  • Les noms de paramètres dans les URIs avec modèle deviennent des arguments de fonction

Les ressources offrent un moyen simple de mettre des données à la disposition des clients MCP, permettant des fonctionnalités telles que les mentions de documents, la navigation dans les fichiers, ou tout scénario où vous devez récupérer des informations depuis votre serveur.