Outils
- Leçon 4
- 55 min
- Module 2 : Concevoir des capacités de serveur utiles
Où nous en sommes
Dans le module 1, nous avons vu la place de MCP, le rôle de chaque partie d'une connexion et les versions de notre projet. Maintenant, nous concevons le serveur lui-même. Mais un outil qui en fait trop, ou qui accepte n'importe quoi, est difficile à vérifier et facile à détourner. Dans cette leçon, nous concevons des outils ciblés avec des contrats clairs avant d'écrire le code du serveur, comme le comptoir d'un bureau de poste.
Leçon 4 sur 22 · MCP : connecter les applications d'IA aux outils et aux donnéesOutils
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
Concevez les outils de support-mcp avant d’écrire le code du serveur. Chaque outil accomplit une tâche ciblée, porte un nom clair, accepte seulement des arguments bien formés et renvoie un résultat de taille limitée.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- L’hôte, le client et le serveur, et qui vérifie quoi, dans Participants et limites.
- Comment un modèle propose un appel d’outil que votre code exécute, dans Décrire un outil.
- Un modèle Pydantic et un schéma JSON Schema, dans Définir un schéma.
Votre projet
~/projects/support-mcpdu dernier module, avec l’environnement virtuel actif :python -m pytest -qaffiche13 passed(13 tests réussis).- Le dépôt des exercices dans
~/projects/nextia-learning-labs. Aucun compte et aucune clé.
Un comptoir postal
Section intitulée « Un comptoir postal »Pensez à un bureau de poste. Vous ne pouvez pas entrer dans l’arrière-boutique et prendre des colis sur les étagères. L’employé propose plutôt une courte liste de services, comme « envoyer un colis » et « récupérer un colis ».
Chaque service a un formulaire. Pour récupérer un colis, vous donnez un numéro d’avis dans un format fixe, comme P-48213. L’employé n’accepte pas « la boîte bleue, je pense » ou « tous les colis pour ma rue ».
Chaque service remet aussi quelque chose d’une taille connue. Vous recevez un colis, celui de votre avis, et non toute l’étagère. Et l’employé vérifie votre avis, même si vous l’avez rempli proprement.
Une courte liste, des formulaires fixes, des résultats connus. Voilà pourquoi un bureau de poste peut servir des inconnus sans risque toute la journée.
Le problème : « donnez simplement la base de données au modèle »
Section intitulée « Le problème : « donnez simplement la base de données au modèle » »Amira commence à planifier les actions de support-mcp. Tomás a une idée rapide. « Pourquoi pas un seul outil, run_sql(query)? Le modèle écrit n’importe quelle requête SQL. Il peut donc répondre à toutes les questions que nous aurons. »
Kwame pose sa question habituelle : « Qui fait l’appel, que peut cette personne faire, et dans quelle organisation? » L’équipe essaie ensuite l’idée sur papier, avec les données du projet. Sam, un agent de Larkfield, pose une question sur un billet de soutien. Un modèle doté de run_sql pourrait facilement écrire la requête la plus simple, SELECT * FROM tickets. Voici ce que cette requête renvoie à partir des données du projet :
- 21 billets des deux organisations, Larkfield et Bramble Books. Sam travaille seulement pour Larkfield.
- 12,540 octets de JSON à lire pour le modèle. Sam avait besoin d’un seul billet.
- Tous les champs de chaque enregistrement : le nom complet du client, son identifiant et tous les messages.
Et SQL ne se limite pas à SELECT. Le même outil accepte DELETE FROM tickets. Un billet peut contenir des mots qui tentent d’orienter le modèle, comme le montre Sécurité de l’IA, vie privée et conception responsable. Le serveur ne peut donc pas faire confiance à une requête écrite par un modèle.
L’équipe n’a jamais créé run_sql. Les nombres ci-dessus proviennent du fichier de données du projet. Malgré cela, le problème est clair : un outil qui peut tout faire donne tout à chaque personne qui l’appelle.
L’idée : des actions ciblées avec un contrat
Section intitulée « L’idée : des actions ciblées avec un contrat »Un outil est une action nommée qu’un serveur propose et que le modèle peut choisir d’appeler. L’hôte montre la description de l’outil au modèle. Le modèle propose un appel avec des arguments. L’hôte décide si l’appel s’exécute, puis le serveur l’exécute et renvoie un résultat.
Un bon outil ressemble à un service postal. Il est ciblé : il accomplit une seule tâche, dans une seule organisation. Et il a un contrat : une entente, écrite avant tout code, sur ce qui entre et ce qui sort. Le contrat d’un outil comprend quatre parties :
- Un nom qui indique ce que fait l’outil, comme
get_ticket. - Une description qui indique au modèle quand utiliser l’outil et ce que signifie le résultat.
- Un schéma d’entrée : les arguments, leurs types et leurs limites. MCP l’écrit sous forme de JSON Schema, un format JSON standard qui décrit la structure des données JSON.
- Un schéma de sortie : la structure du résultat.
Un résultat limité a un maximum fixe : un nombre fixe d’éléments et une longueur fixe de texte. Ces limites protègent le contexte du modèle, le serveur et les personnes dont les données figurent dans le résultat.
Les outils sont l’un des trois types de capacités qu’un serveur MCP peut offrir. Les trois types diffèrent selon qui choisit de les utiliser. Le modèle choisit un outil. L’application ou la personne choisit une ressource, un document à lire. La personne choisit une requête (prompt), une tâche préparée à l’avance. Ce module conçoit les trois pour support-mcp, avec une leçon pour chaque type.
Description textuelle du diagramme
Chaque ligne part d’un besoin d’une personne, et non d’une table de base de données.
| Besoin de l’utilisateur | Qui choisit | Type | Capacité | Limites |
|---|---|---|---|---|
| « Que dit notre politique sur les retours? » | le modèle | outil | search_knowledge(query, limit) |
requête de 3 à 200 caractères; au plus 5 résultats; extraits ≤ 300 caractères |
| « De quoi parle le billet T-30002? » | le modèle | outil | get_ticket(ticket_id) |
T- et 5 chiffres; un billet; prénom seulement; les 3 derniers messages |
| « Montrez-moi la politique de retour complète. » | l’application ou la personne | ressource | policy://{tenant}/{doc_id} |
un document de l’organisation de la personne qui fait l’appel |
| « Rédigez une réponse à ce billet. » | la personne | requête | draft_reply(ticket_id) |
un message utilisateur avec les étapes |
| « Remboursez 25 dollars à ce client. » (module 6) | le modèle propose, une personne approuve | outil d’écriture | propose_refund(ticket_id, amount, reason) |
montant ≤ 100,00; une proposition seulement |
Rejetés volontairement : run_sql(query), run_shell(command), get_customer(email), list_all_tickets() et un refund(ticket, amount) qui paie immédiatement.
Un petit exemple : un argument, une règle
Section intitulée « Un petit exemple : un argument, une règle »Commencez par la plus petite partie d’un contrat : un argument. L’identifiant d’un billet Larkfield comprend toujours T- et cinq chiffres, comme T-30002. Le contrat autorise donc exactement cette forme, et rien d’autre.
Le projet écrit cette règle une seule fois, dans support_mcp/contracts.py :
TicketId = Annotated[str, Field(pattern=TICKET_ID_PATTERN, description="A ticket ID, for example T-30002.")]TICKET_ID_PATTERN est l’expression régulière ^T-\d{5}$. Le texte commence (^) par T-, contient ensuite exactement cinq chiffres (\d{5}), puis se termine ($). Au module 3, la trousse SDK transforme cette ligne en schéma JSON Schema de l’outil. Vous pouvez voir ce schéma et tester la règle dès maintenant, sans serveur. Voici une vraie session Python dans le projet :
>>> from pydantic import TypeAdapter>>> from support_mcp import contracts>>> ticket_id = TypeAdapter(contracts.TicketId)>>> ticket_id.json_schema(){'description': 'A ticket ID, for example T-30002.', 'pattern': '^T-\\d{5}$', 'type': 'string'}>>> ticket_id.validate_python("T-30002")'T-30002'>>> ticket_id.validate_python("30002")pydantic_core._pydantic_core.ValidationError: 1 validation error for constrained-str String should match pattern '^T-\d{5}$' [type=string_pattern_mismatch, input_value='30002', input_type=str]>>> ticket_id.validate_python("T-30002; DROP TABLE tickets")pydantic_core._pydantic_core.ValidationError: 1 validation error for constrained-str String should match pattern '^T-\d{5}$' [type=string_pattern_mismatch, input_value='T-30002; DROP TABLE tickets', input_type=str]>>> TypeAdapter(contracts.Limit).validate_python(1000)pydantic_core._pydantic_core.ValidationError: 1 validation error for constrained-int Input should be less than or equal to 5 [type=less_than_equal, input_value=1000, input_type=int]Les lignes Traceback (trace d’erreur) avant chaque erreur et la ligne « For further information » (pour en savoir plus) après celle-ci sont omises ici. Lisez les quatre résultats :
T-30002passe, sans changement.30002échoue. Un modèle qui oublie leT-reçoit un message clair qui indique la règle.T-30002; DROP TABLE ticketséchoue aussi. Rien après les cinq chiffres ne peut atteindre le service métier.- Une demande de 1 000 résultats de recherche échoue, car le contrat en autorise au plus 5.
Le serveur terminé envoie le même message au modèle. Dans l’enregistrement du cours, un appel de get_ticket avec "30002" renvoie isError: true et « String should match pattern ‘^T-\d5$’ » (la chaîne doit respecter ce motif). Le modèle peut donc lire l’erreur et réessayer.
Un autre test montre la limite d’un schéma. ticket_id.validate_python("T-40003") renvoie 'T-40003', car la forme est correcte. Mais T-40003 est un billet de Bramble Books. Un schéma vérifie la forme d’un argument, jamais l’autorisation. Cette vérification reste dans le serveur et le service métier. Sur une connexion Larkfield, le serveur terminé répond « not_found : there is no ticket T-40003 in this organization » (introuvable : aucun billet T-40003 dans cette organisation).
Ce que reçoit le client
Section intitulée « Ce que reçoit le client »Au module 3, la trousse SDK transforme le contrat en entrée de l’outil dans la réponse à tools/list. Voici cette entrée pour get_ticket, tirée de l’enregistrement du serveur terminé dans le cours :
Description textuelle du diagramme
- name (nom)
get_ticket: le modèle le nomme dans un appel. L’hôte vérifie qu’il a été découvert avant de l’envoyer. - description : « Obtenir un billet de soutien de cette organisation par son identifiant (par exemple T-30002) : le prénom du client, le sujet, le texte, le statut et les 3 derniers messages. Le texte contient les mots du client. » Le modèle la lit. Il décide quand appeler l’outil et ce que signifie le résultat.
- inputSchema (schéma d’entrée) :
ticket_id, une chaîne obligatoire avec le motif^T-\d{5}$. Le modèle la remplit, et le serveur la vérifie de nouveau à chaque appel. - outputSchema (schéma de sortie) : 9 champs, et
last_messagescontient au plus 3 éléments. L’hôte et les tests peuvent vérifier chaque résultat à l’aide de ce schéma. - annotations :
readOnlyHint: true,destructiveHint: false,idempotentHint: true,openWorldHint: false. Ce sont des indications pour l’écran de l’hôte, pas un contrôle : rien ne vérifie qu’elles sont vraies.
La dernière partie demande un avertissement. Les annotations sont des étiquettes qu’un serveur place sur ses propres outils : « je lis seulement », « je ne change rien », « un deuxième appel a le même effet ». Tomás les aime : « L’annotation dit lecture seule, donc l’outil est sûr. » Mais un serveur écrit ses propres annotations. Un serveur défectueux ou hostile peut étiqueter un outil de suppression readOnlyHint: true, et rien dans le protocole ne le vérifie. Un hôte peut utiliser les annotations pour choisir une icône ou une question à poser à la personne, sans plus. Le module 6 montre ce qui protège réellement une écriture.
Les deux outils en lecture seule de Larkfield
Section intitulée « Les deux outils en lecture seule de Larkfield »Voici maintenant la conception complète. Amira écrit toutes les limites en haut de contracts.py, pour regrouper les nombres au même endroit :
# Bounds. A tool that can return "everything" is a tool that can flood a model's context.MAX_QUERY_CHARS = 200MAX_RESULTS = 5DEFAULT_RESULTS = 3MAX_SNIPPET_CHARS = 300MAX_TICKET_TEXT_CHARS = 1500MAX_MESSAGES = 3TICKET_ID_PATTERN = r"^T-\d{5}$"Le premier outil est search_knowledge(query, limit). Il répond à « que dit notre politique à ce sujet? ». La requête contient de 3 à 200 caractères, et limit va de 1 à 5, avec 3 par défaut. Chaque résultat contient le titre du document, un extrait d’au plus 300 caractères et l’URI du document. L’URI est l’adresse du texte complet, que la prochaine leçon transforme en ressource.
Le deuxième outil est get_ticket(ticket_id). Il répond à « de quoi parle ce billet? ». Il prend un identifiant de billet dans la forme ci-dessus et renvoie un billet. Sa sortie conserve seulement le prénom du client : une réponse demande « Bonjour Hugo », pas le nom complet et l’identifiant du client. La conception limite le texte du billet à 1 500 caractères et renvoie seulement les 3 derniers messages.
Les modèles de sortie sont des classes Pydantic ordinaires. SearchResult refuse une liste de plus de 5 résultats, et Ticket refuse plus de 3 messages. Une fonction utilitaire, clip, raccourcit un texte long et ajoute …, pour que le lecteur voie qu’une partie a été coupée.
Quelle quantité de données chaque conception transmet-elle au modèle? L’équipe a mesuré le texte JSON de chaque conception de la même manière, à partir des données du projet :
- conception rejetée
- outil limité
Description textuelle du graphique
Un graphique à quatre colonnes. Les deux conceptions rejetées : run_sql avec SELECT * FROM tickets renvoie 12,540 octets (les 21 billets des deux organisations), et list_all_tickets renvoie 7,845 octets (les 13 billets de Larkfield). Les deux outils limités : search_knowledge pour « charged twice refund » renvoie 935 octets (3 résultats), et get_ticket pour T-30002 renvoie 506 octets (un billet).
Les données de Larkfield sont volontairement peu nombreuses : 13 billets. Dans un vrai magasin avec 50 000 billets, les deux conceptions rejetées grossissent à chaque nouveau billet. Les deux outils limités ne grossissent pas, car leur maximum figure dans le contrat.
Trois autres choix rendent les outils faciles à utiliser pour un modèle :
- Le nom indique l’action.
get_ticketetsearch_knowledgecomprennent un verbe et une chose. Des noms commeticket,query_dbouhelperobligent le modèle à deviner. - La description indique quand agir et ce qui revient. « Utilisez-le avant de répondre à une question sur une politique » indique au modèle quand agir. « Le texte contient les mots du client » avertit que le résultat contient des données provenant d’un inconnu.
- Aucun outil n’accepte une organisation. Le serveur apprend l’organisation à partir de la connexion, au module 3. Un modèle, ou un billet qui l’oriente, ne peut donc même pas demander les données de l’autre magasin.
Ajouter les contrats au projet
Section intitulée « Ajouter les contrats au projet »-
Copiez le fichier de contrat de ce module et ses tests depuis l’instantané
end-of-m02:Fenêtre de terminal S=../nextia-learning-labs/C28/snapshots/end-of-m02cp "$S/support_mcp/contracts.py" support_mcp/cp "$S/tests/test_contracts.py" tests/Fenêtre de terminal $S = "..\nextia-learning-labs\C28\snapshots\end-of-m02"Copy-Item "$S\support_mcp\contracts.py" support_mcp\Copy-Item "$S\tests\test_contracts.py" tests\Le fichier comprend trois parties. Cette leçon utilise la partie des outils. Les deux prochaines leçons lisent la partie des ressources et celle des requêtes.
-
Ouvrez
support_mcp/contracts.pydans VS Code. TrouvezMAX_RESULTS,TicketIdet la classeTicket. -
Exécutez les tests de contrat :
Fenêtre de terminal python -m pytest -q tests/test_contracts.pyLa dernière ligne est
7 passed(7 tests réussis). Aucun serveur ne s’exécute : les tests vérifient seulement le contrat. -
Exécutez tous les tests :
Fenêtre de terminal python -m pytest -qLa dernière ligne est
20 passed(20 tests réussis) : les 13 tests du module 1 et 7 nouveaux tests. -
Lancez Python avec
python, puis tapez les lignes de la session ci-dessus. Vous obtenez les mêmes résultats; seuls les chemins de fichiers dans les lignesTracebackdiffèrent. Quittez Python avecexit().
Les noms des tests se lisent comme le contrat : test_a_query_is_bounded, test_the_number_of_results_is_bounded, test_a_ticket_id_has_one_form et test_a_search_result_holds_at_most_five_hits. Si quelqu’un augmente la limite de résultats par erreur, test_the_number_of_results_is_bounded échoue avant qu’un modèle voie le changement.
Quand créer un outil, et ce qu’il coûte
Section intitulée « Quand créer un outil, et ce qu’il coûte »Créez un outil quand le modèle doit décider, pendant une conversation, qu’il doit chercher une information. « Quelle politique s’applique à ce billet? » est une décision de ce type.
Ne créez pas un outil pour tout :
- Un contenu à lire au complet, comme la politique de retour complète, convient mieux à une ressource. L’application peut l’afficher et le joindre. C’est le sujet de la prochaine leçon.
- Une tâche que la personne lance, comme « rédiger une réponse », convient à une requête (prompt). C’est le sujet de la leçon suivante.
- Une action qui a un effet, comme un remboursement, exige l’approbation d’une personne. Le module 6 l’ajoute comme proposition, après la réussite des tests d’autorisation.
- Tout ce qui est sans restriction, comme
run_sqlourun_shell, ne devient jamais un outil. Si un besoin semble l’exiger, divisez-le en outils à portée limitée.
Les outils à portée limitée ont aussi des coûts :
- Plus de code à écrire et à tester. Deux outils à portée limitée exigent plus de code qu’un seul
run_sql. C’est ce code qui assure la sécurité. - Du contexte à chaque requête. Un hôte envoie le nom, la description et les schémas de chaque outil à son modèle. La réponse
tools/listenregistrée du serveur terminé, avec trois outils, fait 4 460 octets. Vingt outils encombreraient le contexte du modèle et rendraient chaque choix plus difficile. - Des questions sans outil adapté. « Combien de billets Bramble Books a-t-elle reçus cette semaine? » n’a aucun outil. C’est normal pour un assistant de soutien. Si le besoin devient réel, concevez un nouvel outil à portée limitée pour y répondre.
Erreurs courantes
Section intitulée « Erreurs courantes »Erreur courante
cannot import name 'contracts' from 'support_mcp' (impossible d'importer le nom 'contracts' depuis 'support_mcp')
Symptôme : python -m pytest -q s’arrête avant d’exécuter un seul test :
E ImportError: cannot import name 'contracts' from 'support_mcp' (…/support-mcp/support_mcp/__init__.py)=========================== short test summary info ============================ERROR tests/test_contracts.py!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!1 error in 0.06sCause : vous avez copié tests/test_contracts.py, mais pas support_mcp/contracts.py, ou le fichier se trouve dans le mauvais dossier.
Solution : copiez contracts.py dans le dossier support_mcp, à côté de knowledge.py, comme à l’étape 1.
Erreur courante
Un résultat qui ne respecte pas son propre contrat
Symptôme : le code qui construit un SearchResult avec six correspondances s’arrête avec ce message :
pydantic_core._pydantic_core.ValidationError: 1 validation error for SearchResultresults List should have at most 5 items after validation, not 6 [type=too_long, input_value=[{'doc_id': 'd', 'title':...et': 's', 'score': 1.0}], input_type=list]Cause : le code a demandé au service métier plus de correspondances que le contrat le permet.
Solution : gardez la limite et modifiez le code : demandez au plus MAX_RESULTS correspondances. N’augmentez pas la limite pour faire disparaître l’erreur. Cette erreur montre que le contrat fait son travail.
Réinitialisation. Cette leçon ajoute deux fichiers et ne modifie aucune donnée. Pour annuler ces ajouts, supprimez support_mcp/contracts.py et tests/test_contracts.py. Si votre projet ne fonctionne plus, copiez l’instantané end-of-m01 comme dans La place de MCP, avec end-of-m01 plutôt que start. Reprenez ensuite les étapes de cette leçon.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Tomás propose un seul outil, run_sql(query), « parce qu'il peut répondre à toutes les questions ». Donnez trois raisons de le refuser, avec des chiffres ou des faits de cette leçon.
Afficher la réponse
D’abord, il franchit les limites entre organisations : SELECT * FROM tickets renvoie les 21 billets à un agent de Larkfield. Ces billets appartiennent à Larkfield et à Bramble Books. Ensuite, il n’a aucune limite : cette réponse fait 12 540 octets et grossit avec chaque nouveau billet. À l’inverse, get_ticket renvoie un seul billet d’environ 500 octets. Enfin, il donne plus de données et de pouvoir que nécessaire : noms complets, identifiants des clients et tous les messages. SQL accepte aussi DELETE. Personne ne peut faire confiance à une requête du modèle; le serveur devrait donc examiner chaque requête. Les outils à portée limitée assurent cette protection par leur conception.
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 : lesquels de ces identifiants de billet respectent le contrat TicketId : 'T-30002', 't-30002', 'T-300021', 'T-40003'? Pour ceux qui le respectent, cela signifie-t-il que l'appelant peut lire le billet?
Afficher la réponse
T-30002 et T-40003 respectent le contrat. t-30002 échoue, car le motif exige un T majuscule. T-300021 échoue, car le motif exige exactement cinq chiffres, puis la fin. Respecter le contrat signifie seulement que la forme est correcte. T-40003 est un billet de Bramble Books. Sur une connexion Larkfield, le serveur répond donc « not_found : there is no ticket T-40003 in this organization » (introuvable : cette organisation n’a aucun billet T-40003). Le schéma vérifie la forme, et le serveur vérifie l’autorisation.
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 : exécutez python -m pytest -q tests/test_contracts.py, puis python -m pytest -q. Que disent les dernières lignes? Ensuite, dans Python, que répond TypeAdapter(contracts.Query).validate_python('ab'), et pourquoi?
Afficher la réponse
7 passed (7 tests réussis), puis 20 passed (20 tests réussis). La requête 'ab' échoue avec « String should have at least 3 characters » (la chaîne doit contenir au moins 3 caractères), car Query impose min_length=3. Une recherche de deux lettres correspondrait à presque tous les documents. Le contrat la refuse donc avant toute recherche.
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
- Un outil est une action nommée que le modèle peut choisir d’appeler. L’hôte décide si l’appel s’exécute, et le serveur vérifie chaque appel.
- Un bon outil a une portée limitée : une tâche, une organisation. Son contrat comprend un nom, une description, un schéma d’entrée et un schéma de sortie.
- Les limites font partie du contrat : 3–200 caractères, au plus 5 correspondances, extraits de 300 caractères, prénom seulement, 3 messages.
- Un schéma vérifie la forme d’un argument, jamais l’autorisation.
T-40003a la bonne forme, mais une connexion Larkfield ne peut toujours pas le lire. - Les annotations sont les indications du serveur lui-même, pas un mécanisme de contrôle.
Votre projet contient maintenant support_mcp/contracts.py et ses tests, et python -m pytest -q affiche 20 passed. Ensuite, vous donnerez des adresses stables aux documents de politique, pour qu’une application puisse les lire au complet.
Leçon suivante : Ressources