mlc_mcptester

MCP-Tester

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?

Klassische Unit-Tests (go test, pytest, npm test) rufen üblicherweise nur die interne Handler-Funktion direkt auf. Sie testen die Geschäftslogik, nicht aber den MCP-Protokollvertrag:

• Stimmt die JSON-RPC-Kommunikation und das Handshake-Verhalten?
• Werden Parameter anhand des JSON-Schemas vom Transport und Validator korrekt durchgereicht?
• Werden standardisierte Fehler-Codes (wie -32602 bei ungültigen Argumenten) eingehalten?
• Funktionieren Progress-Benachrichtigungen, Ping und Cancellation über den echten Transport?

Eine Diskrepanz zwischen deklariertem Schema und tatsächlichem Handler-Verhalten bleibt in reinen Code-Tests unsichtbar – und bricht erst zur Laufzeit, wenn ein echtes LLM oder ein Host-Client das Tool aufruft.

mcp-tester schließt diese Lücke:

• Echte Client-Perspektive: Testet Server als Blackbox über reale Transports (stdio, sse, streamable-http).
• Deklarative .mcp-Testskripte: Schnelle, lesbare Tests mit Variablen, Typumwandlung und Assertions – ohne Test-Boilerplate oder SDK-Mocks.
• Spec- & Quality-Validierung: inspect prüft auf Einhaltung der offiziellen Spezifikation und Best Practices (Quality Score).
• CI/CD-Integration: Ideal als abschließender test:integration-Schritt in Pipelines und Taskfiles.

Kern-Features

• Multi-Transport: Unterstützt lokale Prozesse (stdio), Remote-Server (sse) sowie Streamable HTTP (streamable-http/http).
• Full Spec Support: Testet Tools, Resources (statisch & Templates), Subscriptions sowie Prompts nach neuester Spezifikation.
• Pagination Support: Unterstützt das Durchblättern langer Listen (list) mittels Cursor.
• Scripting Engine: Automatisierte Test-Abläufe mit Variablen, Typ-Konvertierung und Assertions.
• Server Inspector: Analysiert Server auf Best Practices und gibt einen Quality-Score aus.
• Raw Mode: Umgeht SDK-Validierungen für tiefgreifendes Debugging.
• Profile: Einfache Verwaltung verschiedener Server in einer mcp-tester.yml.

Der "Everything" Test-Server

Im Projekt ist ein Referenz-Server (cmd/test-server) enthalten, der alle Möglichkeiten des MCP-Protokolls ausschöpft (Tools, Resources, Prompts, Logging, Progress, Output-Schemata).

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 tools list -p my-server

Über Curl (Linux/macOS):

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

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"

Tools, Resources & Prompts

mcp-tester tools list -p local
mcp-tester resources list --cursor "NEXT_TOKEN" -p local
mcp-tester prompts get code_review --args '{"file_path": "main.go"}' -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.

Lizenz

Dieses Projekt steht unter der MIT Lizenz.

Copyright Michael Lechner - 2026-03-09