Guide de développement de serveur MCP

Vue d'ensemble

Créez des serveurs MCP (Model Context Protocol) qui permettent aux LLM d'interagir avec des services externes grâce à des outils bien conçus. La qualité d'un serveur MCP se mesure à la facilité avec laquelle il permet aux LLM d'accomplir des tâches concrètes.

Écosystème Microsoft MCP

Microsoft fournit une infrastructure MCP étendue pour les services Azure et Foundry. Comprendre cet écosystème vous aide à décider si vous devez créer des serveurs personnalisés ou exploiter les serveurs existants.

Types de serveurs

Serveurs Microsoft MCP

Avant de créer un serveur personnalisé, vérifiez si Microsoft en fournit déjà un :

Écosystème complet : Consultez 🔷 Modèles Microsoft MCP pour le catalogue complet des serveurs et les modèles.

Quand utiliser Microsoft ou un serveur personnalisé

Processus

🚀 Flux de travail de haut niveau

Créer 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 endpoints API avec des outils de workflow spécialisés. Les outils 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 outils basiques, tandis que d'autres fonctionnent mieux avec des workflows de niveau supérieur. En cas de doute, priorisez la couverture API complète.

Dénomination 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 exemple, github_create_issue, github_list_repos) et une dénomination orientée vers l'action.

Gestion du contexte : Les agents bénéficient de descriptions d'outils concises et de la capacité à filtrer/paginer les résultats. Concevez des outils qui retournent des données ciblées et pertinentes. Certains clients supportent 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 les prochaines étapes.

1.2 Étudier la documentation du protocole MCP

Naviguer dans 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 :

• Vue d'ensemble et architecture de la spécification
• Mécanismes de transport (HTTP avec streaming, stdio)
• Définitions des outils, ressources et prompts

1.3 Étudier la documentation du framework

Sélection du langage :

Sélection du transport :

Charger la documentation du framework :

• MCP Best Practices: 📋 Voir Best Practices - Directives principales

Pour TypeScript (recommandé) :

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

Pour Python :

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

Pour C#/.NET (écosystème Microsoft) :

• 🔷 Modèles Microsoft MCP - Modèles C#, architecture Azure MCP, hiérarchie de commandes

1.4 Planifier votre implémentation

Comprendre l'API : Consultez la documentation 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 outils : Priorisez 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
• 🔷 Modèles Microsoft MCP - Structure de projet C#, hiérarchie de commandes

2.2 Implémenter l'infrastructure principale

Créez des utilitaires partagés :

• Client API avec authentification
• Assistants de gestion des erreurs
• Formatage 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 les contraintes et descriptions claires
• Ajoutez des exemples dans les descriptions des champs

Schéma de sortie :

• Définissez outputSchema quand possible pour les données structurées
• Utilisez structuredContent dans les réponses d'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 I/O
• Gestion appropriée des erreurs avec messages exploitables
• Support de la pagination où applicable
• Retournez à la fois le contenu textuel et les données structurées si vous utilisez les 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

Passez en revue :

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

3.2 Créer 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 de 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 les directives d'évaluation complètes.

4.1 Comprendre l'objectif de l'évaluation

Utilisez les évaluations pour tester si les LLM peuvent effectivement utiliser 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 : Lister les outils disponibles et comprendre leurs capacités
2. Exploration du contenu : Utiliser les opérations en LECTURE SEULE pour explorer les données disponibles
3. Génération de questions : Créer 10 questions complexes et réalistes
4. Vérification des réponses : Résoudre chaque question vous-même pour vérifier les réponses

4.3 Exigences d'évaluation

Assurez-vous que chaque question :

• Est indépendante : Ne dépend pas d'autres questions
• Est en lecture seule : Nécessite uniquement des opérations non destructives
• Est complexe : Nécessite plusieurs appels d'outils et une exploration approfondie
• Est réaliste : Basée sur des cas d'usage réels auxquels les humains se soucient
• Est vérifiable : Réponse unique et claire qui peut être vérifiée par comparaison de chaînes
• Est 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 au cours du développement :

Documentation MCP principale (charger en premier)

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

Documentation Microsoft MCP (Pour Azure/Foundry)

• 🔷 Modèles Microsoft MCP - Modèles spécifiques à Microsoft incluant :
  • Architecture d'Azure MCP Server (48+ services Azure)
  • Modèles d'implémentation de commandes C#/.NET
  • MCP distant avec Foundry Agent Service
  • Authentification (Entra ID, flux OBO, Managed Identity)
  • Infrastructure de test avec templates Bicep

Documentation du SDK (charger lors de la Phase 1/2)

• Python SDK : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• TypeScript SDK : Récupérez depuis https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• Microsoft MCP SDK : Voir Modèles Microsoft MCP pour C#/.NET

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

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

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

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

  • Structure du projet
  • Modèles de schéma Zod
  • Enregistrement d'outils avec server.registerTool
  • Exemples fonctionnels complets
  • Liste de contrôle de qualité

• 🔷 Modèles Microsoft MCP - Guide C#/.NET complet incluant :

  • Hiérarchie de commandes (BaseCommand → GlobalCommand → SubscriptionCommand)
  • Conventions de dénomination ({Resource}{Operation}Command)
  • Gestion des options avec .AsRequired() / .AsOptional()
  • Déploiement de MCP distant avec Azure Functions
  • Modèles de test en direct avec Bicep

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

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