Aller au contenu
English

Choisir une trousse SDK maintenue

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

Où nous en sommes

Dans le module 2, nous avons conçu sur papier chaque capacité de support-mcp : outils, ressources et une requête. Maintenant, une bibliothèque doit parler le protocole pour nous et transformer ces contrats en vrai serveur. Mais toutes les trousses SDK ne parlent pas notre révision, et certaines ne sont plus maintenues. Dans cette leçon, nous choisissons une trousse SDK avec quatre questions et nous fixons sa version, comme on choisit le bon adaptateur de voyage.

Leçon 7 sur 22 · MCP : connecter les applications d'IA aux outils et aux donnéesChoisir une trousse SDK maintenue

Ce que vous saurez faire

Choisissez la bibliothèque qui communiquera par MCP pour votre serveur, et rendez ce choix reproductible. Vérifiez que la trousse SDK est officielle, qu’elle utilise la révision choisie et qu’elle est toujours maintenue. Installez ensuite une version exacte dans un nouvel environnement, puis prouvez que cet environnement fonctionne.

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

Ce que vous devez savoir

Votre projet

  • ~/projects/support-mcp à la fin du module 2, avec les contrats des capacités dans support_mcp/contracts.py. Avec l’environnement virtuel actif, python -m pytest -q affiche 20 passed (20 tests réussis). Si votre projet ne fonctionne plus, copiez l’instantané end-of-m02 (voir Réinitialisation à la fin de cette leçon).
  • Une connexion Internet : les paquets occupent environ 85 Mo sur le disque. Aucun compte ni aucune clé.

Imaginez un voyage dans un autre pays. Le chargeur de votre portable a un type de fiche, mais les prises murales là-bas sont différentes. Il vous faut un adaptateur.

Vous n’achetez pas le premier adaptateur que vous voyez. Vérifiez d’abord la norme : le pays utilise un certain type de prise, et l’adaptateur doit y convenir. Vérifiez ensuite le fabricant : une marque connue qui vend encore des pièces de rechange est plus sûre qu’une marque inconnue. Notez le modèle exact pour pouvoir racheter le même. Et testez-le à la maison, avec votre portable, avant de partir.

Quatre vérifications : la norme, le fabricant, le modèle exact et un test à la maison. Choisir une trousse SDK pour MCP demande les mêmes vérifications.

Le problème : « J’ai trouvé un paquet appelé mcp-something »

Section intitulée « Le problème : « J’ai trouvé un paquet appelé mcp-something » »

Tomás veut démarrer le serveur aujourd’hui. Il cherche « mcp server python » dans l’index des paquets et en trouve plusieurs. L’un d’eux a un beau README. Il le montre à Amira.

Amira pose quatre questions. Qui le publie? Quelle révision du protocole utilise-t-il? Quand sa dernière version est-elle sortie? Et que nous donnera pip install le mois prochain?

Tomás ne trouve aucune réponse dans le README. L’exemple commence par une requête initialize (initialiser) et la révision 2025-06-18. Vous avez vu dans Tenir compte des versions qu’il s’agit de l’ancienne négociation initiale. Le paquet pourrait encore fonctionner, car la trousse SDK officielle accepte les anciens clients. Mais personne ne sait s’il recevra des correctifs, ou s’il utilisera un jour la révision 2026-07-28.

Le risque ne concerne pas seulement le protocole. Un serveur est une porte vers les billets de soutien de Larkfield. Si la bibliothèque qui ouvre cette porte contient une faille de sécurité, quelqu’un doit la corriger rapidement. Une bibliothèque sans nouvelle version depuis un an n’offre aucune garantie à ce sujet.

Une trousse SDK (trousse de développement logiciel) est la bibliothèque qui écrit et lit les messages MCP pour vous. Votre code indique « cette fonction est un outil », et la trousse SDK produit les bons messages. La trousse SDK détermine donc la révision du protocole utilisée par votre serveur et sa façon de répondre aux erreurs.

