mcp-server-patterns

MCP-Server-Muster

Das Model Context Protocol (MCP) ermöglicht es KI-Assistenten, Tools aufzurufen, Ressourcen zu lesen und Prompts von Ihrem Server zu verwenden. Verwenden Sie dieses Skill beim Erstellen oder Warten von MCP-Servern. Die SDK-API entwickelt sich weiter; überprüfen Sie Context7 (query-docs für "MCP") oder die offizielle MCP-Dokumentation für aktuelle Methodennamen und Signaturen.

Für die allgemeine 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

Verwenden Sie dies bei: Implementierung eines neuen MCP-Servers, Hinzufügen von Tools oder Ressourcen, Wahl zwischen stdio und HTTP, Upgrade des SDKs oder Debugging von MCP-Registrierungs- und Transportproblemen.

Wie es funktioniert

Kernkonzepte

• Tools: Aktionen, die das Modell aufrufen kann (z.B. Suche, Befehl ausführen). Registrieren Sie 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). Registrieren Sie 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). Registrieren Sie sie mit registerPrompt() oder einem Äquivalent.
• Transport: stdio für lokale Clients (z.B. Claude Desktop); Streamable HTTP wird für entfernte Clients bevorzugt (Cursor, Cloud). 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üfen Sie immer die aktuellen MCP-Dokumente oder Context7.

Verbinden mit stdio

Für lokale Clients erstellen Sie einen stdio-Transport und übergeben ihn an die connect-Methode Ihres Servers. Die genaue API variiert je nach SDK-Version (z.B. Konstruktor vs. Factory). Siehe die offizielle MCP-Dokumentation oder fragen Sie Context7 nach "MCP stdio server" für das aktuelle Muster.

Halten Sie die Serverlogik (Tools + Ressourcen) transportunabhängig, damit Sie im Einstiegspunkt stdio oder HTTP einstecken können.

Remote (Streamable HTTP)

Für Cursor, Cloud oder andere entfernte Clients verwenden Sie Streamable HTTP (ein einzelner MCP-HTTP-Endpunkt gemäß aktuellem Standard). Unterstützen Sie Legacy HTTP/SSE nur, wenn Abwärtskompatibilität erforderlich ist.

Beispiele

Installieren und Server einrichten

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" });

Registrieren Sie Tools und Ressourcen mit der API, die Ihre SDK-Version bereitstellt: Einige Versionen verwenden server.tool(name, description, schema, handler) (positionale Argumente), andere verwenden server.tool({ name, description, inputSchema }, handler) oder registerTool(). Gleiches gilt für Ressourcen – fügen Sie einen uri im Handler hinzu, wenn die API ihn bereitstellt. Überprüfen Sie die offiziellen MCP-Dokumente oder Context7 auf die aktuellen Signaturen von @modelcontextprotocol/sdk, um Copy-Paste-Fehler zu vermeiden.

Verwenden Sie Zod (oder das bevorzugte Schemaformat des SDKs) für die Eingabevalidierung.

Best Practices

• Schema zuerst: Definieren Sie Eingabeschemata für jedes Tool; dokumentieren Sie Parameter und Rückgabestruktur.
• Fehler: Geben Sie strukturierte Fehler oder Nachrichten zurück, die das Modell interpretieren kann; vermeiden Sie rohe Stack-Traces.
• Idempotenz: Bevorzugen Sie nach Möglichkeit idempotente Tools, damit Wiederholungen sicher sind.
• Raten und Kosten: Für Tools, die externe APIs aufrufen, berücksichtigen Sie Ratenbegrenzungen und Kosten; dokumentieren Sie dies in der Tool-Beschreibung.
• Versionierung: Fixieren Sie die SDK-Version in package.json; überprüfen Sie die Versionshinweise beim Upgrade.

Offizielle SDKs und Dokumente

• JavaScript/TypeScript: @modelcontextprotocol/sdk (npm). Verwenden Sie Context7 mit dem Bibliotheksnamen "MCP" für aktuelle Registrierungs- und Transportmuster.
• Go: Offizielles Go-SDK auf GitHub (modelcontextprotocol/go-sdk).
• C#: Offizielles C#-SDK für .NET.