Aller au contenu
English

Un serveur MCP sur un vrai jeu de données ouvert

  • Étude de cas 1
  • 180 min
  • Facultative · 1 étude de cas requise pour le certificat

Où nous en sommes

Cette étude de cas applique la conception des capacités du module 2 et l'hôte du module 4 à de vraies données publiques : les rapports de rappels alimentaires de la FDA. Vous créez un serveur MCP en lecture seule, vous limitez et mesurez chaque réponse, et vous comparez trois conceptions avec une seule mesure.

Étude de cas 1 sur 2 · MCP : connecter les applications d'IA aux outils et aux donnéesUn serveur MCP sur un vrai jeu de données ouvert

Ce que vous saurez faire

Créez un serveur MCP en lecture seule sur de vraies données publiques : les rapports de rappels alimentaires de la Food and Drug Administration (FDA) des États-Unis. Vous concevez les capacités selon les besoins des gens, vérifiez les données, puis limitez et mesurez chaque réponse. Ensuite, vous testez le contrat, examinez le serveur et connectez l’hôte du cours à un modèle simulé. Enfin, vous comparez trois conceptions avec une même mesure.

Étude de casPièce de portfolio

Durée
Environ 3 h
S’exécute dans
VS Code, Python 3.12+
Compétences utilisées
  • Catalogue des capacités
  • Vérifications des données avec SHA-256
  • Résultats d'outils limités
  • URI de ressources stables
  • Tests de contrat
  • MCP Inspector, ère moderne
  • Hôte avec modèle simulé
  • Une comparaison équitable

Décompressez le projet de départ, ouvrez le dossier dans VS Code et suivez les étapes ci-dessous. Elles commencent par un nouvel environnement virtuel.

Le projet de départ comprend le téléchargement des données et ses vérifications, le service métier, l’hôte du cours et les scripts de mesure. Vous ajoutez le catalogue des capacités, les contrats, le serveur et ses tests. Le projet terminé présente le résultat, pour vous aider si vous bloquez. Le code est sous licence MIT. Les personnes de l’histoire sont fictives; les rappels sont de vrais documents publics.

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

Ce que vous devez savoir

Cette étude de cas utilise tout le cours, avec des données qui ne viennent pas de Larkfield. Elle s’appuie surtout sur Outils, Ressources, Requêtes, Examiner le comportement, Découverte et exécution et Résultats et défaillances. Le test de contrat suit Tests de contrat et de compatibilité. Les limites suivent Limites de ressources et observabilité.

Ce qu’il vous faut sur votre ordinateur

  • Python 3.12 ou une version plus récente et VS Code. Node.js 22.19 ou une version plus récente, pour Inspector seulement.
  • Environ 120 Mo d’espace disque libre : les paquets, les données (5,9 Mo à télécharger) et leur base de données (30 Mo).
  • Aucun compte, aucune clé et aucuns frais. Un vrai modèle est facultatif.

Testé sur macOS (Apple M4, 16 Go, Python 3.12.13, Node.js 24.18.0). Les commandes Windows et Linux sont fournies, mais n’ont pas été testées. Cette étude de cas utilise la révision du 28 juillet 2026 de la spécification MCP et la trousse SDK Python officielle MCP 2.3.0.

Marisol Reyes dirige la sécurité alimentaire chez Cedar Lane, une chaîne de 14 épiceries. Dev Okoro développe ses logiciels. Les deux personnes sont fictives.

Chaque semaine, le service de soutien reçoit les mêmes questions. « J’ai acheté des huîtres congelées. Font-elles l’objet d’un rappel? » « Les nouvelles parlaient du rappel H-1137-2026. De quoi s’agit-il? » Les agents cherchent manuellement sur le site de la FDA. Les réponses varient d’un agent à l’autre.

Cedar Lane utilise déjà deux applications d’IA : l’assistant du service de soutien et un assistant du personnel dans l’application des magasins. Une troisième application, celle d’un partenaire de livraison, s’ajoutera bientôt. Marisol ne veut pas trois intégrations avec les mêmes données publiques. Dev propose un seul serveur MCP que toutes les applications pourront utiliser.

Marisol fixe quatre règles :

  • Lecture seule. L’assistant cherche des renseignements. Il ne change rien.
  • Nommer la source. Chaque réponse donne le numéro de rappel de la FDA pour qu’une personne puisse le vérifier.
  • Jamais « sans danger ». « Aucun rappel trouvé » signifie « absent de ces données ». Cela ne signifie jamais « ce produit est sans danger ».
  • Pas de réponses démesurées. Aucune réponse ne doit être trop grande pour que l’assistant puisse la lire.

L’objectif. Un seul serveur MCP pour les rapports publics de rappels alimentaires de la FDA. Sur un ensemble fixe de 22 questions, l’hôte du cours avec un modèle simulé nomme chaque fois le bon rappel. Chaque réponse d’outil respecte la limite de 4 000 caractères de l’hôte. Un test de contrat détecte tout changement visible pour les clients.

