mcp-tester

Instrumentierter MCP-Server zum Testen der Client-Konformität mit */list_changed-Benachrichtigungen und anderen Protokollfunktionen.

Warum

PR mcaps-microsoft/msx-mcp#321 schlug eine dynamische Bereitstellung von Tools über notifications/tools/list_changed vor. Der PR wurde mit der Behauptung geschlossen, dass "Copilot CLI tools/list beim Sitzungsstart zwischenspeichert und notifications/tools/list_changed ignoriert" – aber es wurde nie ein instrumentiertes Experiment durchgeführt, um dies zu beweisen oder zu widerlegen.

Dieses Repository stellt den Apparat bereit, um diese Behauptung – und die Konformität jedes MCP-Clients mit list_changed – mit echten Beweisen zu testen.

Was es tut

1. Probe MCP Server (src/server.ts) – Ein selbstinstrumentierender MCP-Server, der jede JSON-RPC-Nachricht auf seiner stdio-Pipe protokolliert. Er stellt Alpha-Status-Tools, -Ressourcen und -Prompts bereit, sowie Trigger-Tools, die diese auf den Beta-Status umstellen und die entsprechende */list_changed-Benachrichtigung senden.

2. Automatisierter Client-Treiber (src/driver.ts) – Ein SDK-basierter MCP-Client, der den Server durch den vollständigen Mutationszyklus steuert. Dies ist die Kontrolle: Er beweist, dass das Protokoll funktioniert, wenn beide Endpunkte die Spezifikation einhalten. Jeder Client, der von diesem Verhalten abweicht, ist nachweislich nicht konform.

3. Log-Analysator (src/analyze.ts) – Liest das JSONL-Log und gibt eine Markdown-Beweistabelle aus, die spezifische Fragen beantwortet: Hat der Client die Benachrichtigung erhalten? Hat er neu geladen? Kann er das neue Element aufrufen? Kann er das entfernte Element noch aufrufen?

4. Human Protocol (PROTOCOL.md) – Schritt-für-Schritt-Anleitungen zum Ausführen desselben Tests gegen Copilot CLI oder jeden anderen MCP-Client.

Schnellstart

git clone https://github.com/ericchansen/mcp-tester.git
cd mcp-tester
npm install
npm run build

Ausführen der automatisierten Kontrolle (SDK-Client)

npm run driver -- --domain all

Dies startet den Probe-Server, führt das vollständige Mutationsprotokoll für Tools, Ressourcen und Prompts aus und meldet die Ergebnisse. Sie sollten sehen, dass alle drei Domänen mit voller Konformität bestehen.

Analysieren eines Logs

npm run analyze -- path/to/log.jsonl --domain tools

Testen Ihres eigenen MCP-Clients

Siehe PROTOCOL.md für Schritt-für-Schritt-Anleitungen zum Testen von Copilot CLI oder jedem anderen MCP-Client gegen diese Probe.

Repository-Struktur

mcp-tester/
|-- README.md          # This file
|-- PROTOCOL.md        # Human-driven test procedure
|-- LICENSE            # MIT
|-- package.json
|-- tsconfig.json
|-- src/
|   |-- server.ts      # Probe MCP server (stdio)
|   |-- logger.ts      # JSONL stdio tap + log writer
|   |-- analyze.ts     # CLI: parses log -> markdown evidence table
|   +-- driver.ts      # CLI: spawns server, drives it via SDK Client
+-- results/
    +-- copilot-cli/
        +-- .gitkeep   # Committed experiment results go here

Wie die Probe funktioniert

Ausgangszustand (Alpha)

Plus fünf permanente Tools: mcptester_mutate_tools, mcptester_mutate_resources, mcptester_mutate_prompts, mcptester_status.

Nach der Mutation (Beta)

Wenn ein mcptester_mutate_*-Tool aufgerufen wird:

1. Das Alpha-Element wird entfernt (über SDK handle.remove())

2. Das Beta-Element wird registriert

3. Das SDK sendet automatisch die entsprechende notifications/*/list_changed

4. debouncedNotificationMethods fasst Entfernen + Registrieren zu einer einzigen Benachrichtigung zusammen

Protokollierung

Jede JSON-RPC-Nachricht (eingehend und ausgehend) wird in einer JSONL-Datei protokolliert. Der Logger greift über Transform-Streams, die vor dem SDK-Transport installiert sind, auf process.stdin und process.stdout zu, sodass er jedes Byte sieht, ohne das Protokoll zu stören.

Einschränkungen

• Nur stdio-Transport – noch kein HTTP/SSE-Test

• Nur drei list_changed-Abläufe – zukünftige Tests für Sampling, Elicitation, Roots, Progress, Completions geplant

• Einzelserver-Test – testet jeweils eine MCP-Server-Verbindung

Lizenz

MIT