Leitfaden zur MCP-Serverentwicklung
Übersicht
Um hochwertige MCP (Model Context Protocol)-Server zu erstellen, die LLMs die effektive Interaktion mit externen Diensten ermöglichen, verwenden Sie dieses Skill. Ein MCP-Server stellt Tools bereit, mit denen LLMs auf externe Dienste und APIs zugreifen können. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben mit den bereitgestellten Tools zu erledigen.
Prozess
🚀 High-Level-Workflow
Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:
Phase 1: Gründliche Recherche und Planung
1.1 Grundsätze des agentenzentrierten Designs verstehen
Bevor Sie mit der Implementierung beginnen, sollten Sie die Grundsätze des Tool-Designs für KI-Agenten verstehen, indem Sie diese Prinzipien prüfen:
Für Workflows entwickeln, nicht nur für API-Endpunkte:
- Wickeln Sie nicht einfach bestehende API-Endpunkte ein – entwickeln Sie durchdachte, wirkungsvolle Workflow-Tools
- Konsolidieren Sie verwandte Operationen (z. B.
schedule_event, das sowohl die Verfügbarkeit prüft als auch ein Ereignis erstellt) - Konzentrieren Sie sich auf Tools, die vollständige Aufgaben ermöglichen, nicht nur einzelne API-Aufrufe
- Überlegen Sie, welche Workflows Agenten tatsächlich benötigen
Für begrenzten Kontext optimieren:
- Agenten haben begrenzte Kontextfenster – machen Sie jedes Token wertvoll
- Geben Sie Informationen mit hohem Signalgehalt zurück, keine erschöpfenden Datenmengen
- Bieten Sie Optionen für „kurzgefasst“ vs. „detailliert“ an
- Verwenden Sie standardmäßig lesbare Identifikatoren anstelle von technischen Codes (Namen statt IDs)
- Betrachten Sie das Kontextbudget des Agenten als knappe Ressource
Handlungsorientierte Fehlermeldungen gestalten:
- Fehlermeldungen sollten Agenten zu korrekten Nutzungsmustern führen
- Schlagen Sie spezifische nächste Schritte vor: „Versuchen Sie filter='active_only', um die Ergebnisse einzuschränken“
- Machen Sie Fehler lehrreich, nicht nur diagnostisch
- Helfen Sie Agenten, durch klares Feedback die richtige Tool-Nutzung zu erlernen
Natürlichen Aufgabenteilungen folgen:
- Tool-Namen sollten widerspiegeln, wie Menschen über Aufgaben denken
- Gruppieren Sie verwandte Tools mit konsistenten Präfixen für eine bessere Auffindbarkeit
- Entwerfen Sie Tools um natürliche Workflows herum, nicht nur um die API-Struktur
Evaluierungsgetriebene Entwicklung verwenden:
- Erstellen Sie frühzeitig realistische Evaluierungsszenarien
- Lassen Sie sich durch das Feedback von Agenten zu Tool-Verbesserungen leiten
- Prototypen Sie schnell und iterieren Sie basierend auf der tatsächlichen Agentenleistung
1.3 MCP-Protokolldokumentation studieren
Die neueste MCP-Protokolldokumentation abrufen:
Verwenden Sie WebFetch, um zu laden: https://modelcontextprotocol.io/llms-full.txt
Dieses umfassende Dokument enthält die vollständige MCP-Spezifikation und Richtlinien.
1.4 Framework-Dokumentation studieren
Laden und lesen Sie die folgenden Referenzdateien:
- MCP Best Practices: 📋 Best Practices anzeigen – Kernrichtlinien für alle MCP-Server
Laden Sie für Python-Implementierungen auch:
- Python SDK Dokumentation: Verwenden Sie WebFetch, um zu laden
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Python-Implementierungsleitfaden – Python-spezifische Best Practices und Beispiele
Laden Sie für Node/TypeScript-Implementierungen auch:
- TypeScript SDK Dokumentation: Verwenden Sie WebFetch, um zu laden
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ TypeScript-Implementierungsleitfaden – Node/TypeScript-spezifische Best Practices und Beispiele
1.5 API-Dokumentation erschöpfend studieren
Um einen Dienst zu integrieren, lesen Sie die GESAMTE verfügbare API-Dokumentation:
- Offizielle API-Referenzdokumentation
- Authentifizierungs- und Autorisierungsanforderungen
- Ratenbegrenzungs- und Paginierungsmuster
- Fehlerantworten und Statuscodes
- Verfügbare Endpunkte und deren Parameter
- Datenmodelle und Schemata
Verwenden Sie bei Bedarf Websuche und das WebFetch-Tool, um umfassende Informationen zu sammeln.
1.6 Einen umfassenden Implementierungsplan erstellen
Erstellen Sie basierend auf Ihrer Recherche einen detaillierten Plan, der Folgendes umfasst:
Tool-Auswahl:
- Listen Sie die wertvollsten Endpunkte/Operationen auf, die implementiert werden sollen
- Priorisieren Sie Tools, die die häufigsten und wichtigsten Anwendungsfälle ermöglichen
- Überlegen Sie, welche Tools zusammenarbeiten, um komplexe Workflows zu ermöglichen
Gemeinsame Dienstprogramme und Hilfsfunktionen:
- Identifizieren Sie gemeinsame API-Anforderungsmuster
- Planen Sie Paginierungs-Hilfsfunktionen
- Entwerfen Sie Filter- und Formatierungs-Dienstprogramme
- Planen Sie Strategien zur Fehlerbehandlung
Eingabe-/Ausgabe-Design:
- Definieren Sie Eingabevalidierungsmodelle (Pydantic für Python, Zod für TypeScript)
- Entwerfen Sie konsistente Antwortformate (z. B. JSON oder Markdown) und konfigurierbare Detailtiefen (z. B. Detailliert oder Kurzgefasst)
- Planen Sie für die Nutzung in großem Maßstab (Tausende von Benutzern/Ressourcen)
- Implementieren Sie Zeichenbegrenzungen und Kürzungsstrategien (z. B. 25.000 Token)
Strategie zur Fehlerbehandlung:
- Planen Sie fehlertolerante Fehlermodi
- Entwerfen Sie klare, handlungsorientierte, LLM-freundliche Fehlermeldungen in natürlicher Sprache, die zu weiteren Aktionen auffordern
- Berücksichtigen Sie Ratenbegrenzungs- und Timeout-Szenarien
- Behandeln Sie Authentifizierungs- und Autorisierungsfehler
Phase 2: Implementierung
Nachdem Sie einen umfassenden Plan erstellt haben, beginnen Sie mit der Implementierung gemäß den sprachspezifischen Best Practices.
2.1 Projektstruktur einrichten
Für Python:
- Erstellen Sie eine einzelne
.py-Datei oder organisieren Sie sie bei Komplexität in Module (siehe 🐍 Python Leitfaden) - Verwenden Sie das MCP Python SDK zur Tool-Registrierung
- Definieren Sie Pydantic-Modelle für die Eingabevalidierung
Für Node/TypeScript:
- Erstellen Sie eine geeignete Projektstruktur (siehe ⚡ TypeScript Leitfaden)
- Richten Sie
package.jsonundtsconfig.jsonein - Verwenden Sie das MCP TypeScript SDK
- Definieren Sie Zod-Schemata für die Eingabevalidierung
2.2 Zuerst die Kerninfrastruktur implementieren
Erstellen Sie vor der Implementierung der Tools gemeinsame Dienstprogramme:
- Hilfsfunktionen für API-Anfragen
- Dienstprogramme zur Fehlerbehandlung
- Funktionen zur Formatierung von Antworten (JSON und Markdown)
- Paginierungs-Hilfsfunktionen
- Authentifizierungs-/Token-Verwaltung
2.3 Tools systematisch implementieren
Für jedes Tool im Plan:
Eingabeschema definieren:
- Verwenden Sie Pydantic (Python) oder Zod (TypeScript) zur Validierung
- Fügen Sie geeignete Einschränkungen hinzu (min/max Länge, Regex-Muster, min/max Werte, Bereiche)
- Geben Sie klare, beschreibende Feldbeschreibungen an
- Fügen Sie verschiedene Beispiele in Feldbeschreibungen ein
Umfassende Docstrings/Beschreibungen schreiben:
- Einzeilige Zusammenfassung der Funktionalität des Tools
- Detaillierte Erklärung des Zwecks und der Funktionalität
- Explizite Parametertypen mit Beispielen
- Vollständiges Rückgabetyp-Schema
- Anwendungsbeispiele (wann verwenden, wann nicht verwenden)
- Dokumentation zur Fehlerbehandlung, die beschreibt, wie bei bestimmten Fehlern vorzugehen ist
Tool-Logik implementieren:
- Verwenden Sie gemeinsame Dienstprogramme, um Code-Duplizierung zu vermeiden
- Befolgen Sie async/await-Muster für alle E/A-Vorgänge
- Implementieren Sie eine ordnungsgemäße Fehlerbehandlung
- Unterstützen Sie mehrere Antwortformate (JSON und Markdown)
- Respektieren Sie Paginierungsparameter
- Überprüfen Sie Zeichenbegrenzungen und kürzen Sie entsprechend
Tool-Anmerkungen hinzufügen:
readOnlyHint: true (für schreibgeschützte Operationen)destructiveHint: false (für nicht-destruktive Operationen)idempotentHint: true (wenn wiederholte Aufrufe den gleichen Effekt haben)openWorldHint: true (bei Interaktion mit externen Systemen)
2.4 Sprachspezifische Best Practices befolgen
Laden Sie nun den entsprechenden Sprachleitfaden:
Für Python: Laden Sie 🐍 Python-Implementierungsleitfaden und stellen Sie Folgendes sicher:
- Verwendung des MCP Python SDK mit ordnungsgemäßer Tool-Registrierung
- Pydantic v2-Modelle mit
model_config - Typannotationen durchgängig
- Async/await für alle E/A-Operationen
- Ordnungsgemäße Importorganisation
- Modulebene-Konstanten (CHARACTER_LIMIT, API_BASE_URL)
Für Node/TypeScript: Laden Sie ⚡ TypeScript-Implementierungsleitfaden und stellen Sie Folgendes sicher:
- Korrekte Verwendung von
server.registerTool - Zod-Schemata mit
.strict() - TypeScript Strict Mode aktiviert
- Keine
any-Typen – verwenden Sie geeignete Typen - Explizite
Promise<T>-Rückgabetypen - Build-Prozess konfiguriert (
npm run build)
Phase 3: Überprüfung und Verfeinerung
Nach der ersten Implementierung:
3.1 Code-Qualitätsprüfung
Überprüfen Sie den Code auf Qualität:
- DRY-Prinzip: Kein doppelter Code zwischen Tools
- Komponierbarkeit: Gemeinsame Logik in Funktionen extrahiert
- Konsistenz: Ähnliche Operationen geben ähnliche Formate zurück
- Fehlerbehandlung: Alle externen Aufrufe haben eine Fehlerbehandlung
- Typsicherheit: Vollständige Typabdeckung (Python-Typannotationen, TypeScript-Typen)
- Dokumentation: Jedes Tool hat umfassende Docstrings/Beschreibungen
3.2 Testen und Bauen
Wichtig: MCP-Server sind langlebige Prozesse, die über stdio/stdin oder sse/http auf Anfragen warten. Wenn Sie sie direkt in Ihrem Hauptprozess ausführen (z. B. python server.py oder node dist/index.js), bleibt Ihr Prozess auf unbestimmte Zeit hängen.
Sichere Möglichkeiten zum Testen des Servers:
- Verwenden Sie die Evaluierungsumgebung (siehe Phase 4) – empfohlener Ansatz
- Führen Sie den Server in tmux aus, um ihn außerhalb Ihres Hauptprozesses zu halten
- Verwenden Sie ein Timeout beim Testen:
timeout 5s python server.py
Für Python:
- Überprüfen Sie die Python-Syntax:
python -m py_compile your_server.py - Überprüfen Sie, ob die Importe korrekt funktionieren, indem Sie die Datei prüfen
- Für manuelle Tests: Server in tmux ausführen, dann mit der Evaluierungsumgebung im Hauptprozess testen
- Oder verwenden Sie direkt die Evaluierungsumgebung (sie verwaltet den Server für den stdio-Transport)
Für Node/TypeScript:
- Führen Sie
npm run buildaus und stellen Sie sicher, dass es fehlerfrei abschließt - Überprüfen Sie, ob dist/index.js erstellt wurde
- Für manuelle Tests: Server in tmux ausführen, dann mit der Evaluierungsumgebung im Hauptprozess testen
- Oder verwenden Sie direkt die Evaluierungsumgebung (sie verwaltet den Server für den stdio-Transport)
3.3 Qualitätscheckliste verwenden
Laden Sie zur Überprüfung der Implementierungsqualität die entsprechende Checkliste aus dem sprachspezifischen Leitfaden:
- Python: siehe „Qualitätscheckliste“ in 🐍 Python Leitfaden
- Node/TypeScript: siehe „Qualitätscheckliste“ in ⚡ TypeScript Leitfaden
Phase 4: Evaluierungen erstellen
Nach der Implementierung Ihres MCP-Servers erstellen Sie umfassende Evaluierungen, um seine Effektivität zu testen.
Laden Sie ✅ Evaluierungsleitfaden für vollständige Evaluierungsrichtlinien.
4.1 Evaluierungszweck verstehen
Evaluierungen testen, ob LLMs Ihren MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.
4.2 10 Evaluierungsfragen erstellen
Befolgen Sie zur Erstellung effektiver Evaluierungen den im Evaluierungsleitfaden beschriebenen Prozess:
- Tool-Inspektion: Listen Sie verfügbare Tools auf und verstehen Sie deren Fähigkeiten
- Inhaltserkundung: Verwenden Sie SCHREIBGESCHÜTZTE Operationen, um verfügbare Daten zu erkunden
- Fragengenerierung: Erstellen Sie 10 komplexe, realistische Fragen
- Antwortüberprüfung: Lösen Sie jede Frage selbst, um die Antworten zu überprüfen
4.3 Evaluierungsanforderungen
Jede Frage muss sein:
- Unabhängig: Nicht von anderen Fragen abhängig
- Schreibgeschützt: Es werden nur nicht-destruktive Operationen benötigt
- Komplex: Mehrere Tool-Aufrufe und tiefgehende Erkundung erforderlich
- Realistisch: Basierend auf realen Anwendungsfällen, die für Menschen relevant sind
- Überprüfbar: Einzelne, klare Antwort, die durch String-Vergleich überprüft werden kann
- Stabil: Antwort ändert sich im Laufe der Zeit nicht
4.4 Ausgabeformat
Erstellen Sie eine XML-Datei mit dieser Struktur:
<evaluation>
<qa_pair>
<question>Finden Sie Diskussionen über KI-Modellveröffentlichungen mit Tier-Codenamen. Ein Modell benötigte eine spezifische Sicherheitsbezeichnung, die das Format ASL-X verwendet. Welche Zahl X wurde für das nach einer gefleckten Wildkatze benannte Modell bestimmt?</question>
<answer>3</answer>
</qa_pair>
<!-- Weitere qa_pairs... -->
</evaluation>
Referenzdateien
📚 Dokumentationsbibliothek
Laden Sie diese Ressourcen bei Bedarf während der Entwicklung:
Kern-MCP-Dokumentation (zuerst laden)
- MCP-Protokoll: Abrufen von
https://modelcontextprotocol.io/llms-full.txt– Vollständige MCP-Spezifikation - 📋 MCP Best Practices – Universelle MCP-Richtlinien einschließlich:
- Namenskonventionen für Server und Tools
- Richtlinien für Antwortformate (JSON vs. Markdown)
- Best Practices zur Paginierung
- Zeichenbegrenzungen und Kürzungsstrategien
- Richtlinien zur Tool-Entwicklung
- Sicherheits- und Fehlerbehandlungsstandards
SDK-Dokumentation (während Phase 1/2 laden)
- Python SDK: Abrufen von
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - TypeScript SDK: Abrufen von
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Sprachspezifische Implementierungsleitfäden (während Phase 2 laden)
-
🐍 Python-Implementierungsleitfaden – Vollständiger Python/FastMCP-Leitfaden mit:
- Server-Initialisierungsmuster
- Pydantic-Modellbeispiele
- Tool-Registrierung mit
@mcp.tool - Vollständige funktionierende Beispiele
- Qualitätscheckliste
-
⚡ TypeScript-Implementierungsleitfaden – Vollständiger TypeScript-Leitfaden mit:
- Projektstruktur
- Zod-Schema-Muster
- Tool-Registrierung mit
server.registerTool - Vollständige funktionierende Beispiele
- Qualitätscheckliste
Evaluierungsleitfaden (während Phase 4 laden)
- ✅ Evaluierungsleitfaden – Vollständiger Leitfaden zur Erstellung von Evaluierungen mit:
- Richtlinien zur Fragenerstellung
- Strategien zur Antwortüberprüfung
- XML-Formatspezifikationen
- Beispielfragen und -antworten
- Durchführung einer Evaluierung mit den bereitgestellten Skripten