Aller au contenu
English

Examiner le comportement

  • Leçon 10
  • 50 min
  • Module 3 : Créer et examiner un serveur local

Où nous en sommes

Dans les deux leçons précédentes, nous avons lu des messages à la main et exécuté support-mcp comme processus local. Mais nos propres tests montrent seulement ce que nous avons pensé à vérifier. Dans cette leçon, nous examinons le serveur comme toute autre application le voit, avec MCP Inspector, et nous démontrons un appel valide et une défaillance contrôlée. Nous commençons par un lecteur de diagnostic au garage.

Ce que vous saurez faire

Examinez le serveur comme toute autre application le verrait. Vous utilisez MCP Inspector, l’outil de développement du projet MCP, pour découvrir les capacités du serveur. Vous appelez un outil avec des entrées valides et invalides, puis lisez chaque résultat et chaque erreur. Vous démontrez ensuite le résultat attendu du module : la découverte, un appel valide et une défaillance contrôlée.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 50 minutes

Ce que vous devez savoir

  • La différence entre une erreur de protocole et une erreur d’outil, présentée dans Les messages JSON-RPC.
  • Comment un hôte démarre un serveur stdio, présenté dans Transport local.

Votre projet

  • ~/projects/support-mcp avec le serveur de la dernière leçon : python -m pytest -q affiche 40 passed (40 tests réussis).
  • Node.js 22,19 ou une version ultérieure, seulement pour Inspector. Vérifiez avec node --version; le cours utilisait la version 24.18.0. Si vous ne l’avez pas, installez la version LTS depuis nodejs.org.
  • Une connexion Internet la première fois : npx télécharge Inspector, soit environ 97 Mo. Aucun compte ni aucune clé.

Quand un voyant d’avertissement s’allume dans une voiture, un mécanicien branche un petit lecteur dans un port standard sous le tableau de bord. Le lecteur ne conduit pas la voiture. Il demande l’état de chaque composant, affiche les réponses brutes et peut envoyer une commande de test : « allumer le ventilateur ».

Le lecteur est utile parce qu’il n’est pas le tableau de bord de la voiture. Le tableau de bord affiche ce que ses concepteurs ont choisi de montrer. Le lecteur montre ce que la voiture dit vraiment, dans le format standard que tous les garages comprennent.

Le problème : les tests réussissent, mais que voient les autres applications?

Section intitulée « Le problème : les tests réussissent, mais que voient les autres applications? »

Vos 40 tests réussissent. Ils testent le serveur avec le client de la trousse SDK, écrit par les développeurs du serveur eux-mêmes. Un autre hôte, comme l’application d’un partenaire, possède son propre client. Il lit les mêmes messages, mais les affiche à sa façon et transmet le texte à son propre modèle.

L’équipe du cours en a trouvé un exemple réel. Dans la première version de support-mcp, la chaîne de documentation de chaque outil comptait deux lignes. Les tests réussissaient. Puis l’équipe a dressé la liste des outils avec Inspector et a vu cette description :

"description": "Search this organization's policy documents. Returns at most 5 short matches, best first,\n each with the URI of the full policy. Use it before you answer a policy question."

Le saut de ligne et les huit espaces d’indentation de la chaîne de documentation parvenaient à chaque client, donc à chaque modèle. Rien n’échouait, mais le texte lu par un modèle ne correspondait pas à l’intention d’Amira. Aucun test ne le vérifiait, car aucun ne lisait la description telle qu’un client l’affiche. L’équipe a réduit chaque chaîne de documentation à une ligne. Votre serveur contient le texte corrigé.

MCP Inspector est un outil de développement du projet MCP. C’est un hôte avec un client MCP, mais sans modèle ni opinion. Il se connecte à un serveur et dresse la liste de ce que le serveur offre. Vous pouvez appeler chaque outil, lire chaque ressource et remplir chaque requête à la main; il affiche tous les messages. Ce cours utilise Inspector 2.10.1, qui nécessite Node.js. Vous le démarrez avec npx, qui télécharge et exécute un paquet Node.js.

Inspector propose deux modes de fonctionnement :

  • L’interface Web exécute un petit serveur Web sur votre ordinateur et ouvre une page dans votre navigateur. Vous explorez les outils, les ressources et les requêtes du serveur en cliquant. Utilisez-la pour explorer.
  • La CLI (interface en ligne de commande) envoie une requête, affiche le résultat en JSON et se termine avec un code. Utilisez-la pour les vérifications répétées et dans les scripts.