Avant de dépendre d’une trousse SDK, posez quatre questions. Elles correspondent aux vérifications de l’adaptateur de voyage :

  1. Est-elle officielle? Le projet MCP présente ses trousses SDK officielles, une par langage, sur modelcontextprotocol.io. Chacune a un niveau, qui indique publiquement le soutien offert. Le niveau 1 signifie une prise en charge complète du protocole et des délais de réponse fixes.
  2. Utilise-t-elle votre révision? Les notes de version de la trousse SDK, ou un court script, indiquent les révisions prises en charge.
  3. Est-elle maintenue? Consultez son historique des versions. Des versions régulières signifient que quelqu’un corrige les bogues et suit l’évolution du protocole.
  4. Sa version est-elle fixée et testée ici? Installez une version exacte dans un nouvel environnement, puis exécutez vos tests.
Quatre cases alignées, chacune avec une question et la réponse de Larkfield dessous. 1. Est-ce une trousse SDK officielle? modelcontextprotocol.io classe la trousse SDK Python au niveau 1 : protocole complet, triage en 2 jours ouvrables. 2. Utilise-t-elle votre révision? mcp 2.3.0 utilise 2026-07-28 et accepte l'ancienne négociation initiale de 2024-11-05 à 2025-11-25. 3. Est-elle maintenue? 36 versions dans les 12 mois précédant la version 2.3.0, la plus récente. La série 1.x est en maintenance. 4. Sa version est-elle fixée et testée ici? mcp==2.3.0 dans requirements.txt, nouvel environnement virtuel, pip check OK, python -m pytest -q : 20 passed. Une case rouge dessous : un non à n'importe quelle question signifie choisir une autre trousse SDK, ou noter le manque et le travail nécessaire, par exemple une trousse SDK communautaire sans nouvelle version depuis un an, ou qui ne connaît que 2025-06-18.
Les quatre questions, avec les réponses pour le serveur de Larkfield. Un seul non justifie de s'arrêter et de réfléchir.
Description textuelle du diagramme

Quatre questions, chacune avec la réponse de Larkfield :

  1. Est-ce une trousse SDK officielle? modelcontextprotocol.io classe la trousse SDK Python au niveau 1 : protocole complet et triage des problèmes en 2 jours ouvrables.
  2. Utilise-t-elle votre révision? mcp 2.3.0 utilise 2026-07-28 et accepte l’ancienne négociation initiale de 2024-11-05 à 2025-11-25.
  3. Est-elle maintenue? 36 versions dans les 12 mois précédant la version 2.3.0, la plus récente. La série 1.x est en maintenance.
  4. Sa version est-elle fixée et testée ici? mcp==2.3.0 dans requirements.txt, nouvel environnement virtuel, pip check ne signale aucun problème, et python -m pytest -q affiche 20 passed.

Un « non » à n’importe quelle question : choisissez une autre trousse SDK, ou notez le manque et le travail nécessaire. Deux exemples : une trousse SDK communautaire sans nouvelle version depuis un an, ou qui ne connaît que la révision 2025-06-18.

Le projet MCP publie une liste de trousses SDK officielles. Lors de la rédaction de ce cours, elle comptait dix langages. TypeScript, Python, C#, Go, Rust et Ruby étaient au niveau 1, et Java au niveau 2. Swift, PHP et Kotlin étaient au niveau 3. Les niveaux peuvent changer, alors vérifiez la page actuelle avant de choisir.

Les règles du projet définissent concrètement chaque niveau :

Niveau 1 : prise en charge complète Niveau 2 : vers une prise en charge complète Niveau 3 : expérimental
Tests de conformité automatisés 100 % réussis 80 % réussis aucun minimum
Nouvelles fonctionnalités du protocole avant la publication de la nouvelle révision dans les 6 mois aucun engagement
Triage des problèmes dans les 2 jours ouvrables dans le mois aucune exigence
Correction d’un bogue critique dans les 7 jours dans les deux semaines aucune exigence
Version stable obligatoire, avec des versions clairement définies au moins une non obligatoire

Les tests de conformité forment une suite de tests commune. Elle envoie des messages standard à une trousse SDK et vérifie ses réponses. Une trousse SDK de niveau 1 doit tous les réussir. Cela vous donne une garantie qu’un README ne peut pas offrir.

