Communitygithub.com

ASoudy/AGS

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.

Qu'est-ce que AGS ?

Ce guide détaille le processus complet de création d'un serveur MCP (Model Context Protocol) performant, destiné aux développeurs souhaitant intégrer des API externes et permettre aux LLM d'exécuter des tâches concrètes. Il couvre quatre phases : recherche et planification approfondies, implémentation, test et création d'évaluations. Le guide recommande l'utilisation de TypeScript (avec le SDK officiel) ou de Python (avec FastMCP), et met l'accent sur une conception d'outils avec des noms clairs, des schémas d'entrée précis (Zod/Pydantic) et des messages d'erreur exploitables. Il insiste sur l'importance de la couverture API exhaustive par rapport aux outils de workflow spécialisés, et détaille la configuration de l'infrastructure, la gestion des erreurs, le support de la pagination et les annotations de sécurité (readOnlyHint, destructiveHint, etc.). Enfin, le guide explique comment créer des évaluations de qualité avec des questions complexes et vérifiables pour tester l'efficacité du serveur. Les fichiers de référence (documentation MCP, SDK et guides d'implémentation, avec web fetch) sont essentiels au processus.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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


Processus

🚀 Workflow de haut niveau

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

Phase 1 : Recherche et planification approfondies

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

1.2 Étudier la documentation du protocole MCP

Naviguez 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 (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é :

  • Langage : TypeScript (prise en charge SDK de haute qualité et bonne compatibilité dans de nombreux environnements d'exécution comme MCPB. De plus, les modèles IA sont doués 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 JSON sans état (plus simple à mettre à l'échelle et à maintenir, par opposition aux sessions avec état et aux réponses en streaming). stdio pour les serveurs locaux.

Chargez la documentation du framework :

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

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)
  • 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 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'E/S
  • Gestion appropriée des erreurs avec des messages exploitables
  • Support de la pagination le cas échéant
  • Retour à la fois du contenu textuel et des 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 :

  • Pas de code dupliqué (principe DRY)
  • Gestion cohérente des erreurs
  • Couverture de type complète
  • 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

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

  • Indépendante : Ne dépend pas d'autres questions
  • Lecture seule : Nécessite uniquement des opérations non destructives
  • Complexe : Nécessite plusieurs appels d'outils et une exploration approfondie
  • Réaliste : Basée sur des cas d'utilisation réels qui intéresseraient 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 IA avec des noms de code d'animaux. Un modèle avait besoin d'une désignation de sécurité spécifique utilisant 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 de base (à 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 des 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 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 d'outils avec @mcp.tool
    • Exemples fonctionnels complets
    • Liste de contrôle qualité
  • ⚡ Guide d'implémentation TypeScript - Guide complet TypeScript avec :

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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Skills associés