Deux panneaux en haut. Interface Web : npx @modelcontextprotocol/inspector@2.10.1. Votre navigateur, à l'adresse http://127.0.0.1:6274 avec un jeton dans l'adresse, communique avec le serveur Web local d'Inspector (Node.js), qui contient le client MCP. Notes : vous cliquez sur Connect (connecter), Tools (outils), un outil, puis Execute Tool (exécuter l'outil); le panneau Messages liste chaque requête; utilisez-le pour explorer et voir ce qu'un modèle verrait : noms, descriptions, schémas, annotations. CLI : inspector@2.10.1 --cli. Une commande correspond à une requête; elle affiche le résultat en JSON, puis se termine; code de sortie 0 : OK, 5 : erreur d'outil, 1 : erreur. Notes : utilisez-la dans les scripts et les vérifications; la cible d'abord, puis -- et les options d'Inspector. Les deux panneaux démarrent python -m support_mcp comme processus enfant sur stdio : le même serveur, les mêmes messages. Une note ambrée en bas : ère legacy (ancienne) par défaut, initialize avec la révision 2025-11-25; ajoutez --protocol-era modern pour la révision 2026-07-28, server/discover et _meta; le serveur répond aux deux, donc testez les deux.
Inspector 2.10.1 dans ses deux modes. Les deux démarrent le serveur comme processus enfant sur stdio, comme tout hôte.
Description textuelle du diagramme

Interface Web (npx @modelcontextprotocol/inspector@2.10.1) : votre navigateur ouvre http://127.0.0.1:6274, avec un jeton dans l’adresse. Il communique avec le serveur Web local d’Inspector, qui contient le client MCP. Vous cliquez sur Connect (connecter), Tools (outils), un outil, puis Execute Tool (exécuter l’outil). Le panneau Messages liste chaque requête. Vous voyez ce qu’un modèle pourrait voir : noms, descriptions, schémas et annotations.

CLI (… --cli) : une commande correspond à une requête. Elle affiche le résultat en JSON et se termine avec le code 0 (OK), 5 (erreur d’outil) ou 1 (erreur). Écrivez d’abord la cible, puis --, puis les options d’Inspector.

Les deux démarrent python -m support_mcp comme processus enfant sur stdio. Ils voient donc le même serveur et les mêmes messages que tout hôte.

L’ère du protocole : par défaut, Inspector 2.10.1 utilise l’ère ancienne : initialize (initialiser) avec la révision 2025-11-25. Ajoutez --protocol-era modern pour utiliser la révision 2026-07-28, avec server/discover et _meta. Le serveur répond aux deux, donc testez les deux.

La dernière case de l’image présente une découverte réelle de ce cours. Inspector 2.10.1 démarre dans l’ère ancienne par défaut. L’équipe du cours a placé un enregistreur entre Inspector et le serveur, et le premier message était :

{"method": "initialize", "params": {"protocolVersion": "2025-11-25", "capabilities": {…}, "clientInfo": {"name": "inspector-cli", …}}, "jsonrpc": "2.0", "id": 0}

Avec --protocol-era modern, le premier message est devenu server/discover, avec _meta pour 2026-07-28. C’est important lorsque vous notez ce que vous avez testé. « Inspector fonctionne » est vrai pour les deux ères, mais vous devriez préciser celle que vous avez utilisée.

Un petit exemple : lister les outils en ligne de commande

Section intitulée « Un petit exemple : lister les outils en ligne de commande »

Commencez par une commande, depuis le dossier du projet, avec l’environnement virtuel actif. Inspector démarre le serveur avec la commande après --cli; python doit donc être le Python de l’environnement.

Fenêtre de terminal
npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method tools/list

La première fois, npx demande l’autorisation d’installer le paquet : tapez y (oui) et appuyez sur Entrée. La sortie est la réponse à tools/list, en JSON. Voici son début :

