使用说明

MCP-Tester

Referenz-Server cmd/test-server, geprüft mit task badge

mlcgo.eu — tools, libraries and manuals · Product page

Ein Command-Line Tool zum Testen, Debuggen und Validieren von Model Context Protocol (MCP) Servern nach der aktuellen Spezifikation vom 2026-07-28.

English Version

Warum MCP-Tester?

Fast täglich erscheinen neue Hosts, Harnesses und Modelle, und die MCP-Spezifikation entwickelt sich laufend weiter. Ein Server, der die Spezifikation nicht genau einhält, läuft dann oft „plötzlich“ nicht mehr sauber: Aufrufe scheitern bei strikteren Clients, Fehlermeldungen helfen dem Modell nicht weiter, oder das Modell verbrennt unnötig Tokens mit Wiederholungen. mcp-tester hilft, schnell und mit wenig Aufwand auf dem Stand der Technik zu bleiben.

Tests schreiben statt klicken

Klassische Unit-Tests (go test, pytest, npm test) rufen die Handler-Funktion direkt auf. Sie prüfen die Geschäftslogik, nicht den MCP-Protokollvertrag: Handshake, Schema-Validierung, Fehlercodes, strukturierte Ergebnisse, Fortschritt, Abbruch. Genau dort entstehen die Fehler, die erst auffallen, wenn ein echtes LLM das Tool aufruft.

Mit den deklarativen .mcp-Testskripten testet ihr den Server so, wie ein Client ihn sieht: als Blackbox über den echten Transport (stdio, SSE, Streamable HTTP), mit Variablen, Typumwandlung und Assertions, ohne Boilerplate und ohne SDK-Mocks. Die Skripte laufen als Gate in CI und Taskfile (Exit-Code, --format json).

call_tool generate_image prompt:"a red flower"
set_var size $.size
assert_equals $size "512x512"

expect_error call_tool generate_image prompt:""
assert_tool_error

Früh wissen, was die nächste Spec-Revision verlangt

mcp-tester wird regelmäßig an die neueste MCP-Spezifikation angepasst; was er zu welchem Datum prüft, steht in der Spec-Abdeckung. Wer seine Server damit testet, sieht notwendige Anpassungen, bevor Nutzer oder Hosts darüber stolpern, und erkennt auch veraltete Features, etwa eine alte Protokollversion, entfernte Methoden wie ping oder stillgelegte Fehlercodes.

Wir schreiben selbst viele MCP-Server für die unterschiedlichsten Anwendungen. Gerade dort spart mcp-tester wertvolle Zeit: Ein Lauf der Testskripte zeigt nach einem Spec- oder SDK-Update sofort, welche Server angepasst werden müssen und wo es klemmt.

Besonders bei neuen Features lohnt frühes Testen. Fehler in der Autorisierung (OAuth, Token, Header) sind nicht nur lästig, sondern können gefährlich und teuer werden. mcp-tester spielt den vollständigen OAuth-2.1-Ablauf durch und prüft mit http-check die Transportregeln von Streamable HTTP.

Fremde und Closed-Source-Server vor der Freigabe prüfen

Auch bei MCP-Servern, deren Quellcode ihr nicht kennt, ist eine Analyse sinnvoll, bevor ihr sie einem „echten“ LLM zur Verfügung stellt. inspect zeigt Protokollversion, Fähigkeiten, Tools mit Schemas und Annotations (z. B. ob ein Tool nur liest), Icons und Auffälligkeiten; http-check zeigt, wie sauber der Transport umgesetzt ist; skills --verify zeigt, welche Anweisungen (Skills) der Server dem Modell mitgibt, welche Tools sie vorab freigeben wollen (allowed-tools) und ob der Inhalt zu den veröffentlichten Digests passt.

Unser eigener, interner Harness zeigt genau solche Details an, bevor ein MCP-Server freigeschaltet wird. Für Anwender ist das eine sehr hilfreiche Entscheidungshilfe: verwenden, ja oder nein?

Findet auch Fehler im SDK

Weil mcp-tester den Server von außen gegen die Spezifikation prüft, findet er nicht nur Fehler im eigenen Code. Bei der Anpassung an Spec 2026-07-28 sind uns so auch Fehler und Lücken im verwendeten SDK aufgefallen, zum Beispiel ein Base64-kodierter Mcp-Name-Header, den das offizielle Go-SDK v1.8.0 fälschlich ablehnt.