Pour Larkfield, la réponse est simple. Le serveur est en Python, et la trousse SDK Python officielle est au niveau 1. Son paquet sur PyPI, l’index des paquets Python, porte le nom court mcp. Sa licence est MIT, ce qui permet à Larkfield de l’utiliser dans son propre produit.

Vous avez choisi la révision 2026-07-28 au module 1, car c’est la révision actuelle. La trousse SDK doit la prendre en charge. Votre projet contient déjà un script qui interroge la trousse SDK installée, scripts/versions.py. Vous l’exécuterez dans les étapes ci-dessous. Il affiche deux lignes qui répondent à cette question :

newest revision the SDK speaks: 2026-07-28
older revisions it still accepts (initialize handshake): 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25

La trousse SDK 2.3.0 répond donc à un client actuel comme à un ancien. C’est important pour Larkfield. Certaines applications d’IA du personnel peuvent encore envoyer l’ancienne négociation initiale initialize, et le serveur ne doit pas les refuser.

Une bibliothèque maintenue possède un historique des versions que vous pouvez consulter. PyPI conserve la date de chaque version. Voici l’historique du paquet mcp, tiré des données de PyPI :

Une ligne du temps de juin 2025 à octobre 2026, avec trois rangées de points, un par version du paquet mcp sur PyPI. Rangée 1.x : beaucoup de points de juin 2025 à décembre 2025, puis moins : janvier, avril, mai, juin, juillet, août et septembre 2026; le dernier est 1.30.0. Rangée tests 2.x : six points vides de juin à la fin juillet 2026, le premier étiqueté 2.0.0a1. Rangée 2.x : 2.0.0 le même jour que la ligne pointillée de la révision 2026-07-28, puis quatre autres points jusqu'à 2.3.0 en octobre 2026, étiqueté ce cours. Une deuxième ligne pointillée marque la révision 2025-11-25. Une note : chaque point représente une version de la trousse SDK Python MCP officielle sur PyPI, 36 dans les 12 mois précédant 2.3.0; 1.x reçoit encore des versions après 2.0.0; les points vides sont les versions de test alpha, bêta et candidates de 2.0.0.
Chaque version de la trousse SDK Python officielle depuis juin 2025. La version 2.0.0 est sortie le même jour que la révision 2026-07-28.
Description textuelle du diagramme

Un point par version du paquet mcp sur PyPI, de juin 2025 à octobre 2026, en trois rangées :

  • 1.x : beaucoup de versions de juin à décembre 2025, puis environ une par mois en 2026. La plus récente est 1.30.0, en septembre 2026.
  • Tests 2.x : six versions de test (alpha, bêta et candidate) de juin à la fin juillet 2026. La première est 2.0.0a1.
  • 2.x : 2.0.0 le 28 juillet 2026, le même jour que la révision 2026-07-28. Puis 2.0.1, 2.1.0, 2.1.1, 2.2.0 et 2.3.0 (octobre 2026), la version de ce cours.

Les lignes pointillées marquent les révisions 2025-11-25 et 2026-07-28. Dans les 12 mois précédant 2.3.0, PyPI montre 36 versions.

Lisez l’image de gauche à droite. Les versions sortaient toutes les semaines ou toutes les deux semaines en 2025. Les versions de test de 2.0 sont apparues dès juin 2026 pour permettre d’essayer la nouvelle version majeure tôt. La version 2.0.0 est sortie le même jour que la nouvelle révision : les responsables l’avaient préparée avant la révision finale. C’est la promesse du niveau 1 en pratique.

Remarquez aussi la rangée 1.x. Elle ne s’est pas arrêtée à 2.0.0 : 1.29.0, 1.29.1 et 1.30.0 sont sorties après. La série 1.x est en maintenance. Elle reçoit des correctifs de bogues critiques et de sécurité pour protéger les anciens projets. Mais les nouveautés du protocole vont dans 2.x. Voilà pourquoi les anciens tutoriels fonctionnent encore un certain temps, et pourquoi il faut éviter 1.x pour un nouveau projet.

Vous pouvez voir la même liste dans un terminal. python -m pip index versions mcp affiche toutes les versions sur PyPI, de la plus récente à la plus ancienne. Lors de la rédaction de ce cours, la liste commençait par 2.3.0, 2.2.0, 2.1.1, 2.1.0, 2.0.1, 2.0.0, 1.30.0, ….

