mcp-builder

Leitfaden zur MCP-Serverentwicklung

Überblick

Um hochwertige MCP (Model Context Protocol)-Server zu erstellen, die LLMs eine effektive Interaktion mit externen Diensten ermöglichen, verwende diesen 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 bewältigen.

---

Prozess

🚀 High-Level-Workflow

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Tiefgreifende Recherche und Planung

1.1 Agentenzentrierte Designprinzipien verstehen

Bevor du mit der Implementierung beginnst, solltest du verstehen, wie Tools für KI-Agenten entworfen werden. Überprüfe dazu diese Prinzipien:

Für Workflows bauen, nicht nur für API-Endpunkte:

• Wickle nicht einfach vorhandene API-Endpunkte – baue durchdachte, wirkungsvolle Workflow-Tools
• Konsolidiere verwandte Operationen (z. B. schedule_event, das sowohl die Verfügbarkeit prüft als auch ein Ereignis erstellt)
• Konzentriere dich auf Tools, die vollständige Aufgaben ermöglichen, nicht nur einzelne API-Aufrufe
• Überlege, welche Workflows Agenten tatsächlich benötigen

Optimierung für begrenzten Kontext:

• Agenten haben begrenzte Kontextfenster – mach jeden Token zählbar
• Gib Informationen mit hoher Signalstärke zurück, keine erschöpfenden Datenausschüttungen
• Biete Optionen für "präzise" vs. "detaillierte" Antwortformate an
• Verwende standardmäßig menschenlesbare Identifikatoren anstelle von technischen Codes (Namen statt IDs)
• Betrachte das Kontextbudget des Agenten als knappe Ressource

Gestaltung umsetzbarer Fehlermeldungen:

• Fehlermeldungen sollten Agenten zu korrektem Nutzungsverhalten führen
• Schlage spezifische nächste Schritte vor: "Versuche, filter='active_only' zu verwenden, um die Ergebnisse zu reduzieren"
• Mach Fehler lehrreich, nicht nur diagnostisch
• Hilf Agenten, die korrekte Tool-Nutzung durch klares Feedback zu erlernen

Befolge natürliche Aufgabenunterteilungen:

• Toolnamen sollten widerspiegeln, wie Menschen über Aufgaben denken
• Gruppiere verwandte Tools mit konsistenten Präfixen für die Auffindbarkeit
• Gestalte Tools um natürliche Workflows herum, nicht nur um die API-Struktur

Evaluationsgetriebene Entwicklung nutzen:

• Erstelle frühzeitig realistische Evaluierungsszenarien
• Lass Tool-Verbesserungen durch Agenten-Feedback steuern
• Prototypisiere schnell und iteriere basierend auf der tatsächlichen Agentenleistung

1.3 MCP-Protokolldokumentation studieren

Die neueste MCP-Protokolldokumentation abrufen:

Verwende 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

Lade und lies die folgenden Referenzdateien:

• MCP Best Practices: 📋 Best Practices anzeigen – Kernrichtlinien für alle MCP-Server

Für Python-Implementierungen lade außerdem:

• Python SDK-Dokumentation: Verwende WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md zu laden
• 🐍 Python-Implementierungsleitfaden – Python-spezifische Best Practices und Beispiele

Für Node/TypeScript-Implementierungen lade außerdem:

• TypeScript SDK-Dokumentation: Verwende WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md zu laden
• ⚡ TypeScript-Implementierungsleitfaden – Node/TypeScript-spezifische Best Practices und Beispiele

1.5 API-Dokumentation erschöpfend studieren

Um einen Dienst zu integrieren, lies alle verfügbaren API-Dokumentationen durch:

• Offizielle API-Referenzdokumentation
• Authentifizierungs- und Autorisierungsanforderungen
• Rate-Limiting- und Paginierungsmuster
• Fehlerantworten und Statuscodes
• Verfügbare Endpunkte und deren Parameter
• Datenmodelle und Schemata

Verwende bei Bedarf Websuche und das WebFetch-Tool, um umfassende Informationen zu sammeln.

1.6 Einen umfassenden Implementierungsplan erstellen

Erstelle basierend auf deiner Recherche einen detaillierten Plan, der Folgendes umfasst:

Tool-Auswahl:

• Liste die wertvollsten zu implementierenden Endpunkte/Operationen auf
• Priorisiere Tools, die die häufigsten und wichtigsten Anwendungsfälle ermöglichen
• Überlege, welche Tools zusammenarbeiten, um komplexe Workflows zu ermöglichen

