Das Schnittstellen-Gerüst

Beschreibung

Beispiel-Szenario

Ein Entwicklerteam möchte sein internes Ticketsystem für ein Sprachmodell zugänglich machen, damit es offene Tickets lesen, kommentieren und weiterleiten kann. Ausgehend von der vorhandenen REST-API entsteht mit dem Schnittstellen-Gerüst ein TypeScript-basierter MCP-Server: sprechende Tool-Namen wie tickets_list und tickets_add_comment, typisierte Ein- und Ausgaben, eine Fehlerbehandlung mit konkreten Hinweisen und zehn Testfragen, die zeigen, dass ein Modell offene Tickets zuverlässig findet und bearbeitet.

# ROLLE
Sie erstellen MCP-Server (Model Context Protocol), die es Sprachmodellen ermöglichen, über gut gestaltete Tools mit externen Diensten zu interagieren. Die Qualität eines MCP-Servers bemisst sich daran, wie zuverlässig er einem Modell hilft, reale Aufgaben zu lösen.

# PHASE 1: RECHERCHE UND PLANUNG

## Modernes MCP-Design verstehen
Wägen Sie umfassende API-Abdeckung gegen spezialisierte Workflow-Tools ab. Workflow-Tools sind bei einzelnen Aufgaben komfortabler, umfassende Abdeckung gibt Agenten mehr Freiheit, Operationen selbst zu kombinieren. Im Zweifel priorisieren Sie umfassende API-Abdeckung.

Vergeben Sie klare, sprechende Tool-Namen mit konsistenten Präfixen (zum Beispiel github_create_issue, github_list_repos) und handlungsorientierter Benennung.

Halten Sie Tool-Beschreibungen knapp und ermöglichen Sie Filter und Paginierung, damit Agenten fokussierte, relevante Daten erhalten.

Formulieren Sie Fehlermeldungen so, dass sie den Agenten mit konkreten Vorschlägen zu einer Lösung führen.

## MCP-Spezifikation und Framework-Dokumentation studieren
Nutzen Sie die Sitemap unter https://modelcontextprotocol.io/sitemap.xml, um relevante Seiten zu finden, und rufen Sie einzelne Seiten mit der Endung .md im Markdown-Format ab. Prüfen Sie insbesondere die Architekturübersicht, die Transportmechanismen (Streamable HTTP, stdio) sowie Tool-, Resource- und Prompt-Definitionen.

Empfohlener Stack: TypeScript für Server (gute SDK-Unterstützung, breite Kompatibilität, Modelle generieren zuverlässigen TypeScript-Code), Streamable HTTP mit zustandslosem JSON für Remote-Server, stdio für lokale Server.

Laden Sie die SDK-Dokumentation der gewählten Sprache (TypeScript oder Python) sowie die zugehörigen sprachspezifischen Implementierungsguides, bevor Sie zu implementieren beginnen.

## Implementierung planen
Verstehen Sie die Ziel-API: zentrale Endpunkte, Authentifizierung, Datenmodelle. Priorisieren Sie umfassende API-Abdeckung und listen Sie zunächst die häufigsten Operationen.

# PHASE 2: IMPLEMENTIERUNG

## Projektstruktur aufsetzen
Richten Sie die Projektstruktur nach dem sprachspezifischen Guide ein (Package- beziehungsweise Modulstruktur, Abhängigkeiten, Konfigurationsdateien).

## Kerninfrastruktur
Erstellen Sie gemeinsame Bausteine: einen API-Client mit Authentifizierung, Fehlerbehandlung, Antwortformatierung (JSON oder Markdown) und Paginierungsunterstützung.

## Tools implementieren
Für jedes Tool gilt:
- Input-Schema mit Zod (TypeScript) oder Pydantic (Python), mit Einschränkungen, klaren Beschreibungen und Beispielen.
- Output-Schema, wo möglich, für strukturierte Daten.
- Eine knappe Funktionsbeschreibung mit Parametern und Rückgabetyp.
- Asynchrone Verarbeitung für I/O-Operationen, saubere Fehlerbehandlung mit konkreten Hinweisen, Paginierung wo anwendbar.
- Annotationen: readOnlyHint, destructiveHint, idempotentHint, openWorldHint.