La dernière vérification vous revient. Une version fixée est une version exacte dans vos exigences : mcp==2.3.0, pas mcp ni mcp>=2. Avec une version fixée, chaque installation du projet reçoit la même trousse SDK. Sinon, pip installe la version la plus récente le jour de l’installation. Votre serveur changerait sans aucune modification de votre code.

Votre projet fixe déjà la version de la trousse SDK, depuis Tenir compte des versions :

requirements.txt
# The MCP Python SDK. It brings Starlette, uvicorn, httpx2, pydantic, PyJWT and cryptography.
mcp==2.3.0
PyJWT[crypto]==2.15.1
requirements-dev.txt
-r requirements.txt
pytest==9.1.1
ruff==0.17.0

requirements.txt contient ce dont le serveur a besoin pour fonctionner. requirements-dev.txt ajoute les outils de développement : pytest pour les tests, et ruff, qui vérifie le style du code. Sa première ligne, -r requirements.txt, inclut l’autre fichier : une seule commande installe donc les deux.

Un environnement testé est un nouvel environnement virtuel, créé uniquement à partir de ces fichiers, où les tests réussissent. Le mot « nouvel » compte. Un ancien environnement peut contenir des paquets d’expérimentation qui masquent une ligne manquante dans les exigences. Vous en créez donc un nouveau, et vous le vérifiez.

  1. Ouvrez un terminal dans le dossier de votre projet, ~/projects/support-mcp. Si un environnement virtuel est actif, quittez-le :

    Fenêtre de terminal
    deactivate

    Si aucun environnement n’est actif, la commande affiche une erreur. Ce n’est pas un problème.

  2. Renommez l’ancien environnement pour pouvoir y revenir :

    Fenêtre de terminal
    mv .venv .venv-old
  3. Créez un nouvel environnement avec Python 3.12, puis activez-le :

    Fenêtre de terminal
    python3.12 -m venv .venv
    source .venv/bin/activate

    Vérifiez-le : python --version affiche Python 3.12.13, ou une autre version 3.12.

  4. Installez les exigences aux versions fixées :

    Fenêtre de terminal
    python -m pip install -r requirements-dev.txt

    La dernière ligne nomme chaque paquet installé par pip. Elle commence ainsi :

    Successfully installed PyJWT-2.15.1 annotated-types-0.8.0 anyio-4.15.1 attrs-26.1.0 cffi-2.1.1 click-8.5.0 cryptography-50.0.2 …

    La ligne complète nomme 34 paquets. Parmi eux figurent mcp-2.3.0 et mcp-types-2.3.0, la trousse SDK et ses types de messages.

  5. Examinez la trousse SDK installée :

    Fenêtre de terminal
    python -m pip show mcp
    Name: mcp
    Version: 2.3.0
    Summary: Model Context Protocol SDK
    Home-page: https://modelcontextprotocol.io
    Author: Model Context Protocol a Series of LF Projects, LLC.
    Author-email:
    License: MIT
    Location: …/support-mcp/.venv/lib/python3.12/site-packages
    Requires: anyio, httpx2, jsonschema, mcp-types, opentelemetry-api, pydantic, pyjwt, python-multipart, sse-starlette, starlette, typing-extensions, typing-inspection, uvicorn
    Required-by:

    L’auteur est le projet MCP : il s’agit donc du paquet officiel. Requires (dépendances requises) liste les 13 paquets dont la trousse SDK elle-même a besoin.

  6. Vérifiez que les paquets installés sont compatibles entre eux :

    Fenêtre de terminal
    python -m pip check
    No broken requirements found.
  7. Demandez à la trousse SDK quelles révisions elle utilise :

    Fenêtre de terminal
    python -m scripts.versions
    specification revision (this project): 2026-07-28
    MCP Python SDK (pinned): 2.3.0
    MCP Python SDK (installed): 2.3.0
    newest revision the SDK speaks: 2026-07-28
    older revisions it still accepts (initialize handshake): 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25
    Python: 3.12.13
  8. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q
    .................... [100%]
    20 passed in 1.64s

    Votre durée sera différente. Le résultat doit être 20 passed.

  9. Si chaque étape a réussi, supprimez l’ancien environnement :

    Fenêtre de terminal
    rm -rf .venv-old