Gemeinsame Hilfsprogramme:

• Identifiziere häufige API-Anforderungsmuster
• Plane Paginierungs-Helfer
• Gestalte Filter- und Formatierungshilfsprogramme
• Plane Fehlerbehandlungsstrategien

Eingabe-/Ausgabedesign:

• Definiere Eingabevalidierungsmodelle (Pydantic für Python, Zod für TypeScript)
• Gestalte konsistente Antwortformate (z. B. JSON oder Markdown) und konfigurierbare Detaillierungsgrade (z. B. Detailliert oder Präzise)
• Plane für die Nutzung in großem Maßstab (Tausende von Benutzern/Ressourcen)
• Implementiere Zeichenbegrenzungen und Kürzungsstrategien (z. B. 25.000 Token)

Fehlerbehandlungsstrategie:

• Plane anmutige Fehlermodi
• Gestalte klare, umsetzbare, LLM-freundliche, natürlichsprachliche Fehlermeldungen, die zu weiteren Aktionen auffordern
• Berücksichtige Rate-Limiting- und Timeout-Szenarien
• Behandle Authentifizierungs- und Autorisierungsfehler

---

Phase 2: Implementierung

Nachdem du einen umfassenden Plan erstellt hast, beginne mit der Implementierung gemäß den sprachspezifischen Best Practices.

2.1 Projektstruktur einrichten

Für Python:

• Erstelle eine einzelne .py-Datei oder organisiere sie in Modulen, wenn es komplex ist (siehe 🐍 Python-Leitfaden)
• Verwende das MCP Python SDK für die Tool-Registrierung
• Definiere Pydantic-Modelle für die Eingabevalidierung

Für Node/TypeScript:

• Erstelle eine geeignete Projektstruktur (siehe ⚡ TypeScript-Leitfaden)
• Richte package.json und tsconfig.json ein
• Verwende das MCP TypeScript SDK
• Definiere Zod-Schemata für die Eingabevalidierung

2.2 Kerninfrastruktur zuerst implementieren

Erstelle gemeinsame Hilfsprogramme, bevor du Tools implementierst:

• API-Anforderungs-Hilfsfunktionen
• Fehlerbehandlungs-Hilfsprogramme
• Funktionen zur Antwortformatierung (JSON und Markdown)
• Paginierungs-Helfer
• Authentifizierungs-/Token-Verwaltung

2.3 Tools systematisch implementieren

Für jedes Tool im Plan:

Eingabeschema definieren:

• Verwende Pydantic (Python) oder Zod (TypeScript) zur Validierung
• Füge geeignete Einschränkungen hinzu (Min-/Max-Länge, Regex-Muster, Min-/Max-Werte, Bereiche)
• Gib klare, beschreibende Feldbeschreibungen an
• Füge verschiedene Beispiele in Feldbeschreibungen ein

Umfassende Docstrings/Beschreibungen schreiben:

• Einzeilige Zusammenfassung, was das Tool tut
• 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:

• Verwende gemeinsame Hilfsprogramme, um Code-Duplizierung zu vermeiden
• Befolge async/await-Muster für alle E/A-Vorgänge
• Implementiere eine ordnungsgemäße Fehlerbehandlung
• Unterstütze mehrere Antwortformate (JSON und Markdown)
• Respektiere Paginierungsparameter
• Überprüfe Zeichenbegrenzungen und kürze gegebenenfalls

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 (wenn mit externen Systemen interagiert wird)

2.4 Sprachspezifische Best Practices befolgen

Lade an diesem Punkt den entsprechenden Sprachleitfaden:

Für Python: Lade 🐍 Python-Implementierungsleitfaden und stelle 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-Vorgänge
• Ordnungsgemäße Importorganisation
• Modulebene-Konstanten (CHARACTER_LIMIT, API_BASE_URL)

Für Node/TypeScript: Lade ⚡ TypeScript-Implementierungsleitfaden und stelle Folgendes sicher:

• Verwendung von server.registerTool korrekt
• Zod-Schemata mit .strict()
• TypeScript Strict Mode aktiviert
• Keine any-Typen – verwende geeignete Typen
• Explizite Promise-Rückgabetypen
• Build-Prozess konfiguriert (npm run build)

---

Phase 3: Überprüfen und Verfeinern

Nach der ersten Implementierung:

3.1 Codequalitätsprüfung

Überprüfe den Code auf folgende Qualitätsmerkmale:

• DRY-Prinzip: Kein duplizierter Code zwischen Tools
• Zusammensetzbarkeit: 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 auf Anfragen über stdio/stdin oder sse/http warten. Wenn du sie direkt in deinem Hauptprozess ausführst (z. B. python server.py oder node dist/index.js), bleibt dein Prozess unbegrenzt hängen.

Sichere Wege zum Testen des Servers:

• Verwende die Evaluierungsumgebung (siehe Phase 4) – empfohlener Ansatz
• Führe den Server in tmux aus, um ihn außerhalb deines Hauptprozesses zu halten
• Verwende ein Timeout beim Testen: timeout 5s python server.py

Für Python:

• Überprüfe die Python-Syntax: python -m py_compile your_server.py
• Überprüfe, ob Imports korrekt funktionieren, indem du die Datei durchgehst
• Manuelles Testen: Server in tmux ausführen, dann mit der Evaluierungsumgebung im Hauptprozess testen
• Oder verwende die Evaluierungsumgebung direkt (sie verwaltet den Server für den stdio-Transport)

Für Node/TypeScript:

• Führe npm run build aus und stelle sicher, dass es ohne Fehler abgeschlossen wird
• Überprüfe, ob dist/index.js erstellt wurde
• Manuelles Testen: Server in tmux ausführen, dann mit der Evaluierungsumgebung im Hauptprozess testen
• Oder verwende die Evaluierungsumgebung direkt (sie verwaltet den Server für den stdio-Transport)

3.3 Qualitäts-Checkliste verwenden

Lade die entsprechende Checkliste aus dem sprachspezifischen Leitfaden, um die Implementierungsqualität zu überprüfen:

• Python: siehe "Qualitäts-Checkliste" im 🐍 Python-Leitfaden
• Node/TypeScript: siehe "Qualitäts-Checkliste" im ⚡ TypeScript-Leitfaden

---

Phase 4: Evaluierungen erstellen

Nachdem du deinen MCP-Server implementiert hast, erstelle umfassende Evaluierungen, um seine Effektivität zu testen.

Lade ✅ Evaluierungsleitfaden für vollständige Evaluierungsrichtlinien.

4.1 Evaluierungszweck verstehen

Evaluierungen testen, ob LLMs deinen MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.

4.2 10 Evaluierungsfragen erstellen

Befolge den im Evaluierungsleitfaden beschriebenen Prozess, um effektive Evaluierungen zu erstellen:

1. Tool-Inspektion: Liste die verfügbaren Tools auf und verstehe ihre Fähigkeiten
2. Inhaltserkundung: Verwende schreibgeschützte Operationen, um verfügbare Daten zu erkunden
3. Fragengenerierung: Erstelle 10 komplexe, realistische Fragen
4. Antwortüberprüfung: Löse jede Frage selbst, um die Antworten zu überprüfen

4.3 Evaluierungsanforderungen

Jede Frage muss:

• Unabhängig sein: Nicht von anderen Fragen abhängig
• Schreibgeschützt sein: Nur nicht-destruktive Operationen erforderlich
• Komplex sein: Mehrere Tool-Aufrufe und tiefgehende Erkundung erforderlich
• Realistisch sein: Basierend auf realen Anwendungsfällen, die Menschen wichtig sind
• Überprüfbar sein: Einzelne, klare Antwort, die durch String-Vergleich überprüft werden kann
• Stabil sein: Antwort ändert sich im Laufe der Zeit nicht

4.4 Ausgabeformat

Erstelle eine XML-Datei mit dieser Struktur:

<evaluation>
  <qa_pair>
    <question>Finde 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 Modell bestimmt, das nach einer gefleckten Wildkatze benannt ist?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Weitere qa_pairs... -->
</evaluation>

---

Referenzdateien

📚 Dokumentationsbibliothek

Lade diese Ressourcen nach 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:
  • Server- und Tool-Namenskonventionen
  • Richtlinien für Antwortformate (JSON vs. Markdown)
  • Best Practices für 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-Initialisierungsmustern
  • Pydantic-Modellbeispielen
  • Tool-Registrierung mit @mcp.tool
  • Vollständigen funktionierenden Beispielen
  • Qualitäts-Checkliste

• ⚡ TypeScript-Implementierungsleitfaden – Vollständiger TypeScript-Leitfaden mit:

  • Projektstruktur
  • Zod-Schema-Mustern
  • Tool-Registrierung mit server.registerTool
  • Vollständigen funktionierenden Beispielen
  • Qualitäts-Checkliste

Evaluierungsleitfaden (während Phase 4 laden)

• ✅ Evaluierungsleitfaden