MCP-Server-Entwicklungsleitfaden

Leitfaden zur MCP-Server-Entwicklung

Überblick

Erstellen Sie MCP-Server (Model Context Protocol), die LLMs die Interaktion mit externen Diensten durch durchdachte Werkzeuge ermöglichen. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs befähigt, reale Aufgaben zu erledigen.

---

Prozess

🚀 Hochrangiger Arbeitsablauf

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Tiefgehende Recherche und Planung

1.1 Modernes MCP-Design verstehen

API-Abdeckung vs. Workflow-Tools: Gleichen Sie eine umfassende Abdeckung der API-Endpunkte mit spezialisierten Workflow-Tools ab. Workflow-Tools können für bestimmte Aufgaben bequemer sein, während eine umfassende Abdeckung den Agenten Flexibilität bei der Zusammenstellung von Operationen bietet. Die Leistung variiert je nach Client – einige Clients profitieren von der Codeausführung, die grundlegende Werkzeuge kombiniert, während andere mit übergeordneten Workflows besser arbeiten. Wenn Sie unsicher sind, priorisieren Sie eine umfassende API-Abdeckung.

Benennung und Auffindbarkeit von Tools: Klare, beschreibende Tool-Namen helfen Agenten, die richtigen Werkzeuge schnell zu finden. Verwenden Sie konsistente Präfixe (z. B. github_create_issue, github_list_repos) und handlungsorientierte Benennung.

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

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

1.2 MCP-Protokolldokumentation studieren

Navigation 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 der .md-Endung für das Markdown-Format ab (z. B. https://modelcontextprotocol.io/specification/draft.md).

Wichtige Seiten zum Überprüfen:

• Spezifikationsüberblick und Architektur
• Transportmechanismen (streamable HTTP, stdio)
• Definitionen von Tools, Ressourcen und Prompts

1.3 Framework-Dokumentation studieren

Empfohlener Stack:

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

Framework-Dokumentation laden:

• MCP Best Practices: 📋 Best Practices ansehen - Kernrichtlinien

Für TypeScript (empfohlen):

• TypeScript-SDK: Verwenden Sie WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md zu laden
• ⚡ TypeScript-Leitfaden - TypeScript-Muster und Beispiele

Für Python:

• Python-SDK: Verwenden Sie WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md zu laden
• 🐍 Python-Leitfaden - Python-Muster und Beispiele

1.4 Implementierung planen

Die API verstehen: Überprüfen Sie die API-Dokumentation des Dienstes, um wichtige Endpunkte, Authentifizierungsanforderungen und Datenmodelle zu identifizieren. Verwenden Sie bei Bedarf Websuche und WebFetch.

Tool-Auswahl: Priorisieren Sie eine umfassende API-Abdeckung. Listen Sie die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Operationen.

---

Phase 2: Implementierung

2.1 Projektstruktur einrichten

Siehe sprachspezifische Anleitungen zur Projekteinrichtung:

• ⚡ TypeScript-Leitfaden - Projektstruktur, package.json, tsconfig.json
• 🐍 Python-Leitfaden - Modulorganisation, Abhängigkeiten

2.2 Kerninfrastruktur implementieren

Erstellen Sie gemeinsam genutzte Hilfsprogramme:

• API-Client mit Authentifizierung
• Hilfsprogramme zur Fehlerbehandlung
• Antwortformatierung (JSON/Markdown)
• Paginierungsunterstützung

2.3 Tools implementieren

Für jedes Tool:

Eingabeschema:

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

Ausgabeschema:

• Definieren Sie nach Möglichkeit outputSchema für strukturierte Daten
• Verwenden Sie structuredContent in Tool-Antworten (TypeScript-SDK-Funktion)
• Hilft Clients, Tool-Ausgaben zu verstehen und zu verarbeiten

Tool-Beschreibung:

• Prägnante Zusammenfassung der Funktionalität
• Parameterbeschreibungen
• Rückgabetypschema

Implementierung:

• Async/await für I/O-Operationen
• Ordnungsgemäße Fehlerbehandlung mit umsetzbaren Nachrichten
• Paginierung unterstützen, wo zutreffend
• Sowohl Textinhalt als auch strukturierte Daten zurückgeben, wenn moderne SDKs verwendet werden

Annotationen:

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

---

Phase 3: Überprüfen und Testen

3.1 Code-Qualität

Überprüfen auf:

• Keinen doppelten Code (DRY-Prinzip)
• Einheitliche Fehlerbehandlung
• Vollständige Typabdeckung
• Klare Tool-Beschreibungen

3.2 Builden und Testen

TypeScript:

• Führen Sie npm run build aus, um die Kompilierung zu überprüfen
• Testen Sie mit dem MCP Inspector: npx @modelcontextprotocol/inspector

Python:

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

Siehe sprachspezifische Anleitungen für detaillierte Testansätze und Qualitätschecklisten.

---

Phase 4: Auswertungen erstellen

Erstellen Sie nach der Implementierung Ihres MCP-Servers umfassende Auswertungen, um seine Effektivität zu testen.

Laden Sie den ✅ Auswertungsleitfaden für vollständige Richtlinien zur Auswertung.

4.1 Zweck der Auswertung verstehen

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

4.2 10 Auswertungsfragen erstellen

Um effektive Auswertungen zu erstellen, befolgen Sie den im Auswertungsleitfaden beschriebenen Prozess:

1. Tool-Inspektion: Verfügbare Tools auflisten und ihre Fähigkeiten verstehen
2. Inhaltserkundung: Verwenden Sie SCHREIBGESCHÜTZTE Operationen, um verfügbare Daten zu erkunden
3. Fragengenerierung: Erstellen Sie 10 komplexe, realistische Fragen
4. Antwortüberprüfung: Lösen Sie jede Frage selbst, um die Antworten zu überprüfen

4.3 Auswertungsanforderungen

Stellen Sie sicher, dass jede Frage:

• Unabhängig: Nicht von anderen Fragen abhängig
• Schreibgeschützt: Nur nicht-destruktive Operationen erforderlich
• Komplex: Mehrere Tool-Aufrufe und tiefgehende Erkundung erforderlich
• Realistisch: Basierend auf realen Anwendungsfällen, die Menschen interessieren
• Überprüfbar: Einzige, 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>Finden Sie Diskussionen über KI-Modellveröffentlichungen mit Tier-Codenamen. Ein Modell benötigte eine spezifische Sicherheitsbezeichnung im Format ASL-X. Welche Nummer 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: Beginnen Sie mit der Sitemap unter https://modelcontextprotocol.io/sitemap.xml, rufen Sie dann bestimmte Seiten mit der .md-Endung ab
• 📋 MCP Best Practices - Universelle MCP-Richtlinien, einschließlich:
  • Konventionen zur Benennung von Servern und Tools
  • Richtlinien zum Antwortformat (JSON vs. Markdown)
  • Best Practices für die Paginierung
  • Transportauswahl (streamable HTTP vs. stdio)
  • 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ätscheckliste

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

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

Auswertungsleitfaden (während Phase 4 laden)

• ✅ Auswertungsleitfaden - Vollständiger Leitfaden zur Erstellung von Auswertungen mit:
  • Richtlinien zur Fragenerstellung
  • Strategien zur Antwortüberprüfung
  • XML-Formatspezifikationen
  • Beispielfragen und -antworten
  • Durchführen einer Auswertung mit den bereitgestellten Skripten