En haut, une chaîne de gauche à droite. Le fichier de rappels alimentaires openFDA : 29 471 enregistrements, 5,9 Mo, domaine public (CC0 1.0). Une flèche nommée téléchargement mène à scripts/get_data.py, en ambre : il vérifie le SHA-256 fa59ccc9… et exclut 47 enregistrements dont le numéro de rappel est invalide. Une flèche nommée construction mène à data/recalls.db : SQLite et un index de recherche en texte intégral, 29 424 rappels. Une flèche nommée lecture mène à store.py, le service métier, sans MCP. De store.py, une flèche descend vers le serveur MCP, food-recalls (stdio, révision 2026-07-28, SDK 2.3.0). Il contient trois cases. Outils, le modèle choisit : search_recalls, au plus 5 courts résumés, les plus récents en premier; get_recall, un rappel, textes longs tronqués. Ressources, l'application choisit : recall://fda-food/{recall_number}; la liste contient les rappels de classe I en cours les plus récents, au plus 50. Requête, la personne choisit : customer_answer(recall_number), nommer la source, aucun conseil médical. À gauche, deux clients se connectent au serveur avec des flèches nommées MCP : l'hôte du cours (modèle : simulé ou réel; exécute seulement les outils de la liste d'autorisation; tronque tout résultat dépassant 4 000 caractères) et MCP Inspector 2.10.1 avec --protocol-era modern et sans modèle.
Le projet terminé. Les données sont vérifiées avant que le serveur les lise. Le serveur offre deux outils à résultats limités, un modèle d'URI de ressource et une requête. L'hôte du cours et Inspector sont ses clients.
Description textuelle du diagramme

Les données passent du fichier openFDA par scripts/get_data.py vers une base de données SQLite de 29 424 rappels. Le script vérifie la somme de contrôle SHA-256 et exclut 47 enregistrements dont le numéro de rappel est invalide. store.py lit la base de données, sans MCP. Le serveur MCP food-recalls offre deux outils en lecture seule, search_recalls et get_recall. Il offre aussi un modèle d’URI de ressource, recall://fda-food/{recall_number}, avec une liste des 50 rappels de classe I en cours les plus récents. Il propose également une requête, customer_answer. L’hôte du cours et MCP Inspector s’y connectent par stdio.

Partie Ce que vous faites Preuve
1 Vérifier les données la somme de contrôle, 47 identifiants invalides, les tailles
2 Écrire le catalogue des capacités docs/capability-catalog.md
3 Créer le serveur avec des résultats limités recalls_mcp/contracts.py, server.py
4 Tester le contrat et mesurer les limites 32 tests, contract/capabilities.json
5 L’examiner dans l’ère moderne les réponses d’Inspector
6 Utiliser l’hôte et le faire échouer volontairement une réponse qui nomme sa source
7 Comparer trois conceptions avec une même mesure 22 questions
8 Poser de nouvelles questions, avec un vrai modèle en option les exécutions

Les données sont les rapports de rappels alimentaires de la FDA, fournis par openFDA. Un enregistrement représente un produit rappelé : son numéro de rappel (par exemple H-1393-2026), l’entreprise, le produit, la raison, la classe, le statut et les dates. La classe I est la plus grave : une probabilité raisonnable de préjudice sérieux. Un événement de rappel peut couvrir plusieurs produits. Plusieurs enregistrements peuvent donc partager un numéro d’événement.

openFDA publie un nouveau fichier chaque semaine sous le même nom. Le lien d’origine ne peut donc pas avoir une somme de contrôle fixe. Le cours conserve le fichier exact utilisé, l’exportation du 6 octobre 2026 (5,9 Mo), dans son dépôt de laboratoires. CC0 le permet. scripts/get_data.py télécharge cette copie et la vérifie. Le fichier DATASET.md du projet est la fiche du jeu de données : source, licence, somme de contrôle, changements et limites. Le cours a aussi examiné deux autres sources possibles. Un service de rappels de produits de consommation n’indique aucune licence pour ses données. Le cours ne l’a donc pas utilisé.

Les étapes utilisent VS Code et son terminal. Toutes les commandes s’exécutent dans le dossier du projet.

  1. Téléchargez le projet de départ dans l’encadré en haut de cette page. Décompressez-le dans votre dossier de projets, par exemple ~/projects. Vous obtenez le dossier food-recalls.

  2. Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier), puis ouvrez food-recalls. Ouvrez ensuite un terminal : Terminal > New Terminal (terminal, nouveau terminal).

  3. Créez et activez un environnement virtuel, installez les paquets et récupérez les données :

    Fenêtre de terminal
    python3 -m venv .venv
    source .venv/bin/activate
    python -m pip install -r requirements-dev.txt
    python -m scripts.get_data
    Sortie (fin)
    Checked food-enforcement-2026-10-06.json.zip: SHA-256 fa59ccc9642b... is correct
    Wrote data/recalls.db: 29,424 recalls (openFDA export of 2026-10-06)
    Left out 47 records whose recall number is not in FDA's form: data/excluded.jsonl

    L’invite commence par (.venv). Les paquets utilisent les versions du cours : mcp 2.3.0, pytest 9.1.1 et ruff 0.17.0.

  4. Exécutez les tests du projet de départ :

    Fenêtre de terminal
    python -m pytest -q
    Sortie
    ......... [100%]
    9 passed in 0.04s

Les neuf tests vérifient seulement le service métier : la somme de contrôle, les nombres d’enregistrements, la recherche et un rappel. Il n’y a pas encore de MCP.

Partie 1 : vérifier les données avant de les servir

Section intitulée « Partie 1 : vérifier les données avant de les servir »

Une somme de contrôle est une courte empreinte d’un fichier. Si un seul octet change, l’empreinte SHA-256 change complètement. scripts/get_data.py compare l’empreinte du fichier téléchargé à celle dans data/SHA256SUMS. Si elles diffèrent, il supprime le fichier et s’arrête. Ainsi, le serveur ne lit jamais un téléchargement modifié ou endommagé, et vos chiffres correspondent à ceux de cette page.

