David-Li0406/meta-skill-evloving

Guide de développement de serveurs 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 par 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 d'accès 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 de l'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 exemple, 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 et des étapes suivantes spécifiques.

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

Récupérez ensuite les pages spécifiques avec le suffixe .md pour le format Markdown (par exemple, https://modelcontextprotocol.io/specification/draft.md).

Pages clés à consulter :

• Présentation 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

Stack recommandée :

• Langage: TypeScript (prise en charge SDK de haute qualité et bonne compatibilité dans de nombreux environnements d'exécution, par exemple MCPB. De plus, les modèles d'IA sont doués pour générer du code TypeScript, bénéficiant de son utilisation massive, de son typage statique et de ses bons outils de linting)
• Transport: HTTP streamable pour les serveurs distants, en utilisant du JSON sans état (plus simple à mettre à l'échelle 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 de base

Pour TypeScript (recommandé) :

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

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 d'accès 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 d'accès à 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

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)
• Prise en charge 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 les 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 des fonctionnalités
• Descriptions des paramètres
• Schéma du type de retour

Implémentation :

• Async/await pour les opérations d'I/O
• Gestion appropriée des erreurs avec des messages exploitables
• Prise en charge de la pagination le cas échéant
• Renvoyez à la fois le contenu textuel et les données structurées lors de l'utilisation des 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 Construction et test

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

Voir les guides spécifiques au langage pour des approches de test détaillées et des 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 ✅ Guide d'évaluation pour des directives d'évaluation complètes.

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 READ-ONLY 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: Ne dépend pas d'autres questions
• En lecture seule: Uniquement des opérations non destructives requises
• Complexe: Nécessitant 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 avait besoin d'une désignation de sécurité spécifique qui utilise le format ASL-X. Quel numéro 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 de base (à charger en premier)

• Protocole MCP: Commencez par le plan du site à https://modelcontextprotocol.io/sitemap.xml, puis récupérez les 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 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 pendant la phase 2)

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

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

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

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

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