Vous avez maintenant les quatre réponses par écrit. La trousse SDK est officielle (étape 5), utilise votre révision (étape 7), et sa version est fixée et testée (étapes 4, 6 et 8). L’historique des versions a répondu à la dernière question.

Comptez encore : vos exigences fixent les versions de 4 paquets, mcp, PyJWT, pytest et ruff. pip en a installé 34. Les 30 autres les accompagnaient, et pip a choisi leurs versions dans les plages permises par la trousse SDK. Par exemple, la trousse SDK demande anyio>=4.9, et pip a installé anyio-4.15.1, la version la plus récente ce jour-là.

Une installation le mois prochain pourrait donc recevoir un anyio plus récent, avec le même mcp==2.3.0. Généralement, c’est sans danger, car ces plages permettent de recevoir des correctifs. Rarement, un paquet plus récent cause un problème. Vos tests vous protègent : exécutez-les après chaque nouvelle installation.

Certaines équipes figent aussi toutes les versions. python -m pip freeze affiche les 34 paquets avec leurs versions exactes, et elles conservent cette liste dans un fichier. Ce cours ne le fait pas, pour garder le projet simple. Pour un serveur en production, c’est un bon choix, car la même liste donne toujours le même environnement.

Amira ajoute trois phrases aux notes du projet pour qu’un prochain développeur comprenne le choix :

Nous utilisons la trousse SDK Python MCP officielle, mcp==2.3.0 (niveau 1, MIT), car elle utilise la révision 2026-07-28 et accepte la négociation initiale des anciens clients. Nous passons à une version plus récente de la trousse SDK uniquement sur une branche, après avoir lu ses notes de version et exécuté tous les tests. Nous n’utilisons pas la trousse SDK 1.x, en maintenance, ni les paquets communautaires, sauf si la trousse SDK officielle ne répond pas à un besoin.

Tomás demande : « Alors, le paquet que j’ai trouvé est mauvais? » Amira répond : « Pas mauvais, mais inconnu. Si on en a besoin un jour, on répond aux mêmes quatre questions et on note le manque. »

Utilisez les quatre questions pour chaque bibliothèque qui communique avec l’extérieur pour vous : trousse SDK MCP, client HTTP, pilote de base de données. Elles prennent quelques minutes et évitent toute une catégorie de surprises.

Les coûts sont faibles, mais réels :

  • Les mises à niveau vous reviennent. Une version fixée ne change jamais toute seule. Planifiez une courte révision quand une nouvelle version de la trousse SDK paraît, et lisez ses notes de version. Une nouvelle version majeure, comme le passage de 1.x à 2.x, renomme des éléments et demande un vrai travail.
  • Un nouvel environnement prend du temps. Ici, quelques secondes ont suffi, car pip avait les fichiers dans son cache. La première fois, il télécharge environ 85 Mo.
  • Une trousse SDK officielle n’est pas une revue de sécurité. Elle utilise correctement le protocole. Votre code décide toujours si l’appelant peut lire un billet, à partir du module 5.

Erreur courante

No matching distribution found for mcp==2.3.0 (aucune distribution compatible trouvée pour mcp==2.3.0)

Symptôme : l’installation s’arrête au premier paquet :

ERROR: Could not find a version that satisfies the requirement mcp==2.3.0 (from versions: none)
ERROR: No matching distribution found for mcp==2.3.0

Cause : l’environnement utilise une version de Python trop ancienne. Sur macOS, /usr/bin/python3 est Python 3.9.6, et la trousse SDK exige Python 3.10 ou une version ultérieure. pip masque toutes les versions incompatibles. Il affiche donc « from versions : none » (aucune version disponible).

Solution : supprimez .venv, puis recréez-le avec python3.12 -m venv .venv (Windows : py -3.12 -m venv .venv). Vérifiez avec python --version avant l’installation.

Erreur courante

error : externally-managed-environment (erreur : environnement géré par un système externe)

Symptôme : pip install refuse de s’exécuter :

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.