Une URI de ressource comme recall://fda-food/H-1393-2026 reste stable seulement si chaque rappel possède un identifiant valide et unique. Les numéros de rappel de la FDA suivent une seule forme : une lettre, un tiret, quatre chiffres, un tiret, quatre chiffres. La vérification a trouvé 47 enregistrements sur 29 471 (0,16 %) qui ne respectent pas cette forme. Quelques exemples :

'' (empty; reported 2026-09-30)
'F1462-2014' 'F-1772' 'F-0455-201' 'Ff-2095-201' 'F-1855.2013'

Dev avait trois choix : corriger les numéros, inventer des identifiants ou exclure les enregistrements. Un numéro corrigé peut pointer vers un autre vrai rappel. Un identifiant inventé ne signifie rien pour la FDA. La construction exclut donc les 47 enregistrements et les liste dans data/excluded.jsonl. Ce choix a un coût : l’un d’eux est un rappel récent sans numéro. C’est une raison de plus pour la règle de Marisol : « non trouvé » ne signifie jamais « sans danger ».

Le serveur doit répondre aux questions en respectant des limites. Les faits utiles concernent donc les tailles : la longueur d’un enregistrement et le nombre d’enregistrements correspondant à une question.

  • Un enregistrement. La médiane est de 1 100 caractères de JSON. Le plus grand compte 44 645 caractères, dont 41 747 sont des codes de lot.
  • Une question. « american ginseng » (ginseng américain) correspond à 3 rappels, « infant formula » (préparation pour nourrissons) à 74, et « listeria » à 7 487.
  • Un événement. Le plus grand événement de rappel comprend 409 rappels.

La plupart des enregistrements sont petits, mais quelques-uns sont énormes. Certaines questions correspondent à des milliers d’enregistrements. Une conception adaptée à la médiane peut échouer avec la plus grande réponse.

Partez des besoins des gens, pas des 25 colonnes des données, comme dans Outils. Ouvrez docs/capability-catalog.md. Les besoins s’y trouvent; remplissez le catalogue. Voici celui de Dev :

Besoin Capacité Qui choisit Limites
Ce produit fait-il l’objet d’un rappel? outil search_recalls(query, status, classification, limit) le modèle requête de 3 à 100 caractères; au plus 5 résultats, les plus récents en premier; produit et raison tronqués à 200 caractères; nombre de correspondances
De quoi parle le rappel X? outil get_recall(recall_number) le modèle forme de la FDA, ^[A-Z]-\d{4}-\d{4}$; un enregistrement; chaque texte long tronqué
Lire ou citer le rapport entier modèle d’URI de ressource recall://fda-food/{recall_number} l’application ou la personne un rapport en Markdown; seuls les codes de lot sont tronqués, à 3 000 caractères
Les rappels graves encore en cours resources/list l’application les rappels de classe I en cours les plus récents, au plus 50
Une façon de répondre à un client requête customer_answer(recall_number) la personne numéro vérifié; source nommée; aucun conseil médical

Les idées rejetées sont aussi utiles que le catalogue. list_all_recalls() renverrait 29 424 enregistrements. Un outil qui exécute du SQL n’aurait ni limites ni contrat. Une entrée de liste pour chaque rappel donnerait 29 424 entrées. Le modèle d’URI les décrit tous. La liste contient les 50 qui comptent cette semaine.

Les données sont publiques. Le serveur n’a donc ni connexion ni organisations : tous les appelants voient les mêmes données. Un serveur avec des données privées a besoin des vérifications d’Identité et autorisations.

Le problème : une mince couche d’intégration submerge l’assistant

Section intitulée « Le problème : une mince couche d’intégration submerge l’assistant »

Le serveur le plus rapide à créer est une mince couche d’intégration : l’outil lance la recherche et renvoie chaque correspondance au complet. Dev le crée d’abord comme référence de base. Puis il lui pose une question de la partie 1 : « Une préparation pour nourrissons fait-elle l’objet d’un rappel? » Le serveur envoie 74 enregistrements complets, soit 94 611 caractères. L’hôte du cours coupe tout résultat après 4 000 caractères, comme dans Résultats et défaillances. Le texte coupé n’est plus du JSON valide. Le modèle ne peut pas le lire, donc il ne donne aucune réponse.

L’idée : des résumés d’abord, des détails sur demande

Section intitulée « L’idée : des résumés d’abord, des détails sur demande »

Pensez à un catalogue de bibliothèque. Une fiche est courte : le titre, l’auteur et la cote. Vous lisez quelques fiches, vous en choisissez une, puis vous allez chercher ce livre. Personne ne pose tous les livres correspondants sur le comptoir.

La même idée fonctionne pour le résultat d’un outil. search_recalls renvoie de courts résumés : au plus 5, du plus récent au plus ancien, avec leur numéro de rappel et leur URI. Il indique aussi le nombre de rappels correspondants, pour que le modèle sache qu’il y en a d’autres. Ensuite, get_recall renvoie un enregistrement complet, dont chaque texte long est coupé à une longueur fixe. Chaque réponse a donc une taille maximale connue, quelle que soit la question.

Une question, trois conceptions : une préparation pour nourrissons fait-elle l'objet d'un rappel? 74 rappels correspondent. Trois colonnes. Tout, chaque correspondance au complet : le serveur envoie 74 enregistrements complets, soit 94 611 caractères; l'hôte coupe à 4 000 caractères et le JSON devient invalide; le modèle ne répond pas; bonnes réponses à 22 questions : 10 sur 22. Complet, les 5 plus récents au complet : le serveur envoie 5 enregistrements complets, soit 6 385 caractères; l'hôte coupe à 4 000 caractères et le JSON devient invalide; le modèle ne répond pas; 10 sur 22. Résumé, 5 résumés puis un rappel : le serveur envoie search_recalls, 2 668 caractères, puis get_recall H-1137-2026, 1 407 caractères; chaque résultat reste sous 4 000 caractères; le modèle nomme H-1137-2026, la correspondance la plus récente; 22 sur 22.
La même question, trois conceptions de résultats, le même hôte. Seule la conception par résumés garde chaque résultat sous la limite de l'hôte.
Description textuelle du diagramme

