aiskillstore/marketplace

Guide de développement de serveurs MCP

Aperçu

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

---

Processus

🚀 Flux de travail de haut niveau

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

Phase 1 : Recherche et planification approfondies

1.1 Comprendre la conception moderne des MCP

Couverture des API vs Outils de workflow : Équilibrez la couverture complète des points de terminaison de l'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 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 de base, tandis que d'autres fonctionnent mieux avec des workflows de plus haut niveau. En cas d'incertitude, privilégiez une couverture complète de l'API.

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 spécifiques et des étapes suivantes.

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 :

• Aperçu et architecture de la spécification
• Mécanismes de transport (HTTP streamable, stdio)
• Définitions des outils, 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 d'IA sont performants pour générer 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, en utilisant du JSON sans état (plus simple à scaler et à maintenir, par opposition aux sessions avec état et aux réponses en streaming). stdio pour les serveurs locaux.

Charger la documentation du framework :

• Meilleures pratiques MCP : 📋 Voir les meilleures pratiques - Directives fondamentales

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 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 complète de l'API. 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 - 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
• 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 des contraintes et des descriptions claires
• Ajoutez des exemples dans les descriptions des champs

Schéma de sortie :

• Définissez outputSchema dans la mesure du 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 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 correcte des erreurs avec des messages exploitables
• Prise en charge de la pagination le cas échéant
• Retournez à 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 : Revue 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
• 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 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 sur l'évaluation.

4.1 Comprendre l'objectif de l'évaluation

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

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 est :

• Indépendante : Ne dépend pas d'autres questions
• En lecture seule : Seules des opérations non destructives sont requises
• 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 qui peut être vérifiée par comparaison de chaînes
• Stable : La réponse ne changera pas avec le temps

4.4 Format de sortie

Créez un fichier XML avec cette structure :

<evaluation>
  <qa_pair>
    <question>Trouvez les discussions sur les lancements de modèles d'IA avec des noms de code animaux. Un modèle nécessitait une désignation de sécurité spécifique qui utilise 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 les pages spécifiques avec le suffixe .md
• 📋 Meilleures pratiques MCP - Directives MCP universelles incluant :
  • Conventions de nommage des serveurs et des outils
  • Directives de format des réponses (JSON vs Markdown)
  • Meilleures 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 : 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 complet Python/FastMCP avec :

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

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

  • Structure du projet
  • Modèles de schéma Zod
  • Enregistrement des outils avec server.registerTool
  • Exemples complets 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