# PHASE 3: REVIEW UND TEST
Prüfen Sie den Code auf Duplikate, konsistente Fehlerbehandlung, vollständige Typisierung und klare Tool-Beschreibungen.

TypeScript: Build mit npm run build verifizieren, mit dem MCP Inspector testen (npx @modelcontextprotocol/inspector).
Python: Syntax mit python -m py_compile prüfen, ebenfalls mit dem MCP Inspector testen.

# PHASE 4: EVALUATIONEN ERSTELLEN
Erstellen Sie zehn Evaluationsfragen, um zu prüfen, ob ein Sprachmodell den Server produktiv nutzen kann.

Vorgehen: Tools sichten, mit Nur-Lese-Operationen die verfügbaren Daten explorieren, zehn komplexe, realistische Fragen formulieren, jede Frage selbst lösen und die Antwort verifizieren.

Jede Frage muss unabhängig von anderen Fragen beantwortbar sein, ausschließlich Nur-Lese-Operationen benötigen, mehrere Tool-Aufrufe und echte Exploration erfordern, auf einem realen Anwendungsfall beruhen, eine einzige, per Textvergleich verifizierbare Antwort haben, und zeitstabil sein.

Format als XML-Datei:
```xml
<evaluation>
  <qa_pair>
    <question>...</question>
    <answer>...</answer>
  </qa_pair>
</evaluation>
```

# REFERENZDATEIEN DES ORIGINALS
Das Original bündelt vertiefende Dateien, die eine vollständige Umgebung zusätzlich benötigt: eine Best-Practice-Referenz zu Namenskonventionen, Antwortformaten, Paginierung, Transportwahl, Sicherheit und Fehlerbehandlung; einen TypeScript-Implementierungsguide; einen Python-Implementierungsguide; und einen Evaluationsguide mit Fragenformat und Beispielen.

# DEFINITION OF DONE
[ ] MCP-Spezifikation und SDK-Dokumentation der gewählten Sprache konsultiert
[ ] Tool-Namen konsistent und handlungsorientiert
[ ] Input- und, wo möglich, Output-Schema für jedes Tool definiert
[ ] Fehlerbehandlung durchgängig und mit konkreten Hinweisen
[ ] Annotationen (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) gesetzt
[ ] Build beziehungsweise Syntaxprüfung erfolgreich, Test mit dem MCP Inspector durchgeführt
[ ] Zehn verifizierte, realistische Evaluationsfragen als XML dokumentiert

# ABHÄNGIGKEITEN
Terminal- und Dateizugriff, Zugriff auf die MCP-Spezifikation und die SDK-Dokumentation (TypeScript oder Python), den MCP Inspector für Tests.

Umsetzung

1. 1

   Zieldienst auswählen

   Der Einstieg gelingt am besten mit einem Dienst, der bereits eine dokumentierte API hat und im Team kurzfristig gebraucht wird.

2. 2

   Sprache und Transport festlegen

   TypeScript mit Streamable HTTP ist der empfohlene Standardweg für Remote-Server, stdio bleibt lokalen Servern vorbehalten.

3. 3

   Skill in einer agentischen Umgebung einsetzen

   Der Skill-Text wird in eine Umgebung mit Terminal-, Datei- und Webzugriff geladen, etwa Claude Code.

4. 4

   Server testen und abnehmen lassen

   Vor dem produktiven Einsatz wird der Server über den MCP Inspector geprüft und von einer zweiten Person durchgesehen.

5. 5

   Muster für weitere Dienste wiederverwenden

   Bewährte Namenskonventionen und Fehlerbehandlung werden beim nächsten MCP-Server erneut eingesetzt.