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 grâce à des tools bien conçus. La qualité d'un serveur MCP se mesure par sa capacité à permettre aux LLM d'accomplir des tâches concrètes.

Processus

🚀 Workflow de haut niveau

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

Phase 1 : Recherche approfondie et planification

1.1 Comprendre la conception MCP moderne

Couverture API vs. Tools de workflow : Équilibrez la couverture complète des endpoints API avec des tools de workflow spécialisés. Les tools de workflow peuvent être plus pratiques pour des tâches spécifiques, tandis que la couverture complète donne aux agents la flexibilité de composer des opérations. Les performances varient selon le client — certains clients bénéficient de l'exécution de code qui combine des tools basiques, tandis que d'autres fonctionnent mieux avec des workflows de plus haut niveau. En cas de doute, privilégiez la couverture API complète.

Nommage et découverte des tools : Des noms de tools clairs et descriptifs aident les agents à trouver rapidement les bons tools. Utilisez des préfixes cohérents (par exemple, github_create_issue, github_list_repos) et un nommage orienté vers l'action.

Gestion du contexte : Les agents bénéficient de descriptions concises des tools et de la capacité à filtrer/paginer les résultats. Concevez des tools qui retournent des données ciblées et pertinentes. Certains clients supportent l'exécution de code qui peut aider les agents à filtrer et traiter les données efficacement.

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

1.2 Étudier la documentation du protocole MCP

Naviguer la spécification MCP :

Commencez par le sitemap 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 exemple, https://modelcontextprotocol.io/specification/draft.md).

Pages clés à consulter :

• Aperçu de la spécification et architecture
• Mécanismes de transport (HTTP diffusable, stdio)
• Définitions des tools, ressources et prompts

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 exemple MCPB. De plus, les modèles IA sont bons pour générer du code TypeScript, bénéficiant de son utilisation généralisée, du typage statique et des bons outils de linting)
• Transport : HTTP diffusable pour les serveurs distants, utilisant du JSON sans état (plus simple à mettre à l'échelle et maintenir, par rapport aux sessions avec état et aux réponses en streaming). stdio pour les serveurs locaux.

Charger la documentation du framework :

• Best Practices MCP : 📋 Consulter les Best Practices - Directives essentielles

Pour TypeScript (recommandé) :

• SDK TypeScript : Utilisez WebFetch pour charger https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ Guide TypeScript - Patterns et exemples TypeScript

Pour Python :

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

1.4 Planifier votre implémentation

Comprendre l'API : Consultez la documentation de l'API du service pour identifier les endpoints clés, les exigences d'authentification et les modèles de données. Utilisez la recherche web et WebFetch selon les besoins.

Sélection des tools : Privilégiez la couverture API complète. Listez les endpoints à 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 - Structure du projet, package.json, tsconfig.json
• 🐍 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
• Helpers de gestion d'erreurs
• Formatage des réponses (JSON/Markdown)
• Support de la pagination

2.3 Implémenter les tools

Pour chaque tool :

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 si possible pour les données structurées
• Utilisez structuredContent dans les réponses des tools (feature du SDK TypeScript)
• Aide les clients à comprendre et traiter les outputs des tools

Description du tool :

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

Implémentation :

• Async/await pour les opérations I/O
• Gestion appropriée des erreurs avec messages actionnables
• Support de la pagination où applicable
• Retournez à la fois du contenu textuel et des données structurées lors de l'utilisation de SDKs modernes

Annotations :

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

Phase 3 : Examen et tests

3.1 Qualité du code

Examinez pour :

• Pas de code dupliqué (principe DRY)
• Gestion d'erreurs cohérente
• Couverture de type complète
• Descriptions claires des tools

3.2 Construire et tester

TypeScript :

• Exécutez npm run build pour vérifier la compilation
• Testez avec MCP Inspector : npx @modelcontextprotocol/inspector

Python :

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

Consultez les guides spécifiques au langage pour les approches de test détaillées et les 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é.

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

4.1 Comprendre le but 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 tools : Listez les tools 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 est :

• Indépendante : Non dépendante d'autres questions
• En lecture seule : Seules des opérations non-destructrices requises
• Complexe : Nécessitant plusieurs appels de tools et une exploration approfondie
• Réaliste : Basée sur des cas d'usage réels auxquels les humains tiendraient
• Vérifiable : Réponse unique et claire qui peut être vérifiée par comparaison de chaîne
• Stable : La réponse ne changera pas au fil du temps

4.4 Format de sortie

Créez un fichier XML avec cette structure :

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>

Fichiers de référence

📚 Bibliothèque de documentation

Chargez ces ressources selon les besoins lors du développement :

Documentation MCP de base (Charger en premier)

• Protocole MCP : Commencez par le sitemap sur https://modelcontextprotocol.io/sitemap.xml, puis récupérez des pages spécifiques avec le suffixe .md
• 📋 Best Practices MCP - Directives MCP universelles incluant :
  • Conventions de nommage des serveurs et tools
  • Directives de format de réponse (JSON vs Markdown)
  • Best practices de pagination
  • Sélection du transport (HTTP diffusable vs stdio)
  • Normes de sécurité et gestion d'erreurs

Documentation SDK (Charger lors de la Phase 1/2)

• SDK Python : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• SDK TypeScript : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Guides d'implémentation spécifiques au langage (Charger lors de la Phase 2)

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

  • Patterns d'initialisation du serveur
  • Exemples de modèles Pydantic
  • Inscription des tools avec @mcp.tool
  • Exemples de travail complets
  • Liste de contrôle qualité

• ⚡ Guide d'implémentation TypeScript - Guide TypeScript complet avec :

  • Structure du projet
  • Patterns de schéma Zod
  • Inscription des tools avec server.registerTool
  • Exemples de travail complets
  • Liste de contrôle qualité

Guide d'évaluation (Charger lors de la Phase 4)

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