Das MCP-Handbuch

Kapitel 14: Qualitätssicherung – Der Server-Inspector & das Quality-Scoring

Einen einfachen MCP-Server zu schreiben ist schnell erledigt. Einen robusten, spezifikationskonformen und KI-optimierten MCP-Server zu bauen, ist jedoch eine echte Ingenieursaufgabe. In diesem Kapitel lernen wir, wie wir mit dem Open-Source-Werkzeug mcp-tester die Qualität unserer Server-Implementierung objektiv messen, Spezifikationsänderungen frühzeitig erkennen und systematisch optimieren.

1. Warum ist Qualität bei MCP so erfolgskritisch?

Ein Large Language Model besitzt keinen menschlichen gesunden Menschenverstand: Es verlässt sich zu 100 % auf die Metadaten und Schemata, die der MCP-Server beim Handshake und Aufruf bereitstellt. Unvollständige oder veraltete Server-Antworten führen direkt zu Fehlverhalten:

  • Fehlende Tool-Beschreibungen: Das Modell kann nicht entscheiden, welches Werkzeug für eine Aufgabe das richtige ist, und beginnt zu raten oder zu halluzinieren.
  • Fehlende Output-Schemata: Wenn ein Tool unstrukturierten Text statt validiertem JSON liefert (siehe Kapitel 9), muss das Modell die Rohdaten selbst parsen – was Rechenzeit kostet und fehleranfällig ist.
  • Fehlende Prompts & Richtlinien: Das Modell kennt keine Anwendungsregeln oder Systemkontexte für die Werkzeuge (siehe Kapitel 6).

2. Der `mcp-tester`: Das Diagnosewerkzeug für Entwickler

Um diese Lücke zu schließen, haben wir den mcp-tester entwickelt. Er agiert als spezialisierter, protokollstrenger MCP-Client, der Ihren Server auf Herz und Nieren prüft:

MCP Server Quality Inspector & Scoring

3. Die entscheidenden Vorteile des `mcp-tester`

Warum reicht es nicht aus, den Server einfach mit Claude Desktop oder Cursor auszuprobieren? Der mcp-tester bietet entscheidende architektonische Vorteile:

A. Frühzeitige Erkennung von Spezifikationsänderungen (Spec Drift Detection)

Das Model Context Protocol entwickelt sich dynamisch weiter:

  • Neue Transport-Standards (Streamable HTTP statt reiner SSE-Endpunkte),
  • Neue Spezifikationserweiterungen (z. B. Tasks nach SEP-2663 oder Skills over MCP nach SEP-2640),
  • Strengere Anforderungen an Handshake-Capabilities und Metadaten (wie Icons oder Annotation-Hints).

Wenn sich die offizielle Spezifikation weiterentwickelt oder Ihr SDK im Hintergrund veraltet, verhält sich ein Standard-LLM-Client oft unvorhersehbar: Er schlägt plötzlich stillschweigend fehl oder ignoriert Werkzeuge. Der mcp-tester validiert das Drahtprotokoll direkt gegen die Spezifikation. Veraltete JSON-RPC-Strukturen, fehlerhafte Header oder ungültige Schemata werden sofort als Warnung oder Fehler markiert – lange bevor Ihre Nutzer im echten Chat darauf stoßen.

B. Das Punktesystem (Quality Score 0–100) als Optimierungs-Roadmap

Ein einfaches „Pass/Fail“ hilft Entwicklern kaum weiter. Ein Server kann formal lauffähig sein und dennoch für KIs ungeeignet sein. Der inspect-Befehl des Testers vergibt daher einen Quality Score von 0 bis 100 Punkten und liefert eine klare, priorisierte To-Do-Liste:

./bin/mcp-tester inspect --profile my-server

Das Bewertungsschema im Detail:

  1. Fehlende Prompts (-20 Punkte):
    Ein professioneller Server sollte mindestens einen System-Prompt bereitstellen, der dem LLM erklärt, wie die angebotenen Werkzeuge sinnvoll orchestriert werden.
  2. Fehlende Tool-Beschreibungen (-5 Punkte pro Tool):
    Jedes Werkzeug ohne aussagekräftige Erklärung wird rigoros abgestraft, da es die Hauptursache für Modell-Fehlentscheidungen ist.
  3. Fehlende Output-Schemata (-2 Punkte pro Tool):
    Strukturierte JSON-Rückgabewerte erleichtern dem Modell die Weiterverarbeitung enorm.
  4. Visuelle Metadaten (Icons):
    Prüfung, ob referenzierte Icon-URIs valide und erreichbar sind.