Pour « Une préparation pour nourrissons fait-elle l’objet d’un rappel? » (74 correspondances) :

Conception Le serveur envoie L’hôte Le modèle Bonnes réponses, sur 22 questions
tout : chaque correspondance au complet 74 enregistrements, 94 611 caractères coupe à 4 000 : JSON invalide aucune réponse 10
complet : les 5 plus récents au complet 5 enregistrements, 6 385 caractères coupe à 4 000 : JSON invalide aucune réponse 10
résumé : 5 résumés, puis un rappel 2 668, puis 1 407 caractères les deux respectent la limite nomme H-1137-2026 22
  1. Ajoutez recalls_mcp/contracts.py, comme dans Outils : les bornes, les types d’entrée et les modèles de sortie. Les bornes sont des constantes nommées, pour qu’un test puisse les lire :

    recalls_mcp/contracts.py (part)
    MAX_QUERY_CHARS = 100
    MAX_RESULTS = 5
    DEFAULT_RESULTS = 5
    SUMMARY_CHARS = 200 # product and reason in a search result
    DETAIL_CHARS = { # each text field of get_recall
    "product_description": 1000,
    "reason_for_recall": 500,
    "product_quantity": 200,
    "code_info": 1000,
    "distribution_pattern": 500,
    }
    RECALL_URI_TEMPLATE = "recall://fda-food/{recall_number}"
    RecallNumber = Annotated[
    str, Field(pattern=RECALL_NUMBER, description="An FDA recall number, for example F-0123-2025.")
    ]

    Le fichier terminé contient aussi les modèles RecallSummary, SearchResult et Recall, ainsi que le texte de la requête.

  2. Ajoutez recalls_mcp/server.py. Chaque outil est une fonction avec une chaîne de documentation d’une ligne, des annotations de lecture seule et des entrées typées. C’est l’approche de Transport local :

    recalls_mcp/server.py (part)
    @mcp.tool(annotations=READ_ONLY)
    def search_recalls(
    query: contracts.Query,
    status: contracts.Status = "any",
    classification: contracts.Classification = "any",
    limit: contracts.Limit = contracts.DEFAULT_RESULTS,
    ) -> contracts.SearchResult:
    """Search FDA food recall enforcement reports, newest first. Returns at most 5 short summaries and the number of matches. Read one with get_recall."""
    started = time.perf_counter()
    try:
    total, rows = store.search(
    query,
    None if status == "any" else status,
    None if classification == "any" else classification,
    limit,
    )
    except ValueError as e:
    raise ToolError(f"invalid_query: {e}") from None
    log.event("tool_call", tool="search_recalls", matches=total, returned=len(rows), ms=logs.ms_since(started))
    return contracts.SearchResult(query=query, total_matches=total, results=[summary(r) for r in rows])

    get_recall lève ToolError("not_found: …") pour un numéro absent des données. La ressource lève ResourceNotFoundError, que la trousse SDK transmet avec le code −32602, comme dans Ressources. Le serveur terminé contient aussi un sélecteur, RECALLS_DESIGN, pour les deux variantes des parties 6 et 7. Ces parties en ont besoin; prenez donc cette portion dans le fichier server.py terminé. Utilisez le sélecteur uniquement pour la comparaison.

  3. Ajoutez recalls_mcp/__main__.py, qui lance le serveur sur stdio, et recalls_mcp/logs.py, qui écrit une ligne JSON par appel sur stderr. Avec stdio, stdout appartient au protocole.

  4. Si vous bloquez, copiez les quatre fichiers du projet terminé. Posez ensuite une question au serveur par l’hôte du cours :

    Fenêtre de terminal
    python -m host "Is american ginseng under a recall?"
    Output (the server's log lines on stderr left out)
    [host] discovered 2 tools: search_recalls, get_recall {"protocol": "2026-07-28", "server": "food-recalls"}
    [model] wants search_recalls {"arguments": {"query": "american ginseng"}}
    [host] read-only tool on the allow-list: run it {"decision": "auto"}
    [server] result: 1434 characters {"ms": 21.9, "chars": 1434, "clipped": false}
    [model] wants get_recall {"arguments": {"recall_number": "H-1393-2026"}}
    [host] read-only tool on the allow-list: run it {"decision": "auto"}
    [server] result: 862 characters {"ms": 3.9, "chars": 862, "clipped": false}
    [model] final answer
    Recall H-1393-2026 (Class III, Ongoing, reported 2026-09-30): Kwok Shing, Inc., American Ginsengs. PRODUCT OF WISCONSIN. NET WT: 4 oz. NET WT. 8 oz. Reason: Potential contamination with pesticides. Source: recall://fda-food/H-1393-2026. 3 recalls match; this is the newest.

Ce que cela nous apprend. L’hôte est celui du cours présenté dans Intégration du client, avec quatre changements. Il lance ce serveur, possède sa propre liste d’autorisation et sa requête système, et son modèle simulé suit des règles pour ce serveur. Le modèle simulé cherche les mots de la question, sans les mots comme « is » (est) et « recall » (rappel). Puis il lit la correspondance la plus récente avec get_recall et la nomme. Les deux résultats d’outils comptaient 1 434 et 862 caractères.

L’hôte lance le serveur avec une liste d’autorisation de paramètres, comme dans Limites des identifiants. Une clé de modèle dans votre interpréteur de commandes n’atteint jamais le serveur.

Les utilisateurs du serveur sont d’autres applications. Son contrat est donc ce qu’elles voient : noms, descriptions, schémas, modèle de ressource et requête. Copiez scripts/contract.py du projet terminé. Il demande son contrat au serveur et le compare à contract/capabilities.json, comme dans Tests de contrat et de compatibilité. Écrivez le fichier une fois, puis vérifiez-le :

Fenêtre de terminal
python -m scripts.contract --write
python -m scripts.contract
Sortie
Wrote capabilities.json: 2 tools, 1 resource template, 1 prompt
The server matches contract/capabilities.json.

Copiez ensuite les fichiers de test du projet terminé : tests/conftest.py, qui remplace celui du projet de départ, et les quatre nouveaux fichiers test_server.py, test_contract.py, test_stdio.py et test_host.py. Exécutez tous les tests :

Fenêtre de terminal
python -m pytest -q
Sortie
................................ [100%]
32 passed in 1.05s

Les 23 nouveaux tests vérifient les engagements de cette étude de cas :

  • Bornes. Un limit de 6, une requête de 2 caractères et une requête de 101 caractères produisent des erreurs d’outil. Les 20 plus gros enregistrements respectent la limite de 4 000 caractères de l’hôte. La plus grosse réponse de recherche parmi les 20 questions sur des produits la respecte aussi.
  • Erreurs. H1393 ne respecte pas le format. F-9999-2001 produit not_found (introuvable). Une ressource absente produit −32602, avec data.uri.
  • Sécurité. Chaque outil est en lecture seule. Le texte de la requête ne peut pas utiliser la syntaxe du moteur de recherche (OR, *, NEAR). Le serveur place chaque mot entre guillemets.
  • Transport. Le client de la trousse SDK lance python -m recalls_mcp comme processus enfant, avec la révision 2026-07-28 et l’ancienne ère initialize.
  • Le contrat. Le modèle d’URI ne change jamais, et chaque entrée a une borne.

Quelle est la taille de la plus grosse réponse? scripts/sizes.py lit chacun des 29 424 rappels par un client MCP : une fois avec get_recall, puis comme ressource.

Fenêtre de terminal
python -m scripts.sizes
Sortie
answer count median p95 p99 max (characters)
openFDA record (no bound) 29,471 1,100 1,636 2,451 44,645
get_recall result 29,424 1,098 1,627 2,105 3,590
recall resource text 29,424 831 1,369 2,184 7,713
search_recalls, limit 5 20 2,423 2,711 2,820 2,820
resources/list: 50 recalls (bound 50)
  • sans borne
  • borné par le serveur
La plus grosse réponse de chaque type, parmi tous les rappels (pour la recherche : parmi les 20 questions sur des produits). Les bornes changent à peine l'enregistrement médian; elles raccourcissent le plus gros.
Description textuelle du graphique

Le plus gros enregistrement openFDA compte 44,645 caractères. Le plus gros texte de ressource de rappel en compte 7,713, le plus gros résultat get_recall, 3,590, et la plus grosse réponse de recherche avec une limite de 5, 2,820. Les médianes sont de 1,100 caractères pour un enregistrement et de 1,098 pour un résultat get_recall.

Ce que cela nous apprend. Les bornes ne raccourcissent pas les réponses typiques : le résultat médian de get_recall est aussi long que l’enregistrement médian. Elles raccourcissent les cas extrêmes, de 44 645 caractères à 3 590. C’est le but d’une borne : un maximum connu. Le texte de ressource peut être plus long, jusqu’à 7 713 caractères. L’application choisit de le lire au complet, comme dans Ressources.

Les tests utilisent le client de la trousse SDK. Examinez maintenant le serveur tel qu’un autre client le voit, avec MCP Inspector, comme dans Examiner le comportement. Par défaut, Inspector 2.10.1 utilise l’ancienne négociation initialize. Ajoutez --protocol-era modern pour la révision 2026-07-28. Écrivez d’abord la commande du serveur, puis --, puis les options d’Inspector :

Fenêtre de terminal
npx @modelcontextprotocol/inspector@2.10.1 --cli python -m recalls_mcp -- --protocol-era modern --method tools/list
npx @modelcontextprotocol/inspector@2.10.1 --cli python -m recalls_mcp -- --protocol-era modern --method tools/call --tool-name search_recalls --tool-arg query=listeria --tool-arg limit=11
npx @modelcontextprotocol/inspector@2.10.1 --cli python -m recalls_mcp -- --protocol-era modern --method resources/read --uri recall://fda-food/F-9999-2001
Output of the second command (part), exit code 5
"text": "Error executing tool search_recalls: 1 validation error for search_recallsArguments\nlimit\n Input should be less than or equal to 5 [type=less_than_equal, input_value=11, input_type=int]…"
"isError": true
Output of the third command, exit code 1
{"error":{"code":"error","message":"Resource not found: recall://fda-food/F-9999-2001"}}

Le cours a exécuté douze commandes de ce type, dont onze dans l’ère moderne. Chaque réponse correspondait aux tests : deux outils avec leurs bornes, le modèle d’URI, 50 ressources répertoriées, la requête, une erreur d’outil not_found et le limit refusé. Un enregistreur entre Inspector et le serveur a montré server/discover, puis des requêtes avec _meta pour la révision 2026-07-28. Pour la ressource absente, l’interface en ligne de commande affiche « error » (erreur), et non −32602; les tests vérifient le code.

Essayez deux autres questions : une sans correspondance et une par numéro de rappel.

Fenêtre de terminal
python -m host "Is there a recall of dragon fruit gummies?"
python -m host "What is recall H-1393-2026 about?"
Output (the final answers)
I found no FDA food recall that matches "dragon fruit gummies" in the data.
Recall H-1393-2026 (Class III, Ongoing, reported 2026-09-30): Kwok Shing, Inc., American Ginsengs. PRODUCT OF WISCONSIN. NET WT: 4 oz. NET WT. 8 oz. Reason: Potential contamination with pesticides. Source: recall://fda-food/H-1393-2026.

La première réponse dit « dans les données ». Elle ne dit pas « sans danger ». La deuxième réponse a demandé un seul appel : le modèle simulé a reconnu un numéro de rappel et appelé directement get_recall.

Provoquez maintenant un échec. Lancez le serveur avec la conception « complet », qui renvoie les 5 enregistrements les plus récents au complet :

Fenêtre de terminal
RECALLS_DESIGN=full python -m host "Is there a listeria recall?"
Output (the server's log lines left out)
[host] discovered 2 tools: search_recalls, get_recall {"protocol": "2026-07-28", "server": "food-recalls"}
[model] wants search_recalls {"arguments": {"query": "listeria"}}
[host] read-only tool on the allow-list: run it {"decision": "auto"}
[server] result: 4816 characters {"ms": 25.7, "chars": 4816, "clipped": true}
[model] final answer
I could not read the result of search_recalls: result cut to 4000 characters by the host.

L’hôte a transmis RECALLS_DESIGN au serveur parce qu’il figure dans la liste d’autorisation. Les cinq enregistrements complets comptaient 4 816 caractères. L’hôte les a donc coupés, et le modèle simulé n’a pas pu lire le JSON coupé. Un vrai modèle peut deviner à partir du texte coupé, ce qui est pire : la supposition ressemble à une réponse.

Partie 7 : une comparaison équitable selon une seule mesure

Section intitulée « Partie 7 : une comparaison équitable selon une seule mesure »

La conception par résumés est-elle vraiment meilleure, ou Dev a-t-il choisi des questions faciles? Comparez les trois conceptions équitablement : les mêmes 22 questions, le même hôte, le même modèle simulé et les mêmes données. Seule la conception change.

Les questions sont dans questions/eval.jsonl : 15 sur un produit, 3 générales (« laitue romaine », « arachide », « listeria »), 2 sans correspondance et 2 par numéro de rappel. Chaque question indique l’événement de rappel attendu. Pour chaque question sur un produit, le cours a vérifié manuellement que la correspondance la plus récente concerne le produit demandé. Le test mesure donc la forme du résultat, et non le classement de la recherche.

La mesure. Une réponse est correcte si elle nomme un rappel de l’événement attendu ou dit « aucun rappel » lorsqu’aucun ne correspond. Le script compte aussi les caractères des résultats d’outils que le modèle a lus.

Fenêtre de terminal
python -m scripts.compare
Sortie
22 questions, mock model, host limit 4,000 characters per result
design right cut model read (median / max) server sent (median / max)
everything 10/22 12 4,256 / 4,456 4,278 / 8,345,314
full 10/22 12 4,256 / 4,456 4,278 / 8,278
summary 22/22 0 2,868 / 4,464 3,096 / 4,720
  • limite de l'hôte de 4 000 caractères
  • sans limite de l'hôte
Bonnes réponses aux 22 questions, avec le modèle simulé (tout : la conception qui renvoie tout). Avec la limite de l'hôte, seule la conception par résumés répond à chaque question. Sans limite, les trois y arrivent, avec des tailles très différentes.
Description textuelle du graphique

Avec la limite de 4 000 caractères de l’hôte, la conception « tout » a répondu correctement 10 fois, « complet », 10 fois et « résumé », 22 fois. Sans limite, chacune des trois conceptions a répondu correctement 22 fois.

Ce que cela nous apprend. Trois constats.

  • Les deux conceptions à enregistrements complets ont échoué aux mêmes 12 questions. Chaque échec venait d’un résultat coupé. « Pollen d’abeille » a échoué de 3 caractères : ses 4 enregistrements complets comptaient 4 003 caractères. Une conception qui fonctionne pour la plupart des questions n’est pas bornée.
  • La conception par résumés a répondu correctement 22 fois et lu le moins de texte : une médiane de 2 868 caractères, en deux appels d’outils. Sa plus grosse paire de réponses comptait 4 720 caractères au total, et chaque réponse respectait à elle seule la limite.
  • Changez une seule chose : retirez la limite de l’hôte, avec python -m scripts.compare --host-limit 10000000. Les trois conceptions répondent alors correctement 22 fois. Mais pour « listeria », la conception « tout » transmet 8 345 360 caractères au modèle. C’est bien plus qu’un modèle peut lire en une requête. Retirer une limite ne rend pas une conception bonne. Cela déplace l’échec vers le modèle.

La comparaison est-elle équitable? Les questions, l’hôte, le modèle et les données étaient les mêmes. Le modèle simulé ne comporte aucun hasard : chaque exécution donne les mêmes réponses. Le cours a écrit les questions pour tester la forme du résultat, et non la qualité du classement de recherche. Et 22 questions, c’est peu : elles montrent un échec, pas un taux.

Utilisez la conception par résumés. Elle donne au plus 5 courts résumés avec le nombre de correspondances, puis un enregistrement borné sur demande. La ressource donne le rapport complet. Gardez les bornes comme constantes nommées, avec un test du plus gros cas. Gardez le fichier de contrat et modifiez-le seulement après révision des différences. N’augmentez pas la limite de l’hôte pour sauver une conception qui envoie trop de texte.

La comparaison utilisait des questions fixes. Posez maintenant des questions qui n’en faisaient pas partie. Avec le modèle simulé :

Fenêtre de terminal
python -m host "Are half shell oysters recalled?"
python -m host "Is kombucha under a recall?"
Output (the final answers)
Recall H-0482-2026 (Class II, Terminated, reported 2026-02-11): Khee Trading, Inc., Product is Frozen Half Shell Oysters in 15-16 pound blocks. Packaged in generic brown cardboard boxes. Side panel … Reason: Imported oysters potentially contaminated with Norovirus. Source: recall://fda-food/H-0482-2026. 13 recalls match; this is the newest.
Recall F-1461-2023 (Class II, Terminated, reported 2023-09-06): C & S Wholesale Grocers Inc., The following items sold at Stop & Shop stores located in the New York Metro Region: Natures Promise Lemonade Natures … Reason: Perishable products were not held at an appropriate temperature. Source: recall://fda-food/F-1461-2023. 13 recalls match; this is the newest.

La réponse sur les huîtres est correcte. La réponse sur le kombucha montre une limite de la recherche par mots. La correspondance la plus récente est une liste de nombreux produits, dont le kombucha. La réponse est vraie, mais un agent doit lire l’enregistrement avant d’informer un client. Le modèle simulé prend toujours la correspondance la plus récente et ne peut pas juger ce cas. Un vrai modèle peut lire les cinq résumés et choisir.

L’hôte fonctionne aussi avec tout modèle compatible avec OpenAI, comme dans Intégration du client. Le cours a exécuté quatre nouvelles questions avec un déploiement Azure d’un petit modèle, chat-small. Vous n’avez pas besoin de le faire : les exécutions sont résumées dans docs/results.md du projet.

La première exécution a révélé un vrai défaut. La première version permettait un limit allant jusqu’à 10, et le modèle a demandé 10 rappels de préparations pour nourrissons. La réponse comptait 5 531 caractères, et l’hôte l’a coupée. Le modèle a quand même répondu à partir du texte coupé, par chance. Dev a abaissé le maximum à 5, mesuré à nouveau et ajouté un test. La plus grosse réponse de recherche compte maintenant 2 820 caractères. Le test de contrat a ensuite montré le changement dans la description, maximum et maxItems, sous forme de différences à réviser.

Après la correction, les quatre exécutions ont utilisé 10 appels au modèle et coûté 0,0013 $ US au total. Voici l’une d’elles, vérifiée dans les données :

chat-small, after the fix (bold marks of the answer removed)
Q: Has any infant formula been recalled recently? Give me the newest one.
[model] wants search_recalls {"query": "infant formula", "limit": 5} → 2,668 characters
[model] wants get_recall {"recall_number": "H-1137-2026"} → 1,407 characters
A: Yes. The newest infant formula recall in the FDA results is Nara Organics Whole Milk Organic Infant
Formula, recall H-1137-2026, reported July 8, 2026. It’s an ongoing Class I recall because the product
may be contaminated with Clostridium botulinum. …

Pour la question sur les huîtres, le modèle a demandé quatre rappels en un seul tour. Il a correctement indiqué que les quatre étaient terminés. Un modèle testé un jour ne prouve rien sur le prochain. Les tests et les bornes n’en dépendent pas.

Erreur courante

L'hôte coupe un résultat que les tests jugeaient acceptable

Symptôme : un vrai modèle reçoit un résultat avec la note « result cut to 4000 characters by the host » (résultat coupé à 4 000 caractères par l’hôte), même si python -m pytest réussit.

Cause : les tests vérifiaient le limit par défaut de 5, mais le schéma permettait 10. Un modèle peut demander le maximum, et la réponse peut alors dépasser la limite.

Correction : testez la plus grosse réponse permise par le schéma, et non la valeur par défaut. Mesurez-la sur les vraies données (python -m scripts.sizes) et abaissez la borne jusqu’à ce que le plus gros cas respecte la limite.

Erreur courante

Les tests s'arrêtent avant de commencer

Symptôme : python -m pytest affiche data/recalls.db is missing: run python -m scripts.get_data first (data/recalls.db est absent : exécutez d’abord python -m scripts.get_data).

Cause : la base de données n’est pas dans le fichier zip. Les tests utilisent les vraies données.

Correction : exécutez python -m scripts.get_data. S’il signale une somme de contrôle différente, le téléchargement a été modifié ou endommagé : recommencez. Ne modifiez pas SHA256SUMS.

  • Bornez le pire cas, pas le cas typique. La plupart des enregistrements comptent environ 1 100 caractères, et la plupart des conceptions fonctionnent pour la plupart des questions. Les échecs venaient des cas extrêmes : un enregistrement de 44 645 caractères et une requête avec 7 487 correspondances.
  • Vérifiez les données avant de leur donner des adresses. Des URI stables exigent des identifiants valides et uniques. 47 enregistrements n’en avaient pas; le choix honnête était de les exclure et de le dire.
  • Un vrai modèle trouve ce que le modèle simulé ne peut pas trouver. Le modèle simulé demandait toujours 5 résultats. Le vrai modèle en a demandé 10 et a révélé une borne trop élevée.
  • Limites de cette étude. Un jeu de données, un portable, 22 questions écrites par le cours et un modèle simulé. La recherche trouve des mots, pas des produits. Les données s’arrêtent aux rapports du 30 septembre 2026. Windows et Linux n’ont pas été testés.
  • « Introuvable » ne veut pas dire « sans danger ». Les données ne contiennent que des rapports de mesures d’application. Ils arrivent après que la FDA classe un rappel, et 47 enregistrements sont exclus. Chaque réponse dit « dans les données », et l’agent dirige le client vers l’avis de la FDA.
  • Aucun conseil médical. Les instructions du serveur et la requête customer_answer disent au modèle de ne pas en donner. La FDA indique que les données ne sont pas validées.
  • Nommez la source et sa date. Chaque réponse nomme le numéro de rappel, et DATASET.md indique la date d’exportation. Montrez les deux aux personnes qui lisent les réponses.
  • Un rappel est un rapport, pas un jugement. Certains noms d’entreprises sont des noms de personnes. Ne combinez pas les données avec d’autres sources pour vous renseigner sur des personnes.
  • Utilisez les services publics avec respect. --latest récupère un fichier d’openFDA. Ne dirigez pas un test de charge ou un robot d’exploration vers un service de données public.

Ce projet montre ce que les employeurs recherchent chez une personne qui connecte des applications d’IA aux données. Ses capacités répondent à des besoins réels, ses données sont vérifiées et ses limites sont mesurées. Il comprend aussi un test de contrat et une comparaison honnête.

Quoi mettre dans le dépôt :

food-recalls/
README.md what it is, how to run and test it, the results
DATASET.md the source, the licence, the checksum, the changes, the limits
LICENSE MIT, for the code
docs/capability-catalog.md needs, capabilities, bounds, rejected ideas
docs/results.md your numbers: sizes, the comparison, the bound you fixed
recalls_mcp/ store, contracts, server, logs
host/ the course's host with the mock model
contract/capabilities.json the contract that clients see
questions/eval.jsonl the 22 questions and the expected recall events
scripts/ get_data, contract, sizes, compare
tests/ 32 tests
  1. Créez un dépôt Git à partir du dossier de votre projet, puis envoyez-le sur GitHub. .gitignore exclut les données, la base de données et .venv.
  2. Remplissez docs/results.md avec vos propres exécutions. Ajoutez une question de votre choix à questions/eval.jsonl et dites ce qu’elle a montré.
  3. Vérifiez que python -m scripts.get_data et python -m pytest -q réussissent à partir d’un nouveau clone. Indiquez-le dans le README.

Vérifiez votre compréhension

Le résultat médian de get_recall (1 098 caractères) est aussi long que l'enregistrement médian d'openFDA (1 100). Dev dit que les limites sont inutiles. Que répondez-vous?

Afficher la réponse

Une limite ne sert pas à raccourcir les réponses habituelles. Elle donne à chaque réponse un maximum connu. Sans ces limites, le plus grand enregistrement compte 44 645 caractères, onze fois la limite de 4 000 de l’hôte. Avec elles, le plus grand résultat de get_recall parmi les 29 424 rappels compte 3 590 caractères. Un test vérifie les cas les plus volumineux. La médiane importe peu : c’est le pire cas qui fait échouer un hôte.

Vérifiez votre compréhension

Sans la limite de l'hôte, les trois conceptions ont répondu correctement aux 22 questions. Cela rend-il la conception « tout » acceptable?

Afficher la réponse

Non. Pour « listeria », elle a envoyé 8 345 360 caractères au modèle. C’est beaucoup plus qu’un modèle peut lire dans une seule requête. Retirer la limite de l’hôte ne fait que déplacer la défaillance de l’hôte vers le modèle. La conception avec résumés a répondu correctement aux 22 questions, avec une médiane de 2 868 caractères lus. Chacun de ses résultats reste sous 4 000 caractères, quel que soit l’hôte.

Vérifiez votre compréhension

Vérification pratique : qu'affichent ces commandes avec le projet terminé? (a) python -m scripts.contract (b) l'appel de search_recalls par l'interface en ligne de commande d'Inspector avec limit=11 (c) python -m host 'Is there a recall of dragon fruit gummies?'

Afficher la réponse

(a) The server matches contract/capabilities.json. (Le serveur respecte contract/capabilities.json.) (b) Une erreur d’outil, avec le code de sortie 5 : « Input should be less than or equal to 5 » (l’entrée doit être inférieure ou égale à 5). Le schéma permet un limit (limite) de 1 à 5. (c) I found no FDA food recall that matches "dragon fruit gummies" in the data. (Je n’ai trouvé aucun rappel alimentaire de la FDA correspondant à « dragon fruit gummies » dans les données.) La réponse dit « dans les données », jamais « sans danger ».

Récapitulatif

  • Vous avez d’abord vérifié les données : la somme de contrôle SHA-256 et 47 enregistrements sans numéro de rappel valide, exclus et répertoriés.
  • Vous avez conçu les capacités selon les besoins des gens : deux outils en lecture seule, un modèle de ressource, une liste de ressources limitée et une requête.
  • Les résumés d’abord, les détails sur demande : chaque réponse d’outil a un maximum connu, mesuré sur les 29 424 rappels.
  • Un test de contrat, 32 tests au total et Inspector dans sa version moderne ont montré ce que les clients voient.
  • Selon une même mesure, seule la conception avec résumés a répondu aux 22 questions en respectant la limite de l’hôte. Un vrai modèle a révélé une limite trop élevée, et vous l’avez corrigée.

Ensuite, l’autre étude de cas : trouvez et corrigez les faiblesses d’un serveur MCP volontairement peu robuste.

Leçon suivante : Revue de sécurité d'une intégration MCP