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 Tools ermöglichen. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben zu bewältigen.

---

Prozess

🚀 High-Level-Workflow

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Recherche und Planung

1.1 Modernes MCP-Design verstehen

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

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

Kontextverwaltung: Agenten profitieren von präzisen Tool-Beschreibungen und der Möglichkeit, Ergebnisse zu filtern und zu paginieren. Entwerfen Sie Tools, die fokussierte, relevante Daten zurückgeben. Einige Clients unterstützen die 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

Navigieren Sie in der MCP-Spezifikation:

Beginnen Sie mit der Sitemap, um relevante Seiten zu finden: https://modelcontextprotocol.io/sitemap.xml

Rufen Sie dann bestimmte Seiten mit dem Suffix .md für das Markdown-Format ab (z. B. https://modelcontextprotocol.io/specification/draft.md).

Wichtige Seiten, die zu prüfen sind:

• Spezifikationsübersicht und Architektur
• Transportmechanismen (streamable HTTP, stdio)
• Tool-, Ressourcen- und Prompt-Definitionen

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 der breiten Nutzung, 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 die wichtigsten 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 gemeinsame 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 hinzu
• Fügen Sie Beispiele in Feldbeschreibungen hinzu

Ausgabeschema:

• Definieren Sie outputSchema, wo möglich, 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äzise Zusammenfassung der Funktionalität
• Parameterbeschreibungen
• Rückgabetypschema

Implementierung:

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

Annotationen:

• readOnlyHint: true/false
• destructiveHint: true/false
• idempotentHint: true/false
• openWorldHint: true/false

---

Phase 3: Überprüfung und Test

3.1 Code-Qualität

Überprüfen Sie auf:

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

3.2 Build und Test

TypeScript:

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

Python:

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

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

---

Phase 4: Evaluierungen erstellen

Nach der Implementierung Ihres MCP-Servers erstellen Sie umfassende Evaluierungen, um seine Effektivität zu testen.

Laden Sie den ✅ Evaluierungsleitfaden für vollständige Evaluierungsrichtlinien.

4.1 Zweck der Evaluierung verstehen

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

4.2 10 Evaluierungsfragen erstellen

Um effektive Evaluierungen zu erstellen, befolgen Sie den im Evaluierungsleitfaden beschriebenen Prozess:

1. Tool-Inspektion: Verfügbare Tools auflisten und ihre Fähigkeiten verstehen
2. Inhaltserkundung: READ-ONLY-Operationen verwenden, um verfügbare Daten zu erkunden
3. Fragengenerierung: 10 komplexe, realistische Fragen erstellen
4. Antwortüberprüfung: Jede Frage selbst lösen, um die Antworten zu überprüfen

4.3 Evaluierungsanforderungen

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 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 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 dem Suffix .md 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 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

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ühren einer Evaluierung mit den bereitgestellten Skripten