Quelle: Inhalt angepasst von Anthropics/Skills (MIT).

Übersicht

Erstellen Sie MCP-Server (Model Context Protocol), die es LLMs ermöglichen, über gut konzipierte Tools mit externen Diensten zu interagieren. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er es LLMs ermöglicht, reale Aufgaben zu erfüllen.

Prozess

High-Level-Workflow

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Intensive Forschung und Planung

1.1 Modernes MCP-Design verstehen

API-Abdeckung vs. Workflow-Tools: Kombinieren Sie eine umfassende API-Endpunktabdeckung mit speziellen Workflow-Tools. Workflow-Tools können für bestimmte Aufgaben praktischer sein, während eine umfassende Abdeckung den Agenten Flexibilität bei der Zusammenstellung von Vorgängen gibt. Die Leistung variiert je nach Kunde – einige Kunden profitieren von einer Codeausführung, die grundlegende Tools kombiniert, während andere besser mit Workflows auf höherer Ebene arbeiten. Wenn Sie unsicher sind, priorisieren Sie eine umfassende API-Abdeckung.

Toolbenennung und Auffindbarkeit: Klare, beschreibende Werkzeugnamen helfen Agenten, die richtigen Werkzeuge schnell zu finden. Verwenden Sie konsistente Präfixe (z. B.github_create_issue,github_list_repos) und eine aktionsorientierte Benennung.

Kontextverwaltung: Agenten profitieren von prägnanten Toolbeschreibungen und der Möglichkeit, Ergebnisse zu filtern/paginieren. Entwerfen Sie Tools, die fokussierte, relevante Daten liefern. Einige Clients unterstützen die Codeausführung, was Agenten dabei helfen kann, Daten effizient zu filtern und zu verarbeiten.

Umsetzbare Fehlermeldungen: Fehlermeldungen sollten Agenten mit konkreten Vorschlägen und nächsten Schritten zu Lösungen führen.

1.2 Studieren Sie die MCP-Protokolldokumentation

Navigieren Sie durch die MCP-Spezifikation:

Beginnen Sie mit der Sitemap, um relevante Seiten zu finden:https://modelcontextprotocol.io/sitemap.xml

