Ressources
- Leçon 5
- 50 min
- Module 2 : Concevoir des capacités de serveur utiles
Où nous en sommes
Dans la leçon précédente, nous avons conçu deux outils ciblés que le modèle peut appeler. Mais un document de politique n'est pas une action : une application doit le répertorier, le lire au complet et le citer. Dans cette leçon, nous donnons à chaque document de politique une adresse stable, et nous décidons qui peut lire chaque document, comme les cotes dans une bibliothèque.
Leçon 5 sur 22 · MCP : connecter les applications d'IA aux outils et aux donnéesRessources
1. Comprendre le problème d'intégration
2. Concevoir des capacités de serveur utiles
3. Créer et examiner un serveur local
4. Connecter une application d'IA
5. Accès à distance et autorisation
6. Protéger les outils et le contrôle de l'utilisateur
7. Exploiter et maintenir l'intégration
Ce que vous saurez faire
Donnez à chaque document de politique une adresse stable qui ne change jamais. Une application pourra ainsi le répertorier, le lire au complet et le citer. Décidez ensuite qui peut lire chaque document, et donnez la même réponse pour chaque refus.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les outils, les contrats et les limites, vus dans Outils.
- Les organisations et les rôles (
owner(propriétaire),staff(personnel),read_only(lecture seule)), vus dans Utilisateurs et organisations du cours sur l’authentification.
Votre projet
~/projects/support-mcpaprès la dernière leçon, avec l’environnement virtuel actif :python -m pytest -qaffiche20 passed(20 tests réussis).- Cette leçon n’ajoute aucun fichier. Elle examine la partie de
support_mcp/contracts.pyconsacrée aux ressources.
Les cotes dans une bibliothèque
Section intitulée « Les cotes dans une bibliothèque »Pensez à une bibliothèque. Chaque livre a une cote, comme HIS 942.1 ROW. La cote indique où se trouve le livre et reste la même pendant des années. Quand une nouvelle édition arrive, le livre garde sa cote. Seule l’édition indiquée sur la première page change.
Vous pouvez trouver un livre de deux façons. Vous pouvez consulter le catalogue, une liste de toutes les cotes. Ou vous pouvez déduire une cote à partir du modèle : section, numéro, auteur. Les deux façons mènent au même rayon.
Vous choisissez aussi vous-même un livre, et vous le lisez au complet. Le bibliothécaire ne choisit pas pour vous et ne vous donne pas une seule phrase de la page 40.
Certains livres restent dans une salle réservée au personnel. Le bibliothécaire vérifie votre carte avant de vous en remettre un. Si vous ne pouvez pas le consulter, la réponse est « nous ne l’avons pas ».
Le problème : un extrait n’est pas la politique
Section intitulée « Le problème : un extrait n’est pas la politique »Grace est responsable des politiques de Larkfield. Elle pose une question simple à Amira : « Quand l’assistant répond au sujet d’un article endommagé, que lit le modèle? »
Amira lui montre. L’outil de recherche renvoie un extrait de la bonne politique, comme le contrat le permet. Voici cet extrait, tiré de l’enregistrement du cours pour search_knowledge avec « retourner un article endommagé » :
… no, you can keep or recycle the damaged item. - Items of 50 dollars or more: we send a free return label, or arrange a …La politique complète, damaged-or-wrong-items, compte 867 caractères et six sections. La première section est « Signaler dans les 14 jours ». L’extrait commence au milieu de la troisième. Une réponse rédigée à partir de cet extrait peut dire au client de garder un article peu coûteux. Elle peut oublier les 14 jours et la photo. Un résultat de recherche limité convient pour trouver une politique. Il ne convient pas pour la citer.
Tomás propose un autre outil : get_policy(name). Kwame pose deux questions. D’abord, qui décide quand lire la politique au complet? Avec un outil, seul le modèle décide. Sam ne peut pas ouvrir lui-même la politique ni la joindre à la conversation. Ensuite, quel est le nom de la politique? « Le troisième résultat de recherche » change quand le classement change. Une réponse qui cite une politique a besoin d’une adresse qui reste stable.
L’idée : des ressources avec des URI stables
Section intitulée « L’idée : des ressources avec des URI stables »Une ressource est un contenu qu’un serveur propose de lire, comme un document. Chaque ressource a un URI, un identificateur de ressource uniforme. C’est une courte chaîne qui désigne une chose, comme une adresse Web. L’application ou la personne choisit les ressources à lire. Le modèle ne choisit pas. C’est la principale différence avec un outil.
Un client trouve les ressources de deux façons, comme avec le catalogue de la bibliothèque et son modèle de cotes :
resources/listrenvoie la liste des ressources concrètes, chacune avec son URI, un nom, un titre et un type.resources/templates/listrenvoie des modèles de ressources : des modèles avec des paramètres entre accolades, commepolicy://{tenant}/{doc_id}. Un modèle décrit toute une famille d’URI sans les énumérer. Il suit une norme, URI Template (RFC 6570).
Ensuite, resources/read, avec un URI, renvoie le contenu au complet.
La conception d’Amira prévoit un URI par document de politique :
policy://larkfield/returns-policyIl comporte trois parties. policy:// est le schéma, un nom que Larkfield choisit pour son propre type de contenu. larkfield est l’organisation. returns-policy est l’identifiant du document. L’identifiant reste le même quand le texte change; c’est le numéro de version du document qui change. Ainsi, une réponse qui cite policy://larkfield/returns-policy pointera encore vers la politique de retour l’an prochain.
Un petit exemple : un URI, trois vérifications
Section intitulée « Un petit exemple : un URI, trois vérifications »La partie de contracts.py consacrée aux ressources contient le modèle et une expression régulière qui décompose un URI :
POLICY_URI_TEMPLATE = "policy://{tenant}/{doc_id}"POLICY_URI = re.compile(r"^policy://(?P<tenant>[a-z]+)/(?P<doc_id>[a-z0-9-]{1,60})$")
def policy_uri(tenant: str, doc_id: str) -> str: return POLICY_URI_TEMPLATE.format(tenant=tenant, doc_id=doc_id)POLICY_URI permet seulement des lettres minuscules pour l’organisation. Pour l’identifiant, il permet des lettres minuscules, des chiffres et -, jusqu’à 60 caractères. Voici une vraie session Python qui l’utilise :
>>> from support_mcp import contracts>>> m = contracts.POLICY_URI.match("policy://larkfield/returns-policy")>>> m["tenant"], m["doc_id"]('larkfield', 'returns-policy')>>> contracts.POLICY_URI.match("policy://larkfield/../secrets")>>> contracts.POLICY_URI.match("https://larkfield.example/returns")>>>Le premier URI correspond au modèle, et les deux parties sont extraites. Les deux autres n’affichent rien : match renvoie None (aucune valeur), donc ce ne sont pas des URI de politique. ../secrets tente de sortir du dossier, comme dans un chemin de fichier. L’adresse https:// est une page Web, pas un document de Larkfield. Aucun des deux ne peut atteindre le service métier.
La forme correcte n’est que la première vérification. Avant de répondre à resources/read, le serveur en fait trois :
Description textuelle du diagramme
L’URI policy://larkfield/returns-policy comporte trois parties : le schéma policy://, l’organisation larkfield et l’identifiant du document returns-policy. Cet identifiant reste le même quand le texte change. Le modèle pour cette famille est policy://{tenant}/{doc_id}.
Le serveur vérifie trois choses, dans l’ordre. Un « non » à n’importe quelle vérification donne la même réponse, −32602 « Resource not found » (ressource introuvable).
- L’URI a-t-il la forme
policy://{tenant}/{doc_id}? {tenant}est-il l’organisation de l’appelant?- Le document existe-t-il, et cet appelant peut-il le lire?
| URI | Appelant | Réponse |
|---|---|---|
policy://larkfield/gift-cards |
Sam (personnel, Larkfield) | le texte Markdown, 433 caractères |
policy://bramble/returns-policy |
Sam | −32602 Resource not found (vérification 2) |
policy://larkfield/refund-approval-procedure |
Omar (lecture seule, Larkfield) | introuvable (vérification 3 : réservé au personnel) |
policy://larkfield/../secrets |
n’importe qui | introuvable (vérification 1 : aucune correspondance) |
Regardez la deuxième ligne. Bramble Books possède vraiment un document appelé returns-policy. Pourtant, la réponse est la même que pour un document qui n’existe pas. Si la réponse était « accès interdit », Sam apprendrait que Bramble a une politique de retour et pourrait deviner ses autres documents. Une même réponse pour les deux cas ne révèle rien à l’appelant sur l’autre organisation. Le cours sur l’authentification enseigne la même règle dans Requêtes sûres pour chaque locataire.
L’organisation dans l’URI n’est jamais une clé qui ouvre une porte. Le serveur la compare à l’organisation de l’appelant, qu’il connaît grâce à la connexion, comme pour les outils.
Larkfield : neuf documents, neuf URI
Section intitulée « Larkfield : neuf documents, neuf URI »Larkfield possède 9 documents de politique. L’un d’eux, refund-approval-procedure, est réservé au personnel : il explique aux agents comment approuver les remboursements manuels. La liste dépend donc de l’appelant. Voici une vraie session avec le service métier :
>>> from support_mcp.knowledge import Knowledge>>> k = Knowledge()>>> for d in k.documents("larkfield", staff=True): print(contracts.policy_uri("larkfield", d["doc_id"]), d["access"], d["version"])...policy://larkfield/damaged-or-wrong-items public 2policy://larkfield/delivery-policy public 4policy://larkfield/gift-cards public 1policy://larkfield/order-changes-and-cancellations public 2policy://larkfield/refund-approval-procedure staff 2policy://larkfield/refunds-and-payments public 3policy://larkfield/returns-policy public 3policy://larkfield/supplier-aquaflow-hose-reels public 1policy://larkfield/warranty-policy public 5>>> len(k.documents("larkfield", staff=True)), len(k.documents("larkfield", staff=False))(9, 8)>>> k.document("larkfield", "refund-approval-procedure", staff=False)support_mcp.knowledge.NotFound: Not found.Sam, qui fait partie du personnel, obtient 9 URI. Omar, qui a un accès en lecture seule, en obtient 8. Quand un appelant en lecture seule demande le document réservé au personnel par son URI, le service métier répond « Not found. » (introuvable). Les numéros de version montrent l’utilité des identifiants stables : la politique de livraison en est à sa quatrième version. Son URI n’a jamais changé.
Dans le module 3, le serveur envoie cette liste en réponse à resources/list. L’enregistrement du serveur terminé fourni dans le cours, pour Sam, compte 1 806 octets et 9 entrées. Voici l’une d’elles :
{"description": "policy, version 3", "mimeType": "text/markdown", "name": "returns-policy", "title": "Returns policy", "uri": "policy://larkfield/returns-policy"}mimeType indique le type de texte renvoyé : Markdown. La réponse à resources/templates/list compte 392 octets. Elle contient un modèle, policy://{tenant}/{doc_id}, nommé policy : « Le texte complet d’un document de politique de votre organisation. » Voici maintenant les deux réponses enregistrées à resources/read, abrégées :
{"contents": [{"mimeType": "text/markdown", "text": "# Gift cards\n\n## Buying a gift card\nWe sell gift cards from 25 to 500 dollars. …", "uri": "policy://larkfield/gift-cards"}]}
{"code": -32602, "message": "Resource not found: policy://bramble/returns-policy", "data": {"uri": "policy://bramble/returns-policy"}}La première est un résultat : toute la politique sur les cartes-cadeaux, soit 433 caractères de Markdown. La deuxième est une erreur avec le code −32602, que MCP utilise pour une ressource introuvable. Le module 3 explique les codes d’erreur.
Quelle quantité de texte une ressource renvoie-t-elle? Le document au complet. Voici les neuf documents de Larkfield, comparés aux 300 caractères permis dans un extrait de recherche :
- un document de Larkfield (une ressource)
- la limite des extraits de recherche
Description textuelle du graphique
Un graphique à points avec deux lignes, de 0 à 3 000 caractères. La première ligne comporte neuf points, un par document de Larkfield : damaged-or-wrong-items 867, delivery-policy 2,150, gift-cards 433, order-changes-and-cancellations 724, refund-approval-procedure 1,059, refunds-and-payments 1,432, returns-policy 1,744, supplier-aquaflow-hose-reels 873, warranty-policy 2,846. La deuxième ligne comporte un point à 300, la limite des extraits. Chaque document est plus long qu’un extrait. Le plus court, celui sur les cartes-cadeaux, compte 433 caractères; le plus long, la politique de garantie, en compte 2,846.
Chaque document est plus long qu’un extrait. C’est la raison d’avoir les deux capacités : la recherche trouve la bonne politique, et la ressource fournit son texte complet. Le résultat de recherche contient même l’URI de la ressource, ce qui facilite le passage de l’un à l’autre.
Qui choisit : un outil ou une ressource
Section intitulée « Qui choisit : un outil ou une ressource »Le même serveur peut proposer la même politique de deux façons. La différence est la personne qui décide de la lire. La séquence ci-dessous présente une conception pour un hôte, comme l’assistant du service de soutien. L’hôte du cours, dans le module 4, utilise seulement des outils.
Description textuelle du diagramme
- L’hôte envoie
resources/list. Le serveur répond avec 9 URI de politique pour Sam (8 pour un membre en lecture seule). - L’application choisit une ressource. Sam joint « Politique de retour ». L’hôte envoie
resources/read policy://larkfield/returns-policyet reçoit le document complet en Markdown. - L’hôte envoie la question de Sam et le texte joint au modèle.
- Le modèle choisit un outil. Il propose
search_knowledge. L’hôte envoietools/callet reçoit 3 correspondances : des extraits d’au plus 300 caractères, chacun avec son URIpolicy://. - L’hôte transmet les correspondances au modèle.
Essayez les URI
Section intitulée « Essayez les URI »-
Lancez Python dans le dossier du projet, avec l’environnement virtuel actif :
Fenêtre de terminal python -
Tapez les lignes des deux sessions ci-dessus, de
from support_mcp import contractsàk.document(…). Comparez chaque réponse avec la leçon. Seules les lignesTraceback(trace d’erreur) avantNotFound(introuvable) diffèrent. -
Essayez maintenant Bramble Books. Tapez
len(k.documents("bramble", staff=False)). Cette commande affiche4: Bramble Books possède 5 documents, dont un,supplier-terms, est réservé au personnel. -
Quittez Python avec
exit().
Cette leçon n’ajoute aucun fichier ni aucun test. Le test de contrat test_policy_uris_are_stable_and_parseable, de la dernière leçon, vérifie déjà le modèle, les parties et le refus de ../secrets.
Quand utiliser une ressource, et ce qu’elle coûte
Section intitulée « Quand utiliser une ressource, et ce qu’elle coûte »Utilisez une ressource pour du contenu qu’une personne lit au complet et qui a une identité stable. Par exemple : une politique, une page de manuel ou une fiche de produit. Elle convient quand l’application ou la personne doit la choisir, et quand une réponse doit la citer.
N’utilisez pas une ressource pour tout :
- Les dossiers clients, comme les billets de soutien. Un billet contient des données personnelles, et l’assistant en a besoin d’un à la fois, pour une tâche.
get_ticketpermet au modèle de demander le billet sur lequel il travaille, avec un résultat limité. Unresources/listde tous les billets serait une liste sans limite de clients. - Les réponses qui nécessitent un calcul, comme une recherche. Les mots changent chaque fois, donc il n’y a rien de stable à nommer. Cela relève d’un outil.
- Le contenu volumineux ou qui augmente. Une ressource renvoie tout. La plus longue politique de Larkfield compte 2 846 caractères, ce qui convient. Un manuel de 300 pages devrait être divisé en sections, chacune avec son propre URI.
Les ressources ont aussi des coûts :
- Tout le texte entre dans le contexte. Joignez trois longues politiques, et le modèle les lit toutes à chaque tour.
- La liste elle-même nécessite des vérifications. La liste dépend de l’appelant : 9 documents pour Sam, 8 pour Omar.
resources/listdoit donc vérifier l’appelant, commeresources/read. - Les hôtes diffèrent. Le protocole définit les ressources, mais chaque hôte décide comment les afficher, ou s’il les utilise. Vérifiez chaque hôte que vous prévoyez prendre en charge.
Erreurs courantes
Section intitulée « Erreurs courantes »Erreur courante
Un URI qui ne correspond jamais au modèle
Symptôme : chaque lecture d’un document échoue, même si le document existe. Dans Python, contracts.POLICY_URI.match("policy://Larkfield/Returns_Policy") n’affiche rien : le résultat est None.
Cause : le modèle permet seulement les lettres minuscules, les chiffres et -. Larkfield contient une majuscule, et Returns_Policy contient des majuscules et un trait de soulignement.
Correction : construisez les URI avec contracts.policy_uri(tenant, doc_id) à partir des identifiants dans les données, jamais à la main. N’assouplissez pas le modèle : une forme stricte est la première vérification.
Erreur courante
Un document réservé au personnel qui semble manquer
Symptôme : k.document("larkfield", "refund-approval-procedure", staff=False) déclenche NotFound: Not found., mais le document se trouve dans data/documents.jsonl.
Cause : c’est la vérification d’accès. Le document est marqué staff, et l’appel a été fait comme membre en lecture seule.
Correction : il n’y a rien à corriger. Utilisez staff=True seulement pour les propriétaires et le personnel. Dans le module 3, le serveur tire cette valeur du rôle de l’appelant dans la table des adhésions, jamais de la requête.
Réinitialisation. Cette leçon ne change aucun fichier. Si votre projet ne fonctionne plus, copiez l’instantané end-of-m02 comme dans La place de MCP, avec end-of-m02 plutôt que start.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Pour chaque besoin, choisissez un outil ou une ressource, et dites qui choisit : (a) Sam veut joindre la politique de garantie complète à une conversation; (b) le modèle doit trouver quelle politique parle des doubles facturations; (c) une réponse doit citer la politique de retour pour qu'un lecteur puisse l'ouvrir plus tard.
Afficher la réponse
(a) Une ressource : policy://larkfield/warranty-policy. Sam la choisit au moyen de l’application, qui la reçoit au complet. (b) Un outil : search_knowledge. Pendant la conversation, le modèle décide de chercher de l’information et reçoit un nombre limité de correspondances. (c) Une URI de ressource : policy://larkfield/returns-policy. Elle reste la même quand le texte de la politique change. La citation fonctionne donc encore plus tard. Le résultat de recherche contient cette URI, ce qui permet au modèle de la citer.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Prédisez les réponses du serveur terminé : (a) Omar (lecture seule, Larkfield) envoie resources/list; (b) Omar lit policy://larkfield/refund-approval-procedure; (c) Sam lit policy://bramble/returns-policy, un document qui existe chez Bramble Books.
Afficher la réponse
(a) 8 ressources : tous les documents de Larkfield sauf refund-approval-procedure, réservé au personnel. (b) −32602 « Resource not found » (ressource introuvable), à la vérification 3 : le document existe, mais un membre en lecture seule ne peut pas le lire. (c) −32602 « Resource not found : policy://bramble/returns-policy » (ressource introuvable : policy://bramble/returns-policy), avec data.uri, à la vérification 2. C’est la même réponse que pour un document qui n’existe pas. Sam n’apprend donc rien sur Bramble Books.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Vérification pratique : en Python, qu'affichent contracts.policy_uri('larkfield', 'returns-policy'), contracts.POLICY_URI.match('policy://larkfield/../secrets') et len(k.documents('larkfield', staff=False))?
Afficher la réponse
'policy://larkfield/returns-policy'; rien, car le résultat est None (le format est refusé); et 8, car la liste exclut la procédure réservée au personnel pour un appelant en lecture seule.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Une ressource est un contenu à lire au complet, avec une URI. L’application ou la personne la choisit; pas le modèle.
- Une URI stable,
policy://larkfield/returns-policy, conserve l’identifiant du document quand son texte change. C’est plutôt la version qui change. - Un modèle de ressource,
policy://{tenant}/{doc_id}, décrit toute la famille.resources/listénumère les URI concrètes, selon l’appelant : 9 pour Sam, 8 pour Omar. - Avant
resources/read, le serveur vérifie le format, l’organisation et le droit de lecture de l’appelant. Chaque refus donne la même réponse : −32602 « Resource not found ». - La recherche trouve une politique avec un extrait de 300 caractères; la ressource fournit le texte complet, jusqu’à 2 846 caractères chez Larkfield.
Votre projet affiche toujours 20 passed (20 tests réussis). Ensuite, vous concevez le dernier type de capacité : une tâche que la personne lance.
Leçon suivante : Requêtes