Leitfaden zur MCP-Serverentwicklung
Überblick
Erstelle MCP-Server (Model Context Protocol), die LLMs die Interaktion mit externen Diensten durch gut gestaltete Tools ermöglichen. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben zu erledigen.
Prozess
🚀 Ablauf auf hoher Ebene
Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:
Phase 1: Gründliche Recherche und Planung
1.1 Modernes MCP-Design verstehen
API-Abdeckung vs. Workflow-Tools: Bringe eine umfassende Abdeckung von API-Endpunkten mit spezialisierten Workflow-Tools in Einklang. Workflow-Tools können für bestimmte Aufgaben praktischer sein, während eine umfassende Abdeckung Agenten die Flexibilität gibt, Operationen zu kombinieren. Die Leistung variiert je nach Client – manche Clients profitieren von Codeausführung, die Basistools kombiniert, während andere besser mit übergeordneten Workflows arbeiten. Bei Unsicherheit priorisiere eine umfassende API-Abdeckung.
Tool-Benennung und Auffindbarkeit:
Klare, beschreibende Tool-Namen helfen Agenten, die richtigen Tools schnell zu finden. Verwende 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. Gestalte Tools, die fokussierte, relevante Daten zurückgeben. Manche Clients unterstützen Codeausführung, was Agenten helfen kann, Daten effizient zu filtern und zu verarbeiten.
Handlungsorientierte Fehlermeldungen: Fehlermeldungen sollten Agenten mit spezifischen Vorschlägen und nächsten Schritten zur Lösung führen.
1.2 MCP-Protokolldokumentation studieren
Navigiere durch die MCP-Spezifikation:
Beginne mit der Sitemap, um relevante Seiten zu finden: https://modelcontextprotocol.io/sitemap.xml
Rufe 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überblick 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 wie 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.
Lade die Framework-Dokumentation:
- MCP Best Practices: 📋 Best Practices ansehen – Kernrichtlinien
Für TypeScript (empfohlen):
- TypeScript SDK: Verwende WebFetch, um
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdzu laden - ⚡ TypeScript-Anleitung – TypeScript-Muster und Beispiele
Für Python:
- Python SDK: Verwende WebFetch, um
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdzu laden - 🐍 Python-Anleitung – Python-Muster und Beispiele
1.4 Implementierung planen
Die API verstehen: Überprüfe die API-Dokumentation des Dienstes, um wichtige Endpunkte, Authentifizierungsanforderungen und Datenmodelle zu identifizieren. Verwende bei Bedarf Websuche und WebFetch.
Tool-Auswahl: Priorisiere eine umfassende API-Abdeckung. Liste die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Operationen.
Phase 2: Implementierung
2.1 Projektstruktur einrichten
Siehe sprachspezifische Anleitungen zur Projekteinrichtung:
- ⚡ TypeScript-Anleitung – Projektstruktur, package.json, tsconfig.json
- 🐍 Python-Anleitung – Modulorganisation, Abhängigkeiten
2.2 Kerninfrastruktur implementieren
Erstelle gemeinsam genutzte Hilfsprogramme:
- API-Client mit Authentifizierung
- Fehlerbehandlungs-Helfer
- Antwortformatierung (JSON/Markdown)
- Paginierungsunterstützung
2.3 Tools implementieren
Für jedes Tool:
Eingabeschema:
- Verwende Zod (TypeScript) oder Pydantic (Python)
- Füge Einschränkungen und klare Beschreibungen hinzu
- Füge Beispiele in Feldbeschreibungen ein
Ausgabeschema:
- Definiere
outputSchemawo möglich für strukturierte Daten - Verwende
structuredContentin Tool-Antworten (TypeScript SDK-Funktion) - Hilft Clients, Tool-Ausgaben zu verstehen und zu verarbeiten
Tool-Beschreibung:
- Prägnante Zusammenfassung der Funktionalität
- Parameterbeschreibungen
- Schema des Rückgabetyps
Implementierung:
- Async/await für I/O-Operationen
- Ordnungsgemäße Fehlerbehandlung mit handlungsorientierten Meldungen
- Unterstützung von Paginierung, wo zutreffend
- Rückgabe von Textinhalten und strukturierten Daten bei Verwendung moderner SDKs
Annotationen:
readOnlyHint: true/falsedestructiveHint: true/falseidempotentHint: true/falseopenWorldHint: true/false
Phase 3: Überprüfung und Test
3.1 Codequalität
Überprüfe auf:
- Keinen doppelten Code (DRY-Prinzip)
- Einheitliche Fehlerbehandlung
- Vollständige Typabdeckung
- Klare Tool-Beschreibungen
3.2 Bauen und Testen
TypeScript:
- Führe
npm run buildaus, um die Kompilierung zu überprüfen - Teste mit MCP Inspector:
npx @modelcontextprotocol/inspector
Python:
- Überprüfe die Syntax:
python -m py_compile your_server.py - Teste mit MCP Inspector
Siehe sprachspezifische Anleitungen für detaillierte Testansätze und Qualitätschecklisten.
Phase 4: Evaluierungen erstellen
Nach der Implementierung deines MCP-Servers erstelle umfassende Evaluierungen, um seine Effektivität zu testen.
Lade ✅ Evaluierungsanleitung für vollständige Evaluierungsrichtlinien.
4.1 Evaluierungszweck verstehen
Verwende Evaluierungen, um zu testen, ob LLMs deinen MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.
4.2 10 Evaluierungsfragen erstellen
Um effektive Evaluierungen zu erstellen, folge dem in der Evaluierungsanleitung beschriebenen Prozess:
- Tool-Inspektion: Liste verfügbare Tools auf und verstehe ihre Fähigkeiten
- Inhaltserkundung: Verwende SCHREIBGESCHÜTZTE Operationen, um verfügbare Daten zu erkunden
- Fragenerstellung: Erstelle 10 komplexe, realistische Fragen
- Antwortüberprüfung: Löse jede Frage selbst, um Antworten zu verifizieren
4.3 Evaluierungsanforderungen
Stelle 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 verifiziert werden kann
- Stabil: 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-Modellstarts mit Tier-Codenamen. Ein Modell benötigte eine spezifische Sicherheitskennzeichnung, 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 bei Bedarf während der Entwicklung:
Kern-MCP-Dokumentation (zuerst laden)
- MCP-Protokoll: Beginne mit der Sitemap unter
https://modelcontextprotocol.io/sitemap.xml, rufe dann bestimmte Seiten mit dem Suffix.mdab - 📋 MCP Best Practices – Universelle MCP-Richtlinien einschließlich:
- Server- und Tool-Benennungskonventionen
- 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 Implementierungsanleitungen (während Phase 2 laden)
-
🐍 Python-Implementierungsanleitung – Vollständige Python/FastMCP-Anleitung mit:
- Server-Initialisierungsmustern
- Pydantic-Modellbeispielen
- Tool-Registrierung mit
@mcp.tool - Vollständigen funktionierenden Beispielen
- Qualitätscheckliste
-
⚡ TypeScript-Implementierungsanleitung – Vollständige TypeScript-Anleitung mit:
- Projektstruktur
- Zod-Schema-Mustern
- Tool-Registrierung mit
server.registerTool - Vollständigen funktionierenden Beispielen
- Qualitätscheckliste
Evaluierungsanleitung (während Phase 4 laden)
- ✅ Evaluierungsanleitung – Vollständige Anleitung zur Erstellung von Evaluierungen mit:
- Richtlinien zur Fragenerstellung
- Strategien zur Antwortüberprüfung
- XML-Format-Spezifikationen
- Beispielfragen und -antworten
- Ausführen einer Evaluierung mit den bereitgestellten Skripten