Source: Contenu adapté de anthropics/skills (MIT).

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 la manière dont il permet aux LLM d'accomplir des tâches réelles.

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

Couverture API par rapport aux 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 d'une exécution de code combinant des outils de base, tandis que d'autres fonctionnent mieux avec des flux de travail de niveau supérieur. En cas de doute, donnez la priorité à une couverture API complète.

Nom et visibilité 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 une dénomination orientée action.

Gestion du contexte: Les agents bénéficient de descriptions concises des outils 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 efficacement les données.

Messages d'erreur exploitables: 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

Naviguez 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 des pages spécifiques avec le suffixe.mdpour le format markdown (par exemple,https://modelcontextprotocol.io/specification/draft.md).

Pages clés à consulter:

• Présentation des spécifications et architecture
• Mécanismes de transport (HTTP streamable, stdio)
• Définitions d'outils, de ressources et d'invites

1.3 Documentation du cadre d'étude

Pile recommandée:

• Langage: TypeScript (prise en charge du 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 efficaces pour générer du code TypeScript, bénéficiant de sa large utilisation, de son typage statique et de ses bons outils de peluchage)
• Transport: HTTP diffusable 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.

Charger la documentation du framework:

• Meilleures pratiques MCP: Afficher les meilleures pratiques - Directives de base

Pour TypeScript (recommandé):

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

Pour Python:

• SDK Python: utilisez WebFetch pour chargerhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• Guide Python - Modèles et exemples Python

1.4 Planifiez votre mise en œuvre

Comprenez 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 sur le Web et WebFetch si nécessaire.

Sélection d'outils: Donnez la priorité à une couverture API complète. Répertoriez les points de terminaison à implémenter, en commençant par les opérations les plus courantes.

Phase 2: mise en œuvre

2.1 Configurer la structure du projet

Consultez les guides spécifiques à la langue pour la configuration du projet:

• Guide TypeScript - Structure du projet, package.json, tsconfig.json
• Guide Python - Organisation des modules, dépendances

2.2 Mettre en œuvre l'infrastructure de base

Créez des utilitaires partagés:

• Client API avec authentification
• Aides à la gestion des erreurs
• Formatage de la réponse (JSON/Markdown)
• Prise en charge de la pagination

2.3 Outils de mise en œuvre

Pour chaque outil:

Schéma d'entrée:

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

Schéma de sortie:

• DéfinissezoutputSchemasi possible pour les données structurées
• UtiliserstructuredContentdans les réponses de l'outil (fonctionnalité TypeScript SDK)
• Aide les clients à comprendre et à traiter les résultats des outils

Description de l'outil:

• Résumé concis des fonctionnalités
• Descriptions des paramètres
• Schéma de type de retour

Mise en œuvre:

• Asynchrone/attente pour les opérations d'E/S
• Gestion appropriée des erreurs avec des messages exploitables
• Pagination prise en charge le cas échéant
• Renvoie à la fois le contenu textuel et les données structurées lors de l'utilisation de SDK modernes

Annotations:

• readOnlyHint: vrai/faux
• destructiveHint: vrai/faux
• idempotentHint: vrai/faux
• openWorldHint: vrai/faux

Phase 3: examen et test

3.1 Qualité des codes

Examen pour:

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

3.2 Construire et tester

TypeScript:

• Exécuteznpm run buildpour vérifier la compilation
• Test avec l'inspecteur MCP:npx @modelcontextprotocol/inspector

Python:

• Vérifier la syntaxe:python -m py_compile your_server.py
• Test avec l'inspecteur MCP

Consultez les guides spécifiques à chaque langue pour connaître 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é.

Chargez Guide d'évaluation pour obtenir des directives d'évaluation complètes.

4.1 Comprendre le but de l'évaluation

Utilisez des é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: répertoriez les outils disponibles et comprenez leurs capacités
2. Exploration de contenu: utilisez les opérations 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épendant: ne dépend pas d'autres questions
• Lecture seule: seules les opérations non destructives sont requises
• Complexe: nécessite plusieurs appels d'outils et une exploration approfondie
• Réaliste: basé sur des cas d'utilisation réels qui intéresseraient 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>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 documentaire

Chargez ces ressources selon vos besoins pendant le développement:

Documentation de base de MCP (charger en premier)

• Protocole MCP: commencez par le plan du site surhttps://modelcontextprotocol.io/sitemap.xml, puis récupérez des pages spécifiques avec le suffixe.md.
•  Meilleures pratiques MCP – Directives universelles MCP, notamment:
  • Conventions de dénomination des serveurs et des outils
  • Directives relatives au format de réponse (JSON vs Markdown)
  • Bonnes pratiques en matière de pagination
  • Sélection du transport (HTTP streamable vs stdio)
  • Normes de sécurité et de gestion des erreurs

Documentation du SDK (chargement pendant la phase 1/2)

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

Guides de mise en œuvre spécifiques au langage (chargement pendant la phase 2)

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

  • Modèles d'initialisation du serveur
  • Exemples de modèles pydantiques
  • Enregistrement d'outil avec@mcp.tool
  • Exemples de travail complets
  • 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'outil avecserver.registerTool
  • Exemples de travail complets
  • Liste de contrôle qualité

Guide d'évaluation (chargement pendant la phase 4)

• Guide d'évaluation - Guide complet de création d'évaluation avec:
  • Directives pour la création de questions
  • Stratégies de vérification des réponses
  • Spécifications du format XML
  • Exemples de questions et réponses
  • Exécuter une évaluation avec les scripts fournis

Fichiers de ressources

LICENCE.txt

Télécharger LICENSE.txt

Ressource binaire

référence/évaluation.md

Télécharger référence/evaluation.md

Ressource binaire

référence/mcp_best_practices.md

Télécharger la référence/mcp_best_practices.md

Ressource binaire

référence/node_mcp_server.md

Télécharger la référence/node_mcp_server.md

Ressource binaire

référence/python_mcp_server.md

Télécharger la référence/python_mcp_server.md

Ressource binaire

scripts/connexions.py

Télécharger scripts/connections.py

"""Lightweight connection handling for MCP servers."""

from abc import ABC, abstractmethod
from contextlib import AsyncExitStack
from typing import Any

from mcp import ClientSession, StdioServerParameters
from mcp.client.sse import sse_client
from mcp.client.stdio import stdio_client
from mcp.client.streamable_http import streamablehttp_client


class MCPConnection(ABC):
    """Base class for MCP server connections."""

    def __init__(self):
        self.session = None
        self._stack = None

    @abstractmethod
    def _create_context(self):
        """Create the connection context based on connection type."""

    async def __aenter__(self):
        """Initialize MCP server connection."""
        self._stack = AsyncExitStack()
        await self._stack.__aenter__()

        try:
            ctx = self._create_context()
            result = await self._stack.enter_async_context(ctx)

            if len(result) == 2:
                read, write = result
            elif len(result) == 3:
                read, write, _ = result
            else:
                raise ValueError(f"Unexpected context result: {result}")

            session_ctx = ClientSession(read, write)
            self.session = await self._stack.enter_async_context(session_ctx)
            await self.session.initialize()
            return self
        except BaseException:
            await self._stack.__aexit__(None, None, None)
            raise

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        """Clean up MCP server connection resources."""
        if self._stack:
            await self._stack.__aexit__(exc_type, exc_val, exc_tb)
        self.session = None
        self._stack = None

    async def list_tools(self) -> list[dict[str, Any]]:
        """Retrieve available tools from the MCP server."""
        response = await self.session.list_tools()
        return [
            {
                "name": tool.name,
                "description": tool.description,
                "input_schema": tool.inputSchema,
            }
            for tool in response.tools
        ]

    async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
        """Call a tool on the MCP server with provided arguments."""
        result = await self.session.call_tool(tool_name, arguments=arguments)
        return result.content


class MCPConnectionStdio(MCPConnection):
    """MCP connection using standard input/output."""

    def __init__(self, command: str, args: list[str] = None, env: dict[str, str] = None):
        super().__init__()
        self.command = command
        self.args = args or []
        self.env = env

    def _create_context(self):
        return stdio_client(
            StdioServerParameters(command=self.command, args=self.args, env=self.env)
        )


class MCPConnectionSSE(MCPConnection):
    """MCP connection using Server-Sent Events."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return sse_client(url=self.url, headers=self.headers)


class MCPConnectionHTTP(MCPConnection):
    """MCP connection using Streamable HTTP."""

    def __init__(self, url: str, headers: dict[str, str] = None):
        super().__init__()
        self.url = url
        self.headers = headers or {}

    def _create_context(self):
        return streamablehttp_client(url=self.url, headers=self.headers)


def create_connection(
    transport: str,
    command: str = None,
    args: list[str] = None,
    env: dict[str, str] = None,
    url: str = None,
    headers: dict[str, str] = None,
) -> MCPConnection:
    """Factory function to create the appropriate MCP connection.

    Args:
        transport: Connection type ("stdio", "sse", or "http")
        command: Command to run (stdio only)
        args: Command arguments (stdio only)
        env: Environment variables (stdio only)
        url: Server URL (sse and http only)
        headers: HTTP headers (sse and http only)

    Returns:
        MCPConnection instance
    """
    transport = transport.lower()

    if transport == "stdio":
        if not command:
            raise ValueError("Command is required for stdio transport")
        return MCPConnectionStdio(command=command, args=args, env=env)

    elif transport == "sse":
        if not url:
            raise ValueError("URL is required for sse transport")
        return MCPConnectionSSE(url=url, headers=headers)

    elif transport in ["http", "streamable_http", "streamable-http"]:
        if not url:
            raise ValueError("URL is required for http transport")
        return MCPConnectionHTTP(url=url, headers=headers)

    else:
        raise ValueError(f"Unsupported transport type: {transport}. Use 'stdio', 'sse', or 'http'")

scripts/évaluation.py

Télécharger scripts/evaluation.py

Ressource binaire

scripts/exemple_evaluation.xml

Télécharger scripts/example_evaluation.xml

Ressource binaire

scripts/exigences.txt

Télécharger scripts/requirements.txt

anthropic>=0.39.0
mcp>=1.1.0

Voir dans GitHub

Voir dans GitHub