mcp-builder

Par elophanto · elophanto

Guide pour créer des serveurs MCP (Model Context Protocol) de haute qualité permettant aux LLM d'interagir avec des services externes via des outils bien conçus. À utiliser lors de la création de serveurs MCP pour intégrer des API ou services externes, que ce soit en Python (FastMCP) ou en Node/TypeScript (MCP SDK).

npx skills add https://github.com/elophanto/elophanto --skill mcp-builder

Guide de Développement de Serveur MCP

Déclencheurs

  • mcp
  • model context protocol
  • serveur mcp
  • créer mcp
  • créer un mcp
  • serveur d'outils
  • outil mcp
  • serveur stdio
  • serveur sse
  • protocole 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 à la capacité qu'il offre aux LLM d'accomplir des tâches réelles.

Processus

🚀 Flux de Travail Haut Niveau

Créer un serveur MCP de qualité implique quatre phases principales :

Phase 1 : Recherche et Planification Approfondies

1.1 Comprendre la Conception Moderne de MCP

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

Nommage des Outils et Découverte : Des noms d'outils clairs et descriptifs aident les agents à trouver rapidement les bons outils. Utilisez des préfixes cohérents (p. 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 possibilité de 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 Actionnables : 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 plan du site 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 (p. ex. 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, p. ex. MCPB. De plus, les modèles IA sont bons pour générer du code TypeScript, bénéficiant de son utilisation large, de son typage statique et de ses bons outils de linting)
  • Transport : HTTP streamable pour les serveurs distants, utilisant du JSON sans état (plus simple à scaler et maintenir, par rapport aux sessions avec état et aux réponses en streaming). stdio pour les serveurs locaux.

Charger la documentation du framework :

Pour TypeScript (recommandé) :

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

Pour Python :

  • SDK Python : Utiliser 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 : Passez en revue 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 si nécessaire.

Sélection des Outils : 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

Voir les guides spécifiques au langage pour la configuration du projet :

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 :

  • 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 quand possible pour les données structurées
  • Utiliser structuredContent dans les réponses d'outils (feature du SDK TypeScript)
  • Aide les clients à comprendre et traiter les sorties d'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 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

Vérifiez :

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

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

Voir 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 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 : Listez les outils disponibles et comprenez leurs capacités
  2. Exploration du Contenu : Utilisez les 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 vous-même chaque question 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
  • Lecture seule : Seules les opérations non-destructives sont requises
  • Complexe : Nécessitant plusieurs appels d'outils et une exploration approfondie
  • Réaliste : Basée sur des cas d'usage réels avec lesquels les humains se préoccupent
  • Vérifiable : Réponse unique et claire pouvant être vérifiée par comparaison de chaîne
  • Stable : La réponse ne changera pas dans 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 IA avec des noms de code d'animaux. Un modèle avait besoin d'une désignation de sécurité spécifique au format ASL-X. Quel numéro X était en cours de détermination pour le modèle nommé d'après un grand félin tacheté ?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Plus de qa_pairs... -->
</evaluation>

Fichiers de Référence

📚 Bibliothèque de Documentation

Chargez ces ressources au besoin pendant le développement :

Documentation Principale MCP (Charger en Premier)

  • Protocole MCP : Commencez par le plan du site à https://modelcontextprotocol.io/sitemap.xml, puis récupérez des 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)
    • Standards de sécurité et de gestion des erreurs

Documentation du SDK (Charger Pendant Phase 1/2)

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

Guides d'Implémentation Spécifiques au Langage (Charger Pendant Phase 2)

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

    • Patterns 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 TypeScript complet avec :

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

Guide d'Évaluation (Charger Pendant 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
    • Exemples de questions et réponses
    • Exécution d'une évaluation avec les scripts fournis

Vérifier

  • L'agent/outil/canal cible a effectivement reçu le message ; un accusé de réception, un ID de message ou une charge utile de réponse est capturé
  • L'identité, les scopes et les permissions utilisés par l'appel étaient les minimums requis ; les tokens surpermissionnés sont signalés
  • La gestion des défaillances a été exercée : au moins un chemin retry/timeout/permission-denied est montré se comportant comme prévu
  • Le contexte transmis à l'acteur suivant est complet au point que le destinataire pourrait agir sans question de suivi
  • Tout état muté (config, mémoire, queue, fichier) est listé avec les valeurs avant/après, pas simplement 'mis à jour'
  • Les matériaux sensibles (clés, tokens, PII) ont été redactés des logs/transcriptions partagées dans la preuve de vérification

Skills similaires

quality-playbook
github / awesome-copilot

Générer un système qualité complet et personnalisé pour tout projet logiciel.

32 867
browser-use
browser-use / browser-use

Automatiser un navigateur web via CLI avec persistance et faible latence.

93 757
aiconfig-migrate
launchdarkly / agent-skills

Migrer une application d'invites LLM codées en dur vers LaunchDarkly AI Configs en cinq étapes.

10
remote-browser
browser-use / browser-use

Contrôler un navigateur headless en sandbox via des commandes CLI précises.

93 757
mcp-builder
microsoft / skills

Concevoir et déployer des serveurs MCP pour connecter des LLMs à des services externes.

2 300