{
"tools": [
{
"name": "search_knowledge",
"description": "Search this organization's policy documents. Returns at most 5 short matches, best first, each with the URI of the full policy. Use it before you answer a policy question.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"description": "Words to look for in the organization's policy documents.",
"maxLength": 200,
"minLength": 3,
…

La description tient maintenant sur une ligne. En dessous, vous trouvez le deuxième outil, get_ticket, avec son motif ^T-\d{5}$. Pour chaque outil, vous trouvez aussi ses annotations (readOnlyHint: true) et son outputSchema (schéma de sortie). C’est tout ce qu’un hôte reçoit. Chaque hôte choisit les éléments qu’il transmet à son modèle. L’hôte du cours, au module 4, transmet le nom, la description et le schéma d’entrée.

Larkfield : examiner le serveur dans l’interface Web

Section intitulée « Larkfield : examiner le serveur dans l’interface Web »
  1. Démarrez l’interface Web d’Inspector avec le serveur, dans l’ère moderne :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --protocol-era modern python -m support_mcp

    Le terminal affiche l’adresse, avec un jeton :

    MCP Inspector Web is up and running at:
    http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=…

    Votre navigateur ouvre cette page. Le jeton protège la page pour qu’un autre programme sur votre ordinateur ne puisse pas l’utiliser. Gardez ce terminal ouvert.

  2. Sur la carte du serveur, cliquez sur l’interrupteur à côté de Disconnected (déconnecté). Il devient Connected (connecté), et la carte affiche MCP 2026-07-28.

    La page Servers (serveurs) de MCP Inspector. La carte nommée python affiche Connected (connecté), STDIO Standard I/O (entrées-sorties standard), MCP 2026-07-28 et la commande python -m support_mcp. À droite, le panneau Messages porte l'étiquette MODERN (moderne) et liste les requêtes du client au serveur : resources/templates/list, prompts/list, tools/list et resources/list. Chacune porte la mention COMPLETE (terminée). Il affiche aussi une notification concernant un abonnement.
    Connexion dans l'ère moderne : révision 2026-07-28. Le panneau Messages liste les requêtes de découverte envoyées par Inspector. L’image est en anglais.

    À droite, le panneau Messages liste ce qu’Inspector a envoyé : server/discover, tools/list, resources/list, resources/templates/list et prompts/list. C’est la découverte présentée dans Les messages JSON-RPC, effectuée par un autre client. Inspector envoie aussi subscriptions/listen, une requête pour recevoir les changements, que scripts/trace.py n’envoie pas.

  3. Cliquez sur Tools (outils) en haut, puis sur get_ticket.

    La page Tools (outils). À gauche, les outils search_knowledge et get_ticket; get_ticket est sélectionné. Au centre, get_ticket avec deux étiquettes, READ-ONLY (lecture seule) et IDEMPOTENT (idempotent), et la 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, l'état et les 3 derniers messages. Le texte contient les mots du client. En dessous, un formulaire avec un champ obligatoire, Ticket Id (identifiant du billet), et l'indication : un identifiant de billet, par exemple T-30002. Le champ contient 30002, et le bouton Execute Tool (exécuter l'outil) est actif.
    Inspector construit un formulaire à partir du schéma d'entrée de l'outil. Les étiquettes viennent des annotations de l'outil, et l'indication vient de la description du schéma. L’image est en anglais.

    La page montre ce qu’un modèle pourrait recevoir : le nom, la description et un champ obligatoire du schéma d’entrée. Les étiquettes READ-ONLY (lecture seule) et IDEMPOTENT (idempotent) viennent des annotations.

  4. Tapez T-30002 dans Ticket Id (identifiant du billet), puis cliquez sur Execute Tool (exécuter l’outil).

    Le panneau Results (résultats) de get_ticket. Le résultat textuel est en JSON : ticket_id T-30002, customer_name Hugo, subject : double facturation pour la commande LK-182074, body : ma carte a été débitée deux fois pour la commande LK-182074, de 449,00 dollars chaque fois. Veuillez rembourser l'un des paiements., team billing (facturation), priority 1, status open (ouvert), created_at 2026-09-25 08:20:19+00, et last_messages avec un message de l'agent. En dessous, Structured Output (sortie structurée) montre le même objet. Le panneau Messages montre une nouvelle requête tools/call get_ticket, marquée COMPLETE (terminée).
    Un appel valide : le résultat contient le billet deux fois, comme texte pour les anciens clients et comme sortie structurée conforme au schéma de sortie. L’image est en anglais.

    Le résultat contient le billet deux fois : comme texte, que chaque client peut afficher, et comme Structured Output (sortie structurée), conforme au schéma de sortie. Le prénom d’Hugo s’y trouve, mais pas son adresse courriel : le contrat du module 2 l’excluait.

  5. Fermez les résultats avec le × à côté de Results (résultats). Tapez 30002, sans T-, puis cliquez de nouveau sur Execute Tool.

    Le panneau Results (résultats) montre une case rouge intitulée Tool Error (erreur d'outil) : erreur lors de l'exécution de l'outil get_ticket : 1 erreur de validation pour get_ticketArguments ticket_id. La chaîne doit correspondre au motif '^T-\d{5}$' [type=string_pattern_mismatch, input_value='30002', input_type=str]. Le panneau Messages montre une deuxième requête tools/call get_ticket, marquée COMPLETE (terminée).
    Une défaillance de validation contrôlée : le serveur a refusé 30002 parce qu'il ne correspond pas au motif. Inspector l'affiche comme Tool Error (erreur d'outil). L’image est en anglais.

    Inspector a envoyé la requête : il n’a pas vérifié le motif lui-même. Le schéma du serveur l’a refusée. La réponse est une erreur d’outil, un result (résultat) avec isError: true. Le panneau Messages affiche donc la requête comme terminée. Un modèle lirait ce texte et pourrait réessayer avec T-30002.

  6. Cliquez sur Resources (ressources). La liste montre 9 URI, dont Manual refunds and goodwill credits (remboursements manuels et crédits de courtoisie), un document réservé au personnel : Sam en fait partie. Cliquez sur une ressource pour la lire.

  7. Pour arrêter Inspector, revenez au terminal et appuyez sur Ctrl+C. Cela arrête le serveur Web et le processus enfant.

Essayez encore une chose par vous-même : arrêtez Inspector, puis redémarrez-le sans --protocol-era modern. La carte du serveur affiche alors MCP 2025-11-25. Le panneau Messages affiche LEGACY (ancienne) et une requête initialize :

La page Servers (serveurs) dans l'ère par défaut. La carte affiche Connected (connecté) et MCP 2025-11-25. Le panneau Messages porte l'étiquette LEGACY (ancienne) et liste resources/templates/list, prompts/list, tools/list, resources/list, notifications/initialized et initialize.
Le mode par défaut d'Inspector : l'ère ancienne, avec la négociation initialize. Le même serveur y répond. L’image est en anglais.

L’interface Web sert à explorer. Pour les vérifications répétées, utilisez la CLI. La même requête donne la même sortie, et le code de sortie indique ce qui s’est passé. Exécutez ces commandes depuis le dossier du projet. Le cours n’a pas testé ces commandes dans PowerShell, qui traite différemment les guillemets de 'ticket_id="30002"'.

  1. Un appel valide :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method tools/call --tool-name get_ticket --tool-arg ticket_id=T-30002

    La sortie est le résultat en JSON, avec "isError": false à la fin. Le code de sortie est 0 : vérifiez-le avec echo $? (PowerShell : $LASTEXITCODE).

  2. Le même appel avec ticket_id=30002 :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method tools/call --tool-name get_ticket --tool-arg ticket_id=30002
    "text": "Error executing tool get_ticket: 1 validation error for get_ticketArguments\nticket_id\n Input should be a valid string [type=string_type, input_value=30002, input_type=int]\n …"
    …
    "isError": true

    Sur la sortie d’erreur standard : {"error":{"code":"tool_is_error","message":"Tool 'get_ticket' returned isError:true."}}, et le code de sortie est 5. Lisez attentivement le message : « L’entrée doit être une chaîne valide », input_type=int. La CLI a transformé 30002 en nombre 30 002, parce qu’il ressemble à un nombre. L’interface Web a envoyé une chaîne. Même entrée, deux messages différents.

  3. Envoyez explicitement la chaîne, avec des guillemets JSON dans l’argument :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method tools/call --tool-name get_ticket --tool-arg 'ticket_id="30002"'

    Le message est maintenant celui de l’interface Web, String should match pattern '^T-\d{5}$' (la chaîne doit correspondre au motif), avec input_value='30002', input_type=str. Code de sortie : 5.

  4. Lisez la politique d’une autre organisation :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method resources/read --uri policy://bramble/returns-policy
    {"error":{"code":"error","message":"Resource not found: policy://bramble/returns-policy"}}

    Code de sortie : 1, une erreur de protocole, pas une erreur d’outil. La CLI n’affiche pas le code JSON-RPC. Vous l’avez vu dans l’enregistrement de Les messages JSON-RPC : −32602, avec l’URI dans data (données).

  5. Remplissez la requête :

    Fenêtre de terminal
    npx @modelcontextprotocol/inspector@2.10.1 --cli python -m support_mcp -- --protocol-era modern --method prompts/get --prompt-name draft_reply --prompt-args ticket_id=T-30002

    La sortie contient un message utilisateur qui commence par Draft a reply to support ticket T-30002 for larkfield. (rédigez une réponse au billet de soutien T-30002 pour larkfield). L’organisation vient de l’environnement du serveur, pas des arguments.

Vous avez maintenant vu tous les types de défaillances que ce serveur envoie. L’image les classe selon les deux formes présentées dans Les messages JSON-RPC :

Deux panneaux. À gauche, en rouge : erreur de protocole, error (erreur) plutôt que result (résultat); la requête elle-même a échoué; le client et le code de l'hôte la traitent; le modèle ne la voit généralement jamais. Quatre exemples : -32601 Method not found (méthode introuvable), tools/delete; -32602 Invalid params (paramètres invalides), sans _meta, ou la ressource policy://bramble/… sur Larkfield; -32003 forbidden (interdit) ou insufficient_scope (portée insuffisante), code propre à ce serveur, sans adhésion ou sans portée; -32022 Unsupported protocol version (version de protocole non prise en charge), server/discover avec 2099-01-01. À droite, en ambre : erreur d'outil, un result avec isError true; l'outil a été appelé et a refusé l'appel; le texte retourne au modèle, qui peut le lire et réessayer. Trois exemples : validation, get_ticket avec 30002, String should match pattern (la chaîne doit correspondre au motif); not_found (introuvable), get_ticket T-40003 sur Larkfield, aucun billet dans cette organisation; unknown tool (outil inconnu), delete_ticket, Unknown tool, que la trousse SDK 2.3.0 envoie même si la spécification demande -32602. Une note : code de sortie de la CLI d'Inspector : 5 pour une erreur d'outil, 1 pour une erreur de protocole.
Toutes les défaillances de support-mcp dans ce module, classées par forme. La forme détermine qui réagit : le code de l'hôte ou le modèle.
Description textuelle du diagramme

Erreur de protocole : error (erreur) plutôt que result. La requête elle-même a échoué. Le client et le code de l’hôte la traitent; le modèle ne la voit généralement jamais.

  • −32601 Method not found (méthode introuvable) : tools/delete.
  • −32602 Invalid params (paramètres invalides) : sans _meta, ou la ressource policy://bramble/… sur une connexion Larkfield.
  • −32003 forbidden (interdit) ou insufficient_scope (portée insuffisante) : code propre à ce serveur, sans adhésion ou sans portée.
  • −32022 Unsupported protocol version (version de protocole non prise en charge) : server/discover avec 2099-01-01.

Erreur d’outil : un result avec isError: true. L’outil a été appelé et a refusé l’appel. Le texte retourne au modèle, qui peut le lire et réessayer.

  • validation : get_ticket avec « 30002 » : « La chaîne doit correspondre au motif ».
  • not_found (introuvable) : get_ticket T-40003 sur Larkfield : aucun billet dans cette organisation.
  • unknown tool (outil inconnu) : delete_ticket : « Outil inconnu ». La trousse SDK 2.3.0 envoie une erreur d’outil; la spécification demande −32602.

La CLI d’Inspector se termine avec le code 5 pour une erreur d’outil et le code 1 pour une erreur de protocole.

L’équipe garde une courte liste des constats de l’inspection, car chaque élément deviendra une vérification plus tard :

  • Les descriptions sont du contenu. Un modèle les lit. La première exécution a montré le retrait de la chaîne de documentation. La solution était d’utiliser des chaînes de documentation sur une seule ligne. Dans le module 7, un test de contrat compare les descriptions à un fichier. Ainsi, une modification ne pourra plus passer inaperçue.
  • Les clients envoient des types différents. La CLI a envoyé 30002 comme nombre, et l’interface web comme chaîne. Le serveur doit vérifier lui-même chaque entrée, et il le fait : son schéma a refusé les deux.
  • L’ère fait partie du résultat. Inspector utilise l’ère ancienne par défaut. Une note de compatibilité indique « Inspector 2.10.1, les deux ères », et pas seulement « Inspector ».
  • Les erreurs d’outil semblent être des réussites pour le protocole. Le panneau Messages (messages) marque l’appel échoué comme terminé. Seul isError: true indique que l’outil a refusé l’appel.

Utilisez Inspector chaque fois que vous changez ce qu’un client voit : nouvel outil, nouvelle description, nouveau message d’erreur. Utilisez-le avant de connecter un véritable hôte, pour vérifier que le serveur fonctionne correctement. Utilisez la CLI dans les scripts, car les codes de sortie facilitent les vérifications rapides.

Il a aussi des limites et des coûts :

  • Il nécessite Node.js, dont un projet Python n’a autrement pas besoin, et environ 97 Mo pour le paquet.
  • C’est un outil de développement, pas une suite de tests. Il montre ce qui se passe aujourd’hui. Transformez chaque constat en test pour que le problème reste corrigé.
  • Il lance un serveur web local avec un jeton. Il écoute uniquement sur 127.0.0.1. Ne partagez pas l’adresse avec son jeton, et arrêtez Inspector quand vous avez terminé.
  • Il stocke des secrets. Pour un serveur qui nécessite un jeton, Inspector le conserve par défaut dans le trousseau de votre système. Ce serveur n’en nécessite aucun. Pour garder les secrets uniquement en mémoire, définissez MCP_INSPECTOR_SECRET_STORE=memory avant de le démarrer. Le cours l’a fait à chaque exécution.
  • Ce n’est pas votre hôte. Il montre ce que le serveur envoie, pas ce qu’une application d’IA donnée en fait. Le module 4 construit cette application.

Erreur courante

No servers found in config file (aucun serveur trouvé dans le fichier de configuration)

Symptôme : la CLI affiche {"error":{"code":"error","message":"No servers found in config file"}} et ne fait rien.

Cause : les options précédaient la commande du serveur, dans l’ordre utilisé par la version 1 d’Inspector. La version 2 exige la cible en premier. La commande qui échouait était … --cli --format json python -m support_mcp --method tools/list

Solution : écrivez d’abord la commande du serveur, puis --, puis les options d’Inspector : … --cli python -m support_mcp -- --method tools/list. Le -- est nécessaire ici, car la commande du serveur a sa propre option, -m. Il indique à Inspector où cette commande se termine.

Erreur courante

Input should be a valid string (l'entrée doit être une chaîne valide)

Symptôme : un appel CLI avec --tool-arg ticket_id=30002 échoue avec Input should be a valid string [type=string_type, input_value=30002, input_type=int], et le code de sortie 5.

Cause : la CLI lit les valeurs qui ressemblent à des nombres comme des nombres. Le serveur attendait une chaîne, donc son schéma a refusé l’appel.

Solution : pour tester le motif, envoyez une chaîne avec des guillemets JSON : --tool-arg 'ticket_id="30002"'. Pour faire un appel valide, utilisez le véritable identifiant : ticket_id=T-30002.

Exercice du module : créer et examiner un petit serveur

Section intitulée « Exercice du module : créer et examiner un petit serveur »

Exemple guidé. L’exemple détaillé de ce module est votre propre projet. Vous avez choisi la trousse SDK et créé un environnement testé. Ensuite, vous avez lu et envoyé des messages JSON-RPC à la main. Vous avez exécuté support-mcp sur stdio, avec scripts/trace.py comme hôte. Enfin, vous l’avez examiné avec Inspector : découverte, appel valide et échec contrôlé.

À vous de jouer. Harbour Cycles, le magasin fictif de location de vélos du module 1, veut un petit serveur en lecture seule. Créez harbour_server.py, un nouveau fichier hors de support_mcp/, avec des enregistrements synthétiques dans un dictionnaire Python :

  1. Cinq vélos, chacun avec un identifiant comme B-101, une taille (S, M ou L), un type, une station et sa disponibilité actuelle.
  2. Un outil en lecture seule get_bike(bike_id) dont l’entrée doit respecter ^B-\d{3}$, qui retourne un vélo ou une erreur d’outil not_found (introuvable).
  3. Un outil en lecture seule list_available(size, limit) : la taille est S, M ou L, la limite va de 1 à 5, et le résultat ne contient jamais plus de 5 vélos.
  4. Une ressource, terms://harbour/rental-terms, avec les conditions de location.
  5. Des journaux sur stderr uniquement.

Examinez-le ensuite avec la CLI d’Inspector : listez les outils, faites un appel valide et un appel qui échoue à la validation.

Afficher une solution détaillée
harbour_server.py
"""Harbour Cycles: a small read-only MCP server over in-memory records."""
import json
import sys
from typing import Annotated, Literal
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations
from pydantic import BaseModel, Field
BIKES = {
"B-101": {"size": "M", "kind": "city", "available": True, "dock": "Harbour Street"},
"B-102": {"size": "L", "kind": "city", "available": False, "dock": "Harbour Street"},
"B-103": {"size": "S", "kind": "child", "available": True, "dock": "Old Pier"},
"B-104": {"size": "M", "kind": "electric", "available": True, "dock": "Old Pier"},
"B-105": {"size": "M", "kind": "electric", "available": False, "dock": "Station Road"},
}
TERMS = """# Rental terms
Rent a bike for 1 to 7 days. The deposit is 50 dollars and comes back when the bike is returned undamaged.
Wear a helmet: we lend one with every bike."""
READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, idempotent_hint=True, open_world_hint=False)
BikeId = Annotated[str, Field(pattern=r"^B-\d{3}$", description="A bike ID, for example B-101.")]
class Bike(BaseModel):
bike_id: str
size: Literal["S", "M", "L"]
kind: str
available: bool
dock: str
class Available(BaseModel):
size: str
bikes: list[Bike] = Field(max_length=5)
mcp = MCPServer("harbour-bikes", version="0.1.0")
def log(**fields) -> None:
print(json.dumps(fields), file=sys.stderr, flush=True)
@mcp.tool(annotations=READ_ONLY)
def get_bike(bike_id: BikeId) -> Bike:
"""Get one rental bike by its ID (for example B-101): its size, kind, dock and whether it is free now."""
if bike_id not in BIKES:
log(event="tool_call", tool="get_bike", outcome="not_found")
raise ToolError(f"not_found: there is no bike {bike_id}")
log(event="tool_call", tool="get_bike", outcome="ok")
return Bike(bike_id=bike_id, **BIKES[bike_id])
@mcp.tool(annotations=READ_ONLY)
def list_available(
size: Literal["S", "M", "L"], limit: Annotated[int, Field(ge=1, le=5, description="1 to 5 bikes.")] = 3
) -> Available:
"""List free bikes of one size (S, M or L), at most 5."""
bikes = [Bike(bike_id=k, **v) for k, v in BIKES.items() if v["size"] == size and v["available"]][:limit]
log(event="tool_call", tool="list_available", outcome="ok", results=len(bikes))
return Available(size=size, bikes=bikes)
@mcp.resource("terms://harbour/rental-terms", name="rental-terms", title="Rental terms", mime_type="text/markdown")
def rental_terms() -> str:
return TERMS
if __name__ == "__main__":
mcp.run("stdio")

L’inspection, depuis le dossier du fichier, avec l’environnement du projet actif (chaque commande après npx @modelcontextprotocol/inspector@2.10.1 --cli python harbour_server.py --) :

Options Code de sortie Résultat reçu
--protocol-era modern --method tools/list 0 2 outils : get_bike (motif ^B-\d{3}$) et list_available (size parmi S, M, L; limit de 1 à 5)
… --method tools/call --tool-name list_available --tool-arg size=M 0 B-101 (ville, Harbour Street) et B-104 (électrique, Old Pier) : les deux vélos M disponibles
… --method tools/call --tool-name list_available --tool-arg size=XL 5 erreur d’outil : Input should be 'S', 'M' or 'L' (l’entrée doit être S, M ou L), input_value='XL'
… --method tools/call --tool-name get_bike --tool-arg bike_id=B-9 5 erreur d’outil : String should match pattern '^B-\d{3}$' (la chaîne doit respecter le motif indiqué)
… --method resources/read --uri terms://harbour/rental-terms 0 les conditions de location

Sur stderr, chaque appel réussi a écrit une ligne, par exemple {"event": "tool_call", "tool": "list_available", "outcome": "ok", "results": 2}.

Votre serveur peut être différent. Vérifiez quatre choses. Chaque entrée a une limite : un motif, une liste de valeurs ou un intervalle. Chaque résultat a une taille maximale, rien n’écrit sur stdout et les outils font seulement de la lecture. Un outil comme run_sql(query) ou edit_bike(...) ne satisfait pas la tâche : il permet l’écriture ou n’a aucune limite.

Vérifiez votre compréhension

Le panneau Messages marque un appel tools/call comme terminé, mais le panneau Results affiche Tool Error en rouge. Expliquez comment les deux peuvent être vrais, et indiquez qui doit réagir à l'erreur.

Afficher la réponse

La requête JSON-RPC a réussi : le serveur a répondu avec un result (résultat), donc le protocole voit une requête terminée. Dans le résultat, isError: true indique que l’outil a refusé l’appel, ici à cause du motif d’entrée. C’est une erreur d’outil, pas une erreur de protocole. Le modèle doit réagir : il lit le texte et peut corriger ses arguments, par exemple en utilisant T-30002. Le code de l’hôte réagit aux erreurs de protocole, comme −32601 ou −32602.

Vérifiez votre compréhension

Prédisez : vous exécutez la CLI d'Inspector avec --tool-arg ticket_id=T-40003 sur support-mcp, démarré comme Sam chez Larkfield. Quel est le code de sortie, que dit le résultat, et est-ce une erreur de protocole ou d'outil?

Afficher la réponse

Code de sortie 5, une erreur d’outil : Error executing tool get_ticket: not_found: there is no ticket T-40003 in this organization (erreur d’exécution de get_ticket : aucun billet T-40003 dans cette organisation), avec isError: true. T-40003 est un billet de soutien de Bramble Books. L’identifiant respecte le motif, donc l’appel atteint l’outil. L’outil cherche le billet uniquement dans Larkfield et répond not_found, comme pour un billet qui n’existe nulle part.

Vérifiez votre compréhension

Vérification pratique : avec Inspector, montrez les descriptions des deux outils de support-mcp. Ont-elles chacune une seule ligne, et quelle annotation Inspector affiche-t-il comme badge?

Afficher la réponse

Oui. Dans l’interface web, la description de get_ticket est un seul paragraphe sans saut de ligne : « Get one support ticket of this organization by its ID (for example T-30002) : … » (obtenir un billet de soutien de cette organisation par son identifiant, par exemple T-30002). Avec la CLI, tools/list affiche "description" comme une seule chaîne sans \n. Inspector affiche READ-ONLY (lecture seule) et IDEMPOTENT (idempotent) comme badges, à partir de readOnlyHint: true et idempotentHint: true. Si vous voyez \n suivi d’espaces, votre serveur a encore des chaînes de documentation sur deux lignes : recopiez server.py depuis end-of-m03.

Vérifiez votre compréhension

Vérification de fin de module : démontrez une découverte réussie, un appel valide et un échec de validation contrôlé pour support-mcp. Pour chacun, donnez la commande ou les clics, et la preuve du résultat.

Afficher la réponse

Une réponse complète contient trois preuves, chacune issue d’une véritable exécution de votre projet.

  1. Découverte. python -m scripts.trace discovery montre cinq requêtes (server/discover, tools/list, resources/list, resources/templates/list, prompts/list) et cinq résultats, avec les identifiants 1 à 5. Ou, dans Inspector : Connected (connecté), MCP 2026-07-28, deux outils, 9 ressources, 1 modèle de ressource et 1 requête.
  2. Un appel valide. get_ticket avec T-30002, depuis Inspector ou python -m scripts.trace valid-call : un résultat avec isError: false, l’objet « Charged twice for order LK-182074 » (facturé deux fois pour la commande LK-182074), et une ligne de journal sur stderr avec "outcome": "ok".
  3. Un échec de validation contrôlé. get_ticket avec la chaîne "30002" : un résultat avec isError: true et String should match pattern '^T-\d{5}$' (la chaîne doit respecter le motif indiqué). Avec la CLI, le code de sortie est 5.

Expliquez chacun en une phrase. La découverte liste ce que tout client peut utiliser. L’appel valide retourne des données structurées et limitées pour l’organisation de l’appelant. L’échec est une erreur d’outil détectée par le schéma du serveur, pas un plantage. Démontré exige les trois, avec les sorties de votre propre exécution. Une capture d’écran de l’appel valide seul correspond à partiellement démontré.

Récapitulatif

  • MCP Inspector 2.10.1 est un client indépendant. Utilisez l’interface web pour explorer, et la CLI pour des vérifications reproductibles. Ses codes de sortie : 0 OK, 5 une erreur d’outil, 1 une erreur.
  • Son ère par défaut est legacy (ancienne); ajoutez --protocol-era modern pour la révision 2026-07-28, et indiquez l’ère testée.
  • Regardez ce que le client reçoit. Les descriptions sont du contenu pour le modèle; Inspector a révélé un véritable défaut que les tests avaient manqué.
  • Une erreur d’outil est une requête terminée avec isError: true. Une erreur de protocole est une réponse error (erreur).

Récapitulatif du module. Vous avez choisi la trousse SDK officielle à l’aide de quatre questions, puis créé un environnement neuf et testé. Vous avez lu JSON-RPC à la main : requêtes, résultats, erreurs, notifications et silence après une ligne invalide. Vous avez exécuté support-mcp sur stdio, avec le protocole sur stdout, les journaux sur stderr et l’appelant défini par l’environnement. Vous avez aussi examiné le serveur comme tout autre client le ferait. Votre projet correspond à l’instantané end-of-m03 : 40 passed (40 tests réussis).

Ensuite, vous créerez votre propre application d’IA qui se connecte à ce serveur, d’abord avec un modèle simulé.

Leçon suivante : Intégration du client