Guide de Développement du 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 est mesurée par sa capacité à permettre aux LLM d'accomplir des tâches du monde réel.

Écosystème MCP Microsoft

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 MCP Microsoft

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

Écosystème complet : Voir ? Microsoft MCP Patterns pour le catalogue complet des serveurs et les motifs.

Quand utiliser Microsoft ou personnalisé

Processus

? Flux de travail de haut niveau

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 flux de travail : Équilibrer la couverture complète des points de terminaison API avec des outils de flux de travail spécialisés. Les outils de flux de travail peuvent être plus pratiques pour des tâches spécifiques, tandis que la couverture complète donne aux agents la flexibilité de composer les opérations. Les performances varient selon le client - certains clients bénéficient de l'exécution de code qui combine des outils de base, tandis que d'autres fonctionnent mieux avec des flux de travail de niveau supérieur. En cas de doute, prioriser la couverture API complète.

Nommage et découverte des outils : Des noms d'outils clairs et descriptifs aident les agents à trouver rapidement les bons outils. Utiliser 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 capacité à filtrer/paginer les résultats. Concevoir des outils 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 les étapes suivantes.

1.2 Étudier la documentation du protocole MCP

Naviguer dans la spécification MCP :

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

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

Pages clés à examiner :

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

1.3 Étudier la documentation du framework

Sélection du langage :

Sélection du transport :

Charger la documentation du framework :

• Meilleures pratiques MCP : ? Voir les meilleures pratiques - Directives principales

Pour TypeScript (recommandé) :

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

Pour Python :

• Python SDK : Utiliser WebFetch pour charger https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• ? Guide Python - Motifs et exemples Python

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

• ? Microsoft MCP Patterns - Motifs C#, architecture Azure MCP, hiérarchie de commandes

1.4 Planifier votre implémentation

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

Sélection des outils : Prioriser la couverture API complète. Lister 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

Voir 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
• ? Microsoft MCP Patterns - Structure du projet C#, hiérarchie de commandes

2.2 Implémenter l'infrastructure de base

Créer des utilitaires partagés :

• Client API avec authentification
• Aides 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 :

• Utiliser Zod (TypeScript) ou Pydantic (Python)
• Inclure les contraintes et descriptions claires
• Ajouter des exemples dans les descriptions de champs

Schéma de sortie :

• Définir outputSchema si possible pour les données structurées
• Utiliser structuredContent dans les réponses aux outils (fonctionnalité du SDK TypeScript)
• Aide les clients à comprendre et traiter les résultats 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 d'erreur appropriée avec messages actionnables
• Support de la pagination le cas échéant
• Retourner à la fois le contenu textuel et les 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

Examiner pour :

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

3.2 Compiler et tester

TypeScript :

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

Python :

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

Voir 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é.

Charger ✅ Guide d'évaluation pour les directives d'évaluation complètes.

4.1 Comprendre le but de l'évaluation

Utiliser 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, suivre 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 vous-même chaque question pour vérifier les réponses

4.3 Exigences d'évaluation

Assurer que chaque question est :

• Indépendante : Ne dépendant pas d'autres questions
• Lecture seule : Seules les opérations non destructives requises
• Complexe : Nécessitant plusieurs appels d'outils et une exploration approfondie
• Réaliste : Basée sur les cas d'usage réels dont les humains se soucient
• Vérifiable : Réponse unique et claire pouvant ê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éer 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

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

Documentation MCP principale (À charger en premier)

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

Documentation MCP Microsoft (Pour Azure/Foundry)

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

Documentation SDK (À charger pendant Phase 1/2)

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

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

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

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

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

  • Structure du projet
  • Motifs de schéma Zod
  • Enregistrement des outils avec server.registerTool
  • Exemples complets fonctionnels
  • Liste de contrôle de qualité

• ? Microsoft MCP Patterns - Guide C#/.NET complet avec :

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

Guide d'évaluation (À charger pendant Phase 4)

• ✅ Guide d'évaluation - Guide de création d'évaluation complet avec :
  • 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