Rufen Sie dann bestimmte Seiten mit dem Suffix.mdfür das Markdown-Format ab (z. B.https://modelcontextprotocol.io/specification/draft.md).

Wichtige Seiten zur Überprüfung:

• Spezifikationsübersicht und Architektur
• Transportmechanismen (streambares HTTP, stdio)
• Werkzeug-, Ressourcen- und Eingabeaufforderungsdefinitionen

1.3 Dokumentation des Studienrahmens

Empfohlener Stapel:

• Sprache: TypeScript (hochwertige SDK-Unterstützung und gute Kompatibilität in vielen Ausführungsumgebungen, z. B. MCPB. Außerdem sind KI-Modelle gut in der Generierung von TypeScript-Code und profitieren von seiner breiten Verwendung, der statischen Typisierung und den guten Linting-Tools)
• Transport: Streambares HTTP für Remote-Server unter Verwendung von zustandslosem JSON (einfacher zu skalieren und zu verwalten, im Gegensatz zu zustandsbehafteten Sitzungen und Streaming-Antworten). stdio für lokale Server.

Framework-Dokumentation laden:

• Best Practices von MCP: Best Practices anzeigen – Kernrichtlinien

Für TypeScript (empfohlen):

• TypeScript SDK: Verwenden Sie WebFetch, umhttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdzu laden
• TypeScript-Handbuch – TypeScript-Muster und Beispiele

Für Python:

• Python SDK: Verwenden Sie WebFetch, umhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdzu laden
• Python-Leitfaden – Python-Muster und Beispiele

1.4 Planen Sie Ihre Implementierung

Verstehen Sie die API: Sehen Sie sich die API-Dokumentation des Dienstes an, um wichtige Endpunkte, Authentifizierungsanforderungen und Datenmodelle zu identifizieren. Verwenden Sie nach Bedarf die Websuche und WebFetch.

Werkzeugauswahl: Priorisieren Sie eine umfassende API-Abdeckung. Listen Sie die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Vorgängen.

Phase 2: Umsetzung

2.1 Projektstruktur einrichten

Weitere Informationen zur Projekteinrichtung finden Sie in den sprachspezifischen Anleitungen:

• TypeScript-Handbuch – Projektstruktur, package.json, tsconfig.json
• Python-Leitfaden – Modulorganisation, Abhängigkeiten

2.2 Kerninfrastruktur implementieren

Gemeinsam genutzte Dienstprogramme erstellen:

• API-Client mit Authentifizierung
• Helfer zur Fehlerbehandlung
• Antwortformatierung (JSON/Markdown)
• Unterstützung für Paginierung

2.3 Tools implementieren

Für jedes Werkzeug:

Eingabeschema:

• Verwenden Sie Zod (TypeScript) oder Pydantic (Python)
• Fügen Sie Einschränkungen und klare Beschreibungen hinzu
• Fügen Sie Beispiele in Feldbeschreibungen hinzu

Ausgabeschema:

• Definieren SieoutputSchemanach Möglichkeit für strukturierte Daten
• Verwenden SiestructuredContentin Tool-Antworten (TypeScript SDK-Funktion)
• Hilft Kunden, Tool-Ausgaben zu verstehen und zu verarbeiten

Werkzeugbeschreibung:

• Kurze Zusammenfassung der Funktionalität
• Parameterbeschreibungen
• Rückgabetypschema

Implementierung:

• Asynchron/Warten auf E/A-Vorgänge
• Richtige Fehlerbehandlung mit umsetzbaren Meldungen
• Unterstützen Sie gegebenenfalls die Paginierung
• Geben Sie bei Verwendung moderner SDKs sowohl Textinhalte als auch strukturierte Daten zurück

Anmerkungen:

• readOnlyHint: wahr/falsch
• destructiveHint: wahr/falsch
• idempotentHint: wahr/falsch
• openWorldHint: wahr/falsch

Phase 3: Überprüfung und Test

3.1 Codequalität

Rezension für:

• Kein duplizierter Code (DRY-Prinzip)
• Konsistente Fehlerbehandlung
• Vollständige Typenabdeckung
• Klare Werkzeugbeschreibungen

3.2 Erstellen und Testen

TypeScript:

• Führen Sienpm run buildaus, um die Kompilierung zu überprüfen
• Test mit MCP Inspector:npx @modelcontextprotocol/inspector

Python:

• Überprüfen Sie die Syntax:python -m py_compile your_server.py
• Testen Sie mit MCP Inspector

Detaillierte Testansätze und Qualitätschecklisten finden Sie in den sprachspezifischen Leitfäden.

Phase 4: Auswertungen erstellen

Erstellen Sie nach der Implementierung Ihres MCP-Servers umfassende Auswertungen, um dessen Wirksamkeit zu testen.

Laden Sie Bewertungsleitfaden für vollständige Bewertungsrichtlinien.

4.1 Bewertungszweck verstehen

Testen Sie anhand von Auswertungen, ob LLMs Ihren MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.

4.2 Erstellen Sie 10 Bewertungsfragen

Um effektive Bewertungen zu erstellen, befolgen Sie den im Bewertungsleitfaden beschriebenen Prozess:

1. Werkzeuginspektion: Verfügbare Werkzeuge auflisten und deren Fähigkeiten verstehen
2. Inhaltserkundung: Verwenden Sie schreibgeschützte Vorgänge, um verfügbare Daten zu untersuchen
3. Fragenerstellung: Erstellen Sie 10 komplexe, realistische Fragen
4. Antwortüberprüfung: Lösen Sie jede Frage selbst, um die Antworten zu überprüfen

4.3 Bewertungsanforderungen

Stellen Sie sicher, dass jede Frage lautet:

• Unabhängig: Nicht abhängig von anderen Fragen
• Schreibgeschützt: Nur zerstörungsfreie Vorgänge erforderlich
• Komplex: Erfordert mehrere Toolaufrufe und eine gründliche Erkundung
• Realistisch: Basierend auf realen Anwendungsfällen, die Menschen interessieren würden
• Überprüfbar: Einzelne, klare Antwort, die durch Zeichenfolgenvergleich überprüft werden kann
• Stabil: Die Antwort ändert sich im Laufe der Zeit nicht

4.4 Ausgabeformat

Erstellen Sie eine XML-Datei mit dieser Struktur:

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

Referenzdateien

Dokumentationsbibliothek

Laden Sie diese Ressourcen nach Bedarf während der Entwicklung:

Kern-MCP-Dokumentation (zuerst laden)

• MCP-Protokoll: Beginnen Sie mit der Sitemap beihttps://modelcontextprotocol.io/sitemap.xmlund rufen Sie dann bestimmte Seiten mit dem Suffix.mdab
• MCP Best Practices – Universelle MCP-Richtlinien, einschließlich:
  • Namenskonventionen für Server und Tools
  • Richtlinien für Antwortformate (JSON vs. Markdown)
  • Best Practices für die Paginierung
  • Transportauswahl (streambares HTTP vs. stdio)
  • Standards für Sicherheit und Fehlerbehandlung

SDK-Dokumentation (Laden während Phase 1/2)

• Python SDK: Vonhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdabrufen
• TypeScript SDK: Vonhttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdabrufen

Sprachspezifische Implementierungshandbücher (Laden während Phase 2)

• Python-Implementierungsleitfaden – Vollständiger Python/FastMCP-Leitfaden mit:

  • Serverinitialisierungsmuster
  • Beispiele für pydantische Modelle
  • Werkzeugregistrierung mit@mcp.tool
  • Vollständige Arbeitsbeispiele
  • Qualitätscheckliste

• TypeScript-Implementierungshandbuch – Vollständiges TypeScript-Handbuch mit:

  • Projektstruktur
  • Zod-Schemamuster
  • Werkzeugregistrierung mitserver.registerTool
  • Vollständige Arbeitsbeispiele
  • Qualitätscheckliste

Evaluierungsleitfaden (Laden während Phase 4)

• Evaluierungsleitfaden – Vollständiger Leitfaden zur Evaluierungserstellung mit:
  • Richtlinien zur Fragenerstellung
  • Strategien zur Antwortverifizierung
  • Spezifikationen für das XML-Format
  • Beispielfragen und -antworten
  • Ausführen einer Auswertung mit den bereitgestellten Skripten

Ressourcendateien

LIZENZ.txt

LICENSE.txt herunterladen

Binäre Ressource

reference/evaluation.md

Reference/evaluation.md herunterladen

Binäre Ressource

reference/mcp_best_practices.md

Download reference/mcp_best_practices.md

Binäre Ressource

reference/node_mcp_server.md

Download reference/node_mcp_server.md

Binäre Ressource

reference/python_mcp_server.md

Download reference/python_mcp_server.md

Binäre Ressource

scripts/connections.py

Scripts/connections.py herunterladen

"""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/evaluation.py

Scripts/evaluation.py herunterladen

Binäre Ressource

scripts/example_evaluation.xml

Download scripts/example_evaluation.xml

Binäre Ressource

scripts/requirements.txt

Scripts/requirements.txt herunterladen

anthropic>=0.39.0
mcp>=1.1.0

Siehe in GitHub

Siehe in GitHub