Cause : aucun environnement virtuel n’est actif. pip a donc tenté d’installer les paquets dans le Python que Homebrew gère. Homebrew le protège, et c’est une bonne chose : les outils système en dépendent.

Solution : activez l’environnement du projet (source .venv/bin/activate; Windows : .venv\Scripts\Activate.ps1), puis relancez l’installation. N’ajoutez jamais --break-system-packages pour faire disparaître le message.

Réinitialisation. Si votre projet ne fonctionne plus, gardez vos fichiers et repartez de l’instantané. Renommez votre dossier support-mcp-old. Copiez ensuite nextia-learning-labs/C28/snapshots/end-of-m02 vers support-mcp, comme dans La place de MCP, et refaites les étapes de cette leçon.

Vérifiez votre compréhension

Nommez les quatre questions à poser avant de dépendre d'une trousse SDK MCP. Donnez les preuves de Larkfield pour chacune.

Afficher la réponse
  1. Est-elle officielle? Le projet MCP classe la trousse SDK Python, le paquet mcp, dans Tier 1 (niveau 1). pip show mcp indique le projet MCP comme auteur.
  2. Prend-elle en charge votre révision? python -m scripts.versions indique que la trousse SDK 2.3.0 utilise la révision 2026-07-28 et accepte la négociation initiale de quatre révisions antérieures.
  3. Est-elle maintenue? PyPI affiche 36 versions publiées dans les 12 mois précédant la version 2.3.0. La version 2.0.0 est sortie le jour de la révision 2026-07-28.
  4. Sa version est-elle fixée et testée ici? mcp==2.3.0 figure dans requirements.txt. Un environnement neuf réussit pip check, et python -m pytest -q affiche 20 passed (20 tests réussis).

Vérifiez votre compréhension

Prédisez : un collègue remplace la ligne mcp==2.3.0 par mcp, sans version, dans requirements.txt. Aujourd'hui, une nouvelle installation donne le même résultat. Que peut-il arriver dans trois mois, et quel script ou test vous l'indique?

Afficher la réponse

Sans version fixée, pip installe la version la plus récente de mcp le jour de chaque installation. Dans trois mois, ce pourrait être une version plus récente, peut-être une nouvelle version majeure avec des éléments renommés. Le code du serveur ne change pas, mais son comportement peut changer. python -m scripts.versions afficherait WARNING (avertissement), car la version installée diffère de SDK_VERSION dans support_mcp/__init__.py. Le test test_the_installed_sdk_is_the_pinned_one échouerait. Gardez la version fixée et changez-la volontairement.

Vérifiez votre compréhension

Vérification pratique : créez un environnement neuf à partir de requirements-dev.txt. Qu'affichent pip check et python -m pytest -q, et combien de paquets pip a-t-il installés?

Afficher la réponse

pip check affiche No broken requirements found. (aucune dépendance non satisfaite), et python -m pytest -q se termine par 20 passed. La ligne Successfully installed … (installation réussie) nomme 34 paquets : les 4 dont les exigences fixent la version, et leurs 30 dépendances. Si le nombre de tests diffère, vérifiez que votre projet correspond à la fin du module 2. Vérifiez ensuite que l’environnement est bien le nouveau : python -m pip show mcp doit afficher Version: 2.3.0.

Récapitulatif

  • Une trousse SDK écrit et lit les messages du protocole pour vous. Elle détermine donc la révision que votre serveur utilise.
  • Posez quatre questions. Officielle : la liste du projet MCP, Tier 1 pour Python. Votre révision : la version 2.3.0 utilise 2026-07-28. Maintenue : 36 versions publiées en 12 mois. Version fixée et testée : mcp==2.3.0, un environnement neuf, 20 passed.
  • Fixer la version de la trousse SDK ne fixe pas celle de ses 30 dépendances. Exécutez les tests après chaque nouvelle installation.
  • La trousse SDK 1.x est en maintenance. Reconnaissez-la dans les anciens tutoriels et ne l’utilisez pas pour commencer un nouveau travail.

Votre projet dispose d’un environnement neuf et testé. Vous allez maintenant examiner ce que la trousse SDK écrit pour vous : les messages JSON-RPC.

Leçon suivante : Les messages JSON-RPC