Erreicht Ihr Server beispielsweise 73/100 Punkte, listet der Inspector exakt auf:

„-20 Pkt: Keine Prompts registriert; -5 Pkt: Tool 'export_db' besitzt keine Beschreibung; -2 Pkt: Tool 'query' liefert kein structured output schema.“
Damit erhalten Sie sofort konkrete Hebel zur Optimierung.

C. Black-Box-Integrationstest vs. Unit-Test

Ein Go- oder Python-Unit-Test prüft lediglich die interne Funktion (z. B. handleAdd(1, 2) == 3).
Der mcp-tester prüft hingegen das tatsächliche Systemverhalten von außen:

  • Funktioniert der Handshake über Stdio-Pipes oder Streamable HTTP?
  • Werden JSON-Typen korrekt serialisiert?
  • Werden Timeouts und Cancellation-Signale sauber verarbeitet?

4. Validierung visueller Metadaten (Icons)

Seit den Spezifikationsrevisionen für Rich-Clients können Tools, Ressourcen und Prompts mit Icons ausgestattet werden. Der Tester bietet spezialisierte Flags, um sicherzustellen, dass keine fehlerhaften URLs ausgeliefert werden:

# Prüft Erreichbarkeit aller Icon-URIs im Server
./bin/mcp-tester list --check-icons --profile my-server

# Lädt alle Icons in einen lokalen Ordner herunter (zur manuellen Sichtprüfung)
./bin/mcp-tester list --download-icons "./icons_export" --profile my-server

5. Checkliste für den „Perfekten Server“ (100/100 Score)

Um im mcp-tester inspect die volle Punktzahl zu erreichen, sollte Ihre Implementierung folgende Kriterien erfüllen:

  • Handshake & Version: Der Server meldet eine aktuelle Protokoll-Version und verhandelt Capabilities sauber aus.
  • Tool-Beschreibungen: Jedes Werkzeug enthält eine präzise Erklärung mit Einsatzszenarien und Trigger-Begriffen.
  • Vollständige Typisierung: Input-Argumente und Output-Daten sind über standardkonforme JSON-Schemata typisiert.
  • Prompts hinterlegt: Mindestens ein Prompt definiert den Systemkontext oder standardisierte Workflows für das Modell.
  • Icon-Integrität: Alle deklarierten Icon-Links sind erreichbar und valide formatiert.

6. Die perfekte Kombination: Unit-Tests & MCP-Tester

In der Praxis empfiehlt sich eine zweistufige Teststrategie:

┌────────────────────────────────────────────────────────┐
│                      Unit-Tests                        │
│   Prüft interne Fachlogik & Edge Cases in Millisek.    │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│                   mcp-tester inspect                   │
│   Prüft Protokoll-Konformität, Schemata & Score        │
└───────────────────────────┬────────────────────────────┘
                            │
                            ▼
┌────────────────────────────────────────────────────────┐
│              mcp-tester test (CI/CD Skripte)           │
│   Automatische Regressionstests vor jedem Deployment   │
└────────────────────────────────────────────────────────┘

Beispiel: Unit-Test für einen Go-Tool-Handler

func TestHandleAdd(t *testing.T) {
    ctx := context.Background()
    args := map[string]any{"a": 10.0, "b": 20.0}

    result, structured, err := handleAdd(ctx, nil, args)
    if err != nil {
        t.Fatalf("Unerwarteter Fehler: %v", err)
    }

    if structured.(map[string]any)["sum"] != 30.0 {
        t.Errorf("Unerwartetes Ergebnis: %v", structured)
    }
}

Faustregel: Nutzen Sie Unit-Tests für die interne Rechenlogik und den mcp-tester für die Protokoll-Konformität, Schemavalidierung und Interaktionsqualität.

Fazit

Qualitätssicherung bei MCP bedeutet, Reibungsverluste zwischen Server und KI systematisch zu eliminieren. Durch den Einsatz des mcp-tester (github.com/hmsoft0815/mlc_mcptester) erkennen Sie Protokoll-Abweichungen frühzeitig und erhalten über den Quality Score eine glasklare Anleitung, um Ihren Server auf das Niveau führender Produktionssysteme zu heben.

← Kapitel 13: Das Artifact-Pattern | Inhaltsverzeichnis | Nächstes Kapitel: Automatisierung & CI/CD →

Copyright Michael Lechner – 2026-09-27 (Aktualisiert für MCP Quality Scoring, Spec Drift Detection & GitHub Open Source)

Lizenz: CC BY-NC 4.0