MCP-Server-Patterns

Was macht MCP-Server-Patterns?

Mit dem Model Context Protocol (MCP) können KI-Assistenten Tools aufrufen, Ressourcen lesen und Prompts von deinem Server nutzen. Verwende dieses Skill beim Erstellen oder Warten von MCP-Servern. Die SDK-API entwickelt sich weiter; überprüfe Context7 (query-docs für „MCP“) oder die offizielle MCP-Dokumentation, um die aktuellen Methodennamen und Signaturen zu erhalten.

Für die übergreifende Routing-Entscheidung, wann eine Fähigkeit eine Regel, ein Skill, MCP oder ein einfacher CLI-/API-Workflow sein sollte, siehe docs/capability-surface-selection.md.

Wann verwenden

Verwende dies bei: Implementierung eines neuen MCP-Servers, Hinzufügen von Tools oder Ressourcen, Wahl zwischen stdio und HTTP, Upgrade des SDK oder Debuggen von MCP-Registrierungs- und Transportproblemen.

Wie es funktioniert

Kernkonzepte

• Tools: Aktionen, die das Modell aufrufen kann (z. B. Suche, Ausführen eines Befehls). Registriere sie mit registerTool() oder tool(), abhängig von der SDK-Version.
• Ressourcen: Schreibgeschützte Daten, die das Modell abrufen kann (z. B. Dateiinhalte, API-Antworten). Registriere sie mit registerResource() oder resource(). Handler erhalten normalerweise ein uri-Argument.
• Prompts: Wiederverwendbare, parametrisierte Prompt-Vorlagen, die der Client anzeigen kann (z. B. in Claude Desktop). Registriere sie mit registerPrompt() oder einem Äquivalent.
• Transport: stdio für lokale Clients (z. B. Claude Desktop); Streamable HTTP wird für Remote-Clients (Cursor, Cloud) bevorzugt. Legacy-HTTP/SSE dient der Abwärtskompatibilität.

Das Node/TypeScript SDK kann tool() / resource() oder registerTool() / registerResource() bereitstellen; das offizielle SDK hat sich im Laufe der Zeit geändert. Überprüfe immer die aktuellen MCP-Dokumente oder Context7.

Verbinden mit stdio

Erstelle für lokale Clients einen stdio-Transport und übergib ihn an die connect-Methode deines Servers. Die genaue API variiert je nach SDK-Version (z. B. Konstruktor vs. Factory). Siehe die offizielle MCP-Dokumentation oder frage Context7 nach „MCP stdio server“ für das aktuelle Pattern.

Halte die Serverlogik (Tools + Ressourcen) transportunabhängig, damit du im Einstiegspunkt stdio oder HTTP einstecken kannst.

Remote (Streamable HTTP)

Verwende für Cursor, Cloud oder andere Remote-Clients Streamable HTTP (ein einzelner MCP-HTTP-Endpunkt gemäß aktuellem Standard). Unterstütze Legacy-HTTP/SSE nur, wenn Abwärtskompatibilität erforderlich ist.

Beispiele

Installation und Servereinrichtung

npm install @modelcontextprotocol/sdk zod

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

Registriere Tools und Ressourcen mit der API, die deine SDK-Version bereitstellt: Einige Versionen verwenden server.tool(name, description, schema, handler) (positionsabhängige Argumente), andere verwenden server.tool({ name, description, inputSchema }, handler) oder registerTool(). Gleiches gilt für Ressourcen – füge einen uri in den Handler ein, wenn die API ihn bereitstellt. Überprüfe die aktuellen @modelcontextprotocol/sdk-Signaturen in der offiziellen MCP-Dokumentation oder Context7, um Copy-Paste-Fehler zu vermeiden.

Verwende Zod (oder das bevorzugte Schemaformat des SDK) für die Eingabevalidierung.

Best Practices

• Schema zuerst: Definiere Eingabeschemata für jedes Tool; dokumentiere Parameter und Rückgabeform.
• Fehler: Gib strukturierte Fehler oder Nachrichten zurück, die das Modell interpretieren kann; vermeide rohe Stacktraces.
• Idempotenz: Bevorzuge wo möglich idempotente Tools, damit Wiederholungen sicher sind.
• Rate und Kosten: Berücksichtige bei Tools, die externe APIs aufrufen, Ratenlimits und Kosten; dokumentiere dies in der Tool-Beschreibung.
• Versionierung: Setze die SDK-Version in package.json fest; überprüfe die Versionshinweise beim Upgrade.

Offizielle SDKs und Dokumente

• JavaScript/TypeScript: @modelcontextprotocol/sdk (npm). Verwende Context7 mit dem Bibliotheksnamen „MCP“ für aktuelle Registrierungs- und Transport-Patterns.
• Go: Offizielles Go-SDK auf GitHub (modelcontextprotocol/go-sdk).
• C#: Offizielles C#-SDK für .NET.