MCP-Builder

Leitfaden zur MCP-Serverentwicklung

Übersicht

Erstellen Sie MCP-Server (Model Context Protocol), die es LLMs ermöglichen, über gut gestaltete Tools mit externen Diensten zu interagieren. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben zu bewältigen.

---

Prozess

🚀 Hochrangiger Workflow

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: Balancen Sie die umfassende Abdeckung von API-Endpunkten mit spezialisierten Workflow-Tools. Workflow-Tools können für bestimmte Aufgaben bequemer sein, während die umfassende Abdeckung den Agenten Flexibilität bei der Zusammensetzung von Vorgängen gibt. Die Leistung variiert je nach Client – einige Clients profitieren von Codeausführung, die grundlegende Tools kombiniert, während andere mit übergeordneten Workflows besser arbeiten. Wenn Sie unsicher sind, priorisieren Sie die umfassende API-Abdeckung.

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

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

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

1.2 MCP-Protokolldokumentation studieren

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

Wichtige Seiten, die Sie prüfen sollten:

• 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, profitierend von seiner breiten Nutzung, statischen Typisierung und guten Linting-Tools)
• Transport: Streamable HTTP für Remote-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 anzeigen - Kernrichtlinien

Für TypeScript (empfohlen):

Das TypeScript SDK hat zwei Hauptversionen. Wählen Sie eine aus, bevor Sie Code schreiben:

• v2 (@modelcontextprotocol/server): die aktuelle stabile Version. Verwenden Sie sie für neue Server.
• v1 (@modelcontextprotocol/sdk): erhält nur Fehler- und Sicherheitskorrekturen. Verwenden Sie es nur, wenn die package.json des Projekts bereits von @modelcontextprotocol/sdk abhängt, oder migrieren Sie dieses Projekt mit npx @modelcontextprotocol/codemod@latest v1-to-v2 .

Wenn das Projekt bereits v1 verwendet, informieren Sie den Benutzer einmal in ein oder zwei Sätzen, dass v2 (@modelcontextprotocol/server) die aktuelle stabile Version ist, dass v1 nur Fehler- und Sicherheitskorrekturen erhält und dass npx @modelcontextprotocol/codemod@latest v1-to-v2 . das Projekt migriert. Fahren Sie dann mit v1 fort, es sei denn, der Benutzer bittet um eine Migration.

Mischen Sie nicht beide in einem Projekt: Codebeispiele von v1 (Importe von @modelcontextprotocol/sdk/...) gelten nicht für v2.

• TypeScript SDK (v2): Verwenden Sie WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md zu laden; das vollständige Dokumentationsverzeichnis ist https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
• ⚡ TypeScript Guide (v2) - TypeScript-Muster und Beispiele
• Nur für v1-Projekte: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md und der TypeScript Guide (v1)

Für Python:

• Python SDK: Verwenden Sie WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md zu laden
• 🐍 Python Guide - 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 die umfassende API-Abdeckung. Listen Sie die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Vorgängen.

---

Phase 2: Implementierung

2.1 Projektstruktur einrichten

Siehe sprachspezifische Anleitungen für die Projekteinrichtung:

• ⚡ TypeScript Guide (v2) - Projektstruktur, package.json, tsconfig.json (v1 für bestehende v1-Projekte)
• 🐍 Python Guide - 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 ein

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

Toolbeschreibung:

• Prägnante Zusammenfassung der Funktionalität
• Parameterbeschreibungen
• Schema des Rückgabetyps

Implementierung:

• Async/await für E/A-Vorgänge
• Korrekte Fehlerbehandlung mit handlungsorientierten Meldungen
• Paginierung unterstützen, wo anwendbar
• 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 Codequalität

Überprüfen Sie auf:

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

3.2 Build und Test

TypeScript:

• Führen Sie npm run build aus, um die Kompilierung zu überprüfen
• v2-Projekte: Führen Sie das Selbstprüfungsskript aus dem v2 Guide gegen den gebauten Server aus
• 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: Evaluierungen erstellen

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

Laden Sie den ✅ Evaluierungs-Guide 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, folgen Sie dem im Evaluierungs-Leitfaden beschriebenen Prozess:

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

4.3 Evaluierungsanforderungen

Stellen Sie sicher, dass jede Frage:

• Unabhängig: Nicht von anderen Fragen abhängig ist
• Nur lesend: Nur nicht-destruktive Vorgänge erforderlich sind
• Komplex: Mehrere Tool-Aufrufe und tiefgehende Erkundung erfordert
• Realistisch: Auf realen Anwendungsfällen basiert, die Menschen betreffen
• Überprüfbar: Eine einzige, klare Antwort hat, die durch Zeichenfolgenvergleich überprüft werden kann
• Stabil: Die Antwort sich im Laufe der Zeit nicht ändert

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

---

Referenzdateien

📚 Dokumentationsbibliothek

Laden Sie diese Ressourcen nach 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:
  • Benennungskonventionen für Server 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 (v2): Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md; vollständiges Dokumentationsverzeichnis unter https://ts.sdk.modelcontextprotocol.io/v2/llms.txt
• TypeScript SDK (v1, nur bestehende v1-Projekte): Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.md

Sprachspezifische Implementierungsleitfäden (während Phase 2 laden)

• 🐍 Python Implementierungsleitfaden - Vollständiger Python/FastMCP-Leitfaden mit:

  • Serverinitialisierungsmustern
  • Pydantic-Modellbeispielen
  • Tool-Registrierung mit @mcp.tool
  • Vollständigen funktionierenden Beispielen
  • Qualitäts-Checkliste

• ⚡ TypeScript Implementierungsleitfaden (SDK v2) - Vollständiger TypeScript-Leitfaden für @modelcontextprotocol/server mit:

  • Projekteinrichtung und der Server Factory
  • Tool-Design: Zod 4-Schemata, Ausgabeformate, Paginierung, Fehler
  • Einem vollständigen Beispiel, das stdio und Streamable HTTP bedient, plus Bearer Auth
  • Ressourcen, Prompts und Benachrichtigungen
  • Einem Selbstprüfungsskript zur Überprüfung des gebauten Servers
  • Links zu SDK-Beispielen für erweiterte Funktionen
  • Einer v1 → v2-Übersetzungstabelle, Migrationsschritten und einer Qualitäts-Checkliste

• ⚡ TypeScript Implementierungsleitfaden (SDK v1) - Der entsprechende Leitfaden für bestehende @modelcontextprotocol/sdk-Projekte

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
  • Beispiel für Fragen und Antworten
  • Durchführen einer Evaluierung mit den bereitgestellten Skripten