Kern-Features

Echte Client-Perspektive über stdio, SSE und Streamable HTTP, mit Profilen in mcp-tester.yml.
Scripting Engine (.mcp): Tools, Tasks, Completion, Elicitation, Sampling, Roots und Notifications skriptbar, mit Assertions und Exit-Code für CI.
MCP Apps: interaktive Oberflächen eines Servers auflisten und prüfen (apps): Tool-Verknüpfung, ui://-Resources, externe Domains (CSP) und angeforderte Berechtigungen wie Kamera oder Mikrofon – wichtig vor der Freigabe.
Auth-Extensions: Client Credentials (Maschine-zu-Maschine) und Enterprise-Login per ID-JAG; auth-check zeigt, welche Flows ein Server anbietet.
Skills-Extension: Skills eines Servers auflisten und verifizieren (skills --verify): Manifest, Digests, Frontmatter, Namensregeln. Das Go-Paket pkg/mcpskills stellt Skills aus einem Verzeichnis bereit.
Tasks-Extension: lang laufende Tool-Aufrufe als Task starten, pollen, abbrechen, Eingaben nachreichen; tasks prüft einen Server gegen die Extension (Fehlercodes, Task-Form, Statusübergänge). Für Server-Autoren gibt es das Go-Paket pkg/mcptasks, das die Extension auf Servern mit dem offiziellen go-sdk nachrüstet.
Server Inspector (inspect): Spec-Abgleich, Best Practices und Quality Score; --min-score als CI-Gate, --badge für eine Status-Badge im README.
Markdown-Referenz (docs): Tools, Prompts, Resources und instructions als Markdown-Datei, gelesen über das Protokoll; --check lässt CI scheitern, wenn die Datei veraltet ist.
HTTP-Konformität (http-check): Pflicht-Header, Fehlercodes, Origin, Sessions nach Spec 2026-07-28.
Autorisierung: Bearer-Token, eigene Header und der OAuth-2.1-Ablauf (PKCE, Protected Resource Metadata, iss-Prüfung).
Strikte Ergebnisprüfung: Jedes Ergebnis wird gegen das outputSchema geprüft, so streng wie das offizielle TypeScript-SDK.
Aktuelle Spezifikation: Protokoll 2026-07-28 mit Rückfall auf ältere Revisionen; Abdeckung mit Datum dokumentiert.
Raw Mode für tiefgreifendes Debugging nicht konformer Server.

Schnellstart

Installieren – im Benutzerverzeichnis, ohne sudo:

curl -sSL https://raw.githubusercontent.com/hmsoft0815/mlc_mcptester/main/scripts/install.sh | bash   # nach ~/.local/bin
# oder: go install github.com/hmsoft0815/mlc_mcptester/cmd/mcp-tester@latest                       # nach ~/go/bin

Den eigenen Agents beibringen – installiert eine Skill-Datei für Claude Code, Gemini CLI, OpenCode und Codex, jeweils im Benutzerverzeichnis des Harness (--dry-run zeigt vorher, wohin):
```
mcp-tester agent-skill install
```
Nach einem Update des Testers erneut ausführen; der Skill passt immer zur installierten Version.

Ersten Server prüfen:

mcp-tester inspect -c "<Befehl, der euren MCP-Server startet>"

Weiterlesen: Kommandos, Test-Skripte, Status-Badge, Spec-Abdeckung.

Häufige Fragen

mcp-tester meldet Fehler – was tun? Unsere Empfehlung ist klar: gegen die aktuelle Spezifikation testen und die Meldungen ernst nehmen. Die Ausgabe nennt Methode, Feld, Fehlercode und die verletzte Regel. Moderne LLMs wie Claude oder Gemini machen daraus in der Regel schnell konkrete Vorschläge zur Behebung – gebt ihnen die Ausgabe (gern mit --format json) einfach mit.

Muss ich den Quality Score auf 100/100 bringen? Nein. Der Score beruht auf unseren eigenen Erfahrungen und Bewertungen; ein Wert unter 100 muss nicht automatisch eine Änderung am MCP-Server auslösen. Wir halten die Zahl trotzdem für eine sehr hilfreiche Information, deshalb gibt es sie. Wie der Score entsteht und was sich mit Version 1.8.0 an der Bewertung geändert hat, steht unter So entsteht der Score. Anders sind Protokollfehler (inspect) und FAIL (http-check): Das sind Verstöße gegen MUST-Regeln der Spezifikation, an denen echte Clients scheitern. Zeilen mit INFO gehen gar nicht in den Score ein: Sie beschreiben Entscheidungen, die legitim sein können, etwa ttlMs: 0 (Listen sofort veraltet) oder cacheScope: "public" bei einer Verbindung mit Zugangsdaten. Wer mit Anmeldung testet, sollte --read-resources ergänzen: Dann liest inspect die erste Resource und warnt, wenn nutzerbezogene Inhalte als public markiert sind und damit über gemeinsame Caches bei anderen Nutzern landen können.

Warum ist mcp-tester nicht selbst ein MCP-Server? Weil er vor allem in CI läuft, und dort zählen Exit-Code und --format json, nicht ein Tool-Aufruf. Agents mit Shell-Zugriff, etwa Claude Code, OpenCode oder Gemini CLI, rufen die CLI direkt auf. Wie das geht, erklärt ihnen die mitgelieferte Skill-Datei, die mcp-tester agent-skill install in das jeweilige Harness installiert: welcher Befehl wofür, wie man .mcp-Skripte schreibt und was in CI zu beachten ist. Meist wird ohnehin ein einzelner Server getestet, da bringt ein zusätzlicher Server keinen Vorteil. Hinzu kommt die Sicherheit: Ein Tool, das beliebige Prozesse startet und URLs aufruft, wäre ein großes Einfallstor, während die CLI nur mit den Rechten läuft, die ihr gebt. Für Hosts ohne Shell wäre ein Server-Modus dennoch nützlich; die Idee ist notiert, aber noch nicht geplant.

Der "Everything" Test-Server

Im Projekt ist ein Referenz-Server (cmd/test-server) enthalten, der die Möglichkeiten des MCP-Protokolls vorführt: Tools mit Output-Schemata, Resources und Templates, Prompts, Completion, Logging, Progress, Elicitation, Sampling, Roots, Notifications über subscriptions/listen, x-mcp-header, Elicitation im URL-Modus, Tool-Annotations, instructions, Cache-Hinweise und Paginierung (fünf Einträge pro Seite). task test-inspect verlangt für ihn 100/100. Mit -addr :8080 läuft er über HTTP, mit -auth zusätzlich OAuth-geschützt mit eingebautem Test-Autorisierungsserver.

Damit der Tester nicht nur gegen das go-sdk geprüft wird, gibt es einen zweiten, kleineren Referenz-Server auf Basis des TypeScript-SDK v2 (tests/interop/ts-server). Er ist eine unabhängige Umsetzung von 2026-07-28. task test-interop-ts-server verlangt für ihn über stdio und HTTP dieselben Ergebnisse wie für den Go-Server: 100/100 in inspect, kein FAIL in http-check, bestandenes Skript (braucht Node 20+).

Benutzung

1. Installation

Über Go (Direkt von GitHub):

go install github.com/hmsoft0815/mlc_mcptester/cmd/mcp-tester@latest

Hinweis: Stellt sicher, dass $GOPATH/bin (meist ~/go/bin) in eurem PATH liegt.

Erste Schritte: Nach der Installation könnt ihr euren ersten Server hinzufügen und sofort testen:

# Server-Profil hinzufügen
mcp-tester profile add my-server -c "npx -y @modelcontextprotocol/server-everything"

# Verfügbare Tools auflisten
mcp-tester list -p my-server

Über Curl (Linux/macOS) – installiert nach ~/.local/bin (anderes Ziel: INSTALL_DIR=…):

curl -sSL https://raw.githubusercontent.com/hmsoft0815/mlc_mcptester/main/scripts/install.sh | bash

Manueller Build:

git clone https://github.com/hmsoft0815/mlc_mcptester.git
cd mlc_mcptester
task all            # Baut den Tester und Referenz-Server in den bin/ Ordner

Ohne --recursive klonen. Das Repository verweist auf zwei Submodule (.mlcai, mlcprodweb), die auf einem internen Server liegen — interne Dokumentation und die Produktseite. Für den Bau werden sie nicht gebraucht; git clone --recursive bricht ohne Zugang zu diesem Server ab.

Echte Ausgabe: der Inspektor und ein Testlauf gegen den MCP-Server von mlc OpticScript.

2. Kommandos (Auszug)

Profilverwaltung

Verwaltet verschiedene Server-Konfigurationen direkt über die CLI:

mcp-tester profile add my-server -c "npx -y @modelcontextprotocol/server-everything"
mcp-tester profile list
mcp-tester profile disable my-server
mcp-tester profile delete my-server

Geschützte Server (Autorisierung)

Für HTTP-Transporte. Statische Zugangsdaten per Flag oder Profil, sonst der OAuth-2.1-Ablauf der Spec (PKCE, Protected Resource Metadata, iss-Prüfung; Client-Registrierung per Client ID Metadata Document, vorregistriertem Client oder dynamisch):

# Bearer-Token oder beliebige Header
mcp-tester list -u https://example.com/mcp --bearer "$TOKEN"
mcp-tester list -u https://example.com/mcp -H "X-Api-Key: $KEY"

# OAuth: URL wird ausgegeben (oder mit --oauth-browser geöffnet)
mcp-tester inspect -u https://example.com/mcp --oauth
mcp-tester inspect -u https://example.com/mcp --oauth --oauth-client-id my-client

# Ohne Browser, für Autorisierungsserver ohne Nutzerinteraktion (CI, test-server -auth)
mcp-tester inspect -u http://127.0.0.1:8080/mcp --oauth --oauth-auto

# Auth-Extensions: Maschine-zu-Maschine und Enterprise-Login (ID-Token → ID-JAG)
mcp-tester list -u https://example.com/mcp --oauth-client-credentials --oauth-client-id svc --oauth-client-secret "$SECRET"
mcp-tester list -u https://example.com/mcp --oauth-enterprise --idp-issuer https://idp.example --idp-client-id app \
  --id-token "$ID_TOKEN" --oauth-client-id app

# Welche Flows bietet der Server an, und stimmen die Metadaten?
mcp-tester auth-check -u https://example.com/mcp

Im Profil: headers: und bearer:, ${VAR} wird aus der Umgebung ersetzt. ./bin/test-server -addr :8080 -auth startet einen geschützten Test-Server mit eingebautem Autorisierungsserver (statische Tokens test-token und, als zweiter Nutzer, test-token-2).

HTTP-Konformität (`http-check`)

Prüft einen Streamable-HTTP-Endpunkt mit gezielt gebauten Requests gegen die Transportregeln von Spec 2026-07-28: Pflicht-Header (MCP-Protocol-Version, Mcp-Method, Mcp-Name, Base64-Werte, Mcp-Param-* aus x-mcp-header), Fehlercodes mit HTTP-Status (-32020, -32022, 404/-32601), Origin-Prüfung (403), 405 für GET/DELETE und keine Sessions. MUST-Verstöße: FAIL und Exit 1, SHOULD-Verstöße: WARN.

mcp-tester http-check -u https://example.com/mcp --bearer "$TOKEN"
mcp-tester http-check -u http://127.0.0.1:8080/mcp --format json

Server Inspektion

Analysiere einen Server auf Qualität (Metadaten, Prompts, Struktur):

# Mit Profil aus mcp-tester.yml
mcp-tester inspect --profile local

# Direktaufruf ohne Konfigurationsdatei
mcp-tester inspect -c "npx -y @modelcontextprotocol/server-everything"

# Als CI-Gate: Exit 1 bei Protokollfehlern oder Score unter der Schwelle
mcp-tester inspect -p local --min-score 90

# Tools, die bewusst nur Text (Markdown, Quelltext) liefern: kein Output-Schema erwartet
mcp-tester inspect -p local --text-only render_markdown,get_source

Tools ohne Output-Schema fasst inspect in einer HINT-Zeile zusammen (--hints-per-tool für eine Zeile je Tool). Liefert ein Tool bewusst nur Text, nimmt --text-only es aus der Prüfung: kein Hinweis, kein Punktabzug; eine INFO-Zeile und im JSON das Feld textOnlyTools nennen die ausgenommenen Tools. Im Profil steht dieselbe Liste unter text_only: [render_markdown, get_source].

So entsteht der Score

Jeder Server startet mit 100 Punkten. Davon gehen zwei Arten von Abzügen ab:

Qualitätsabzüge: fehlende Beschreibungen, Titel, Output-Schemas oder Prompts, Namensregeln, Icons, veraltete Protokoll-Revision und Ähnliches. Je Kategorie sind sie gedeckelt, damit ein Server mit vielen Tools für denselben Fehler nicht ohne Grenze bestraft wird.
Verstöße gegen MUST-Regeln der Spec: fehlgeschlagene */list-Aufrufe, inputSchema nicht vom Typ object, fehlende Cache-Felder, ungültige x-mcp-header, Verstöße gegen die Skills- oder die Tasks-Extension.

Für Tools mit readOnlyHint gibt es einen Bonus von bis zu 20 Punkten. Er gleicht nur Qualitätsabzüge aus. Danach wird auf 100 gekappt, und erst dann werden die MUST-Verstöße abgezogen.

Geänderte Bewertung ab Version 1.8.0

Bis einschließlich 1.7.0 wurde der Bonus vor der Kappung auf alle Abzüge angerechnet. Ein Server mit vielen readOnlyHint-Tools konnte so MUST-Verstöße vollständig verdecken und trotzdem 100/100 erreichen. Jetzt kostet jeder MUST-Verstoß sichtbar Punkte. Neu geprüft werden außerdem die Fehlercodes der Tasks-Extension, darunter -32021 für subscriptions/listen ohne Extension. Server, die auf dem go-sdk aufbauen und die Tasks-Extension erklären, verletzen diese Regel ohne Zusatz-Code und verlieren jetzt 10 Punkte. Abhilfe bietet pkg/mcptasks mit GuardListen bzw. GuardListenHandler.

Was ihr tun solltet: Lasst inspect einmal mit der neuen Version laufen. Sinkt der Score, nennt die Ausgabe die Ursache als WARNING. Wer --min-score als CI-Gate nutzt, sollte vor dem Update prüfen, ob die Schwelle noch erreicht wird. Gegebenenfalls die Ursache beheben oder die Schwelle vorübergehend senken. Badges mit Score ändern sich beim nächsten Lauf entsprechend.

Tasks-Extension prüfen (`tasks`)

inspect prüft bei Servern mit Tasks-Extension nur die Fehlercodes und ruft dabei kein Tool auf. Tiefer geht tasks:

# Fehlercodes von tasks/get, tasks/update, tasks/cancel und subscriptions/listen, ohne Tool-Aufruf
mcp-tester tasks -p local

# Einen Task vollständig verfolgen: Handle, dauerhafte Anlage, jede tasks/get-Antwort,
# Statusübergänge, Rückfragen und, falls angeboten, notifications/tasks
mcp-tester tasks -p local --tool long_job --args '{"seconds":2}' --elicit 'accept:{"name":"Ada"}'

# Abbruch direkt nach dem Start
mcp-tester tasks -p local --tool long_job --args '{"seconds":30}' --cancel

# Über HTTP mit Anmeldung: eine zweite Identität darf den Task nicht erreichen
mcp-tester tasks -u https://example.com/mcp --bearer "$TOKEN_A" --other-bearer "$TOKEN_B" --tool long_job

task test-interop-ts lässt außerdem den offiziellen TypeScript-Client der Extension (@modelcontextprotocol/ext-tasks) gegen unseren Referenzserver laufen, über stdio und Streamable HTTP (braucht Node 20+). Das prüft pkg/mcptasks und damit die Annahmen des Testers gegen eine unabhängige Umsetzung der Spec.

Mit --tool läuft das Tool zweimal, einmal ohne und einmal mit Extension. Wählt also eines, das ohne Schaden mehrfach laufen darf. MUST-Verstöße ergeben FAIL und Exit 1. Für Server-Autoren rüstet pkg/mcptasks die Extension auf go-sdk-Servern nach, einschließlich der Bindung von Tasks an die Identität, die sie angelegt hat.

Status-Badge für das eigene README

inspect schreibt auf Wunsch eine Badge, die andere Projekte in ihr README einbinden:

mcp-tester inspect -p local --badge docs/mcpcheck.svg --badge-json docs/mcpcheck.json

[![mcpcheck](docs/mcpcheck.svg)](docs/mcpcheck.json)

spec 2026-07-28: die Protokoll-Revision, die der Server ausgehandelt hat. Das ist bewusst nicht das Testdatum, denn die Revision zeigt, ob der Server auf dem aktuellen Stand ist.
100/100: der Quality Score von inspect. Mit --badge-no-score erscheint nur die Revision.
Farbe: grün; gelb bei Score unter 80 oder älterer Revision; rot („failing“) bei Protokollfehlern, unabhängig vom Score.
Testdatum und Tester-Version stehen im Tooltip der SVG und in der JSON-Datei. Verlinkt die Badge auf die JSON, dann ist nachvollziehbar, wann und womit geprüft wurde.
Die Badge wird auch bei fehlgeschlagener Prüfung geschrieben (rot), damit keine veraltete grüne Badge stehen bleibt. Die SVG ist eigenständig und braucht keinen externen Dienst. Die JSON folgt dem shields.io-Endpoint-Schema und funktioniert daher auch mit https://img.shields.io/endpoint?url=<Raw-URL der JSON>.

Markdown-Referenz (`docs`)

docs schreibt, was ein Client vom Server sieht, als Markdown-Datei: eine Übersicht der Tools (Titel, strukturiertes oder Text-Ergebnis, Annotations), je Tool die Beschreibung wörtlich, eine Parametertabelle aus dem inputSchema in der Reihenfolge des Servers (Typ, Pflicht, format, enum, Bereich, pattern, default) und die Ergebnisfelder aus dem outputSchema; dazu Prompts mit Argumenten, Resources, Resource-Templates und die instructions.

mcp-tester docs -p local -o docs/mcp-tools.md
# CI: Exit 1, wenn die Datei nicht mehr zum Server passt
mcp-tester docs -p local --check docs/mcp-tools.md

Gelesen wird das Protokoll, nicht der Quelltext; das funktioniert daher für jeden Server, unabhängig von Sprache und SDK. Die Datei ist immer englisch und enthält kein Datum und keine Version, --check schlägt also nur an, wenn sich Tools, Prompts oder Resources geändert haben. Parameter ohne Beschreibung werden auf stderr genannt; inspect meldet sie ebenfalls als Hinweis.

Tools, Resources & Prompts

mcp-tester list -p local
mcp-tester list -p local --format json   # alle Tools mit Schemas als JSON (ebenso resources list/templates, prompts list)
mcp-tester resources list --cursor "NEXT_TOKEN" -p local
mcp-tester prompts get code_review --args '{"file_path": "main.go"}' -p local
mcp-tester complete prompt:code_review file_path ma -p local

Test-Skripte (Automatisierung)

Führe komplexe Test-Szenarien aus:

./bin/mcp-tester test --script tests/03_variables_and_math.mcp --profile local

Dokumentation

Das MCP-Handbuch (Online) — Die umfassende Einführung und Referenz in das Model Context Protocol (Deutsch).
Scripting Referenz (DE) — Detaillierte Dokumentation der Test-Grammatik.
Scripting Reference (EN) — Detailed documentation of the test grammar.
Agent-Skill — Kompakte Anleitung für KI-Agents (Englisch); installieren mit mcp-tester agent-skill install.
Changelog — Änderungen je Version (Added/Changed/Fixed).
Spec-Abdeckung (DE) — Welche Features der aktuellen MCP-Spezifikation geprüft werden, mit Datum.

Lizenz

Dieses Projekt steht unter der MIT Lizenz.

Projektdokumentation (`.mlcai/`)

.mlcai/ ist ein privates Git-Submodul: interne Planung, Backlog und Arbeitsnotizen, gepflegt mit dem MLC Doc Hub. Es ist nicht öffentlich zugänglich — ohne --recurse-submodules klonen; für den Build wird es nicht gebraucht. Links nach .mlcai/ funktionieren nur mit Zugriff (git submodule update --init .mlcai).

Wer ist „Claude“ in den Commits?

Einige Commits in diesem Repository sind zusammen mit Claude entstanden, dem KI-Modell von Anthropic. Es schreibt Code mit, hält Dokumentation und Backlog aktuell und sucht Fehler in der Build-Pipeline – jede Änderung wird geprüft, bevor sie übernommen wird. Wir verstecken das nicht: wie wir mit Claude arbeiten.