mcp-builder

Guide de développement de serveur MCP

Aperçu

Créez des serveurs MCP (Model Context Protocol) qui permettent aux LLM d'interagir avec des services externes via des outils bien conçus. La qualité d'un serveur MCP se mesure à sa capacité à permettre aux LLM d'accomplir des tâches concrètes.

---

Processus

🚀 Flux de travail général

La création d'un serveur MCP de haute qualité implique quatre phases principales :

Phase 1 : Recherche approfondie et planification

1.1 Comprendre la conception MCP moderne

Couverture API vs Outils de workflow : Équilibrez la couverture complète des points de terminaison API avec des outils de workflow spécialisés. Les outils de workflow peuvent être plus pratiques pour des tâches spécifiques, tandis qu'une couverture complète offre aux agents la flexibilité de composer des opérations. Les performances varient selon le client : certains clients bénéficient d'une exécution de code qui combine des outils de base, tandis que d'autres fonctionnent mieux avec des workflows de plus haut niveau. En cas d'incertitude, privilégiez une couverture API complète.

Nommage et découvrabilité des outils : Des noms d'outils clairs et descriptifs aident les agents à trouver rapidement les bons outils. Utilisez des préfixes cohérents (par ex., github_create_issue, github_list_repos) et un nommage orienté action.

Gestion du contexte : Les agents bénéficient de descriptions d'outils concises et de la possibilité de filtrer/paginer les résultats. Concevez des outils qui renvoient des données ciblées et pertinentes. Certains clients prennent en charge l'exécution de code, ce qui peut aider les agents à filtrer et traiter les données efficacement.

Messages d'erreur exploitables : Les messages d'erreur doivent guider les agents vers des solutions avec des suggestions spécifiques et des prochaines étapes.

1.2 Étudier la documentation du protocole MCP

Naviguer dans la spécification MCP :

Commencez par le plan du site pour trouver les pages pertinentes : https://modelcontextprotocol.io/sitemap.xml

Ensuite, récupérez des pages spécifiques avec le suffixe .md pour le format markdown (par ex., https://modelcontextprotocol.io/specification/draft.md).

Pages clés à consulter :

• Aperçu de la spécification et architecture
• Mécanismes de transport (HTTP streamable, stdio)
• Définitions des outils, ressources et invites

1.3 Étudier la documentation du framework

Stack recommandée :

• Langage : TypeScript (support SDK de haute qualité et bonne compatibilité dans de nombreux environnements d'exécution, par ex. MCPB. De plus, les modèles d'IA génèrent bien du code TypeScript, bénéficiant de son utilisation répandue, de son typage statique et de ses bons outils de linting).
• Transport : HTTP streamable pour les serveurs distants, utilisant JSON sans état (plus simple à scaler et à maintenir, contrairement aux sessions avec état et aux réponses en streaming). stdio pour les serveurs locaux.

Charger la documentation du framework :

• Bonnes pratiques MCP : 📋 Voir les bonnes pratiques - Directives essentielles

Pour TypeScript (recommandé) :

Le SDK TypeScript a deux versions majeures. Choisissez-en une avant d'écrire du code :

• v2 (@modelcontextprotocol/server) : la version stable actuelle. Utilisez-la pour les nouveaux serveurs.
• v1 (@modelcontextprotocol/sdk) : ne reçoit que des correctifs de bugs et de sécurité. Utilisez-la uniquement si le package.json du projet dépend déjà de @modelcontextprotocol/sdk, ou migrez ce projet avec npx @modelcontextprotocol/codemod@latest v1-to-v2 .

Si le projet utilise déjà v1, informez-en l'utilisateur une fois, en une ou deux phrases, que v2 (@modelcontextprotocol/server) est la version stable actuelle, que v1 ne reçoit que des correctifs de bugs et de sécurité, et que npx @modelcontextprotocol/codemod@latest v1-to-v2 . migre le projet. Continuez ensuite avec v1 sauf si l'utilisateur demande la migration.

Ne mélangez pas les deux dans un même projet : les exemples de code v1 (importations depuis @modelcontextprotocol/sdk/...) ne s'appliquent pas à v2.

• SDK TypeScript (v2) : Utilisez WebFetch pour charger https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md ; l'index complet de la documentation est https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
• ⚡ Guide TypeScript (v2) - Modèles et exemples TypeScript
• Pour les projets v1 uniquement : https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md et le Guide TypeScript (v1)

Pour Python :

• SDK Python : Utilisez WebFetch pour charger https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Guide Python - Modèles et exemples Python

1.4 Planifier votre implémentation

Comprendre l'API : Consultez la documentation de l'API du service pour identifier les points de terminaison clés, les exigences d'authentification et les modèles de données. Utilisez la recherche web et WebFetch si nécessaire.

Sélection des outils : Privilégiez une couverture API complète. Listez les points de terminaison à implémenter, en commençant par les opérations les plus courantes.

---

Phase 2 : Implémentation

2.1 Configurer la structure du projet

Consultez les guides spécifiques au langage pour la configuration du projet :

• ⚡ Guide TypeScript (v2) - Structure du projet, package.json, tsconfig.json (v1 pour les projets v1 existants)
• 🐍 Guide Python - Organisation des modules, dépendances

2.2 Implémenter l'infrastructure de base

Créez des utilitaires partagés :

• Client API avec authentification
• Aides à la gestion des erreurs
• Mise en forme des réponses (JSON/Markdown)
• Support de la pagination

2.3 Implémenter les outils

Pour chaque outil :

Schéma d'entrée :

• Utilisez Zod (TypeScript) ou Pydantic (Python)
• Incluez des contraintes et des descriptions claires
• Ajoutez des exemples dans les descriptions de champs

Schéma de sortie :

• Définissez outputSchema lorsque c'est possible pour des données structurées
• Utilisez structuredContent dans les réponses des outils (fonctionnalité du SDK TypeScript)
• Aide les clients à comprendre et traiter les sorties des outils

Description de l'outil :

• Résumé concis de la fonctionnalité
• Descriptions des paramètres
• Schéma du type de retour

Implémentation :

• Async/await pour les opérations d'E/S
• Gestion appropriée des erreurs avec des messages exploitables
• Support de la pagination le cas échéant
• Renvoi à la fois du contenu textuel et des données structurées lors de l'utilisation de SDK modernes

Annotations :

• readOnlyHint : true/false
• destructiveHint : true/false
• idempotentHint : true/false
• openWorldHint : true/false

---

Phase 3 : Révision et test

3.1 Qualité du code

Vérifiez :

• Absence de code dupliqué (principe DRY)
• Gestion cohérente des erreurs
• Couverture complète des types
• Descriptions claires des outils

3.2 Compilation et test

TypeScript :

• Exécutez npm run build pour vérifier la compilation
• Projets v2 : exécutez le script d'auto-vérification du guide v2 contre le serveur compilé
• Testez avec MCP Inspector : npx @modelcontextprotocol/inspector

Python :

• Vérifiez la syntaxe : python -m py_compile votre_serveur.py
• Testez avec MCP Inspector

Consultez les guides spécifiques au langage pour des approches de test détaillées et des listes de contrôle qualité.

---

Phase 4 : Créer des évaluations

Après avoir implémenté votre serveur MCP, créez des évaluations complètes pour tester son efficacité.

Chargez le ✅ Guide d'évaluation pour des directives complètes d'évaluation.

4.1 Comprendre l'objectif de l'évaluation

Utilisez les évaluations pour tester si les LLM peuvent utiliser efficacement votre serveur MCP pour répondre à des questions réalistes et complexes.

4.2 Créer 10 questions d'évaluation

Pour créer des évaluations efficaces, suivez le processus décrit dans le guide d'évaluation :

1. Inspection des outils : Listez les outils disponibles et comprenez leurs capacités
2. Exploration du contenu : Utilisez des opérations EN LECTURE SEULE pour explorer les données disponibles
3. Génération de questions : Créez 10 questions complexes et réalistes
4. Vérification des réponses : Résolvez chaque question vous-même pour vérifier les réponses

4.3 Exigences d'évaluation

Assurez-vous que chaque question :

• Indépendante : Ne dépend pas d'autres questions
• En lecture seule : Nécessite uniquement des opérations non destructives
• Complexe : Nécessite plusieurs appels d'outils et une exploration approfondie
• Réaliste : Basée sur des cas d'utilisation réels qui intéressent les humains
• Vérifiable : Réponse unique et claire pouvant être vérifiée par comparaison de chaînes
• Stable : La réponse ne change pas avec le temps

4.4 Format de sortie

Créez un fichier XML avec cette structure :

<evaluation>
  <qa_pair>
    <question>Trouvez des discussions sur les lancements de modèles d'IA avec des noms de code d'animaux. Un modèle nécessitait une désignation de sécurité spécifique utilisant le format ASL-X. Quel nombre X était déterminé pour le modèle nommé d'après un chat sauvage tacheté ?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Plus de qa_pairs... -->
</evaluation>

---

Fichiers de référence

📚 Bibliothèque de documentation

Chargez ces ressources selon les besoins pendant le développement :

Documentation MCP principale (À charger en premier)

• Protocole MCP : Commencez par le plan du site à https://modelcontextprotocol.io/sitemap.xml, puis récupérez des pages spécifiques avec le suffixe .md
• 📋 Bonnes pratiques MCP - Directives MCP universelles incluant :
  • Conventions de nommage des serveurs et outils
  • Directives de format de réponse (JSON vs Markdown)
  • Bonnes pratiques de pagination
  • Sélection du transport (HTTP streamable vs stdio)
  • Normes de sécurité et de gestion des erreurs

Documentation SDK (À charger pendant les phases 1/2)

• SDK Python : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK TypeScript (v2) : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md ; index complet de la documentation à https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
• SDK TypeScript (v1, projets v1 existants uniquement) : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md

Guides d'implémentation spécifiques au langage (À charger pendant la phase 2)

• 🐍 Guide d'implémentation Python - Guide Python/FastMCP complet avec :

  • Modèles d'initialisation de serveur
  • Exemples de modèles Pydantic
  • Enregistrement d'outils avec @mcp.tool
  • Exemples complets fonctionnels
  • Liste de contrôle qualité

• ⚡ Guide d'implémentation TypeScript (SDK v2) - Guide TypeScript complet pour @modelcontextprotocol/server avec :

  • Configuration du projet et la fabrique de serveur
  • Conception d'outils : schémas Zod 4, formats de sortie, pagination, erreurs
  • Un exemple complet servant stdio et HTTP streamable, plus une authentification par bearer
  • Ressources, invites et notifications
  • Un script d'auto-vérification pour valider le serveur compilé
  • Liens vers des exemples SDK pour des fonctionnalités avancées
  • Une table de traduction v1 → v2, des étapes de migration et une liste de contrôle qualité

• ⚡ Guide d'implémentation TypeScript (SDK v1) - Le guide équivalent pour les projets existants @modelcontextprotocol/sdk

Guide d'évaluation (À charger pendant la phase 4)

• ✅ Guide d'évaluation - Guide complet de création d'évaluations avec :
  • Directives de création de questions
  • Stratégies de vérification des réponses
  • Spécifications du format XML
  • Exemples de questions et réponses
  • Exécution d'une évaluation avec les scripts fournis