mcpstub

Ein simulierter MCP-Server, der aus dem echten Vertrag generiert wird.

mcpstub verwandelt einen mcpdoctor-Report oder ein kleines JSON-Fixture in einen deterministischen Stdio-Server. Teste MCP-Clients, Gateways und Agenten-Harness ohne Live-Zugangsdaten, unzuverlässige APIs oder handgeschriebene JSON-RPC-Verkabelung.

$ mcpstub from mcpdoctor.json --out fixtures/docs.json
mcpstub: wrote fixtures/docs.json (14 tools)

$ mcpstub check fixtures/docs.json
✓ valid mcpstub fixture: fixtures/docs.json

$ mcpstub serve fixtures/docs.json
# speaks MCP on stdin/stdout until the client disconnects

Der nützliche Kreislauf

Untersuche einen echten Server einmal, prüfe den Vertrag und teste dann gegen den lokalen Stub:

# 1. Inventory the server. mcpdoctor never calls its tools.
npx --yes github:jovial-liu/mcpdoctor#v1 inspect \
  --format json --out mcpdoctor.json -- \
  npx -y @modelcontextprotocol/server-filesystem /tmp

# 2. Generate a safe starting fixture from the advertised contract.
npx --yes github:jovial-liu/mcpstub#v1 from mcpdoctor.json --out fixtures/files.json

# 3. Point an MCP client at the deterministic fixture server.
npx --yes github:jovial-liu/mcpstub#v1 serve fixtures/files.json

Das generierte Fixture bewahrt Toolnamen, Beschreibungen, Schemas, Annotationen, Ressourcen, Templates, Prompts und die Serveridentität. Es erzeugt Platzhalterergebnisse – niemals aufgezeichnete Produktions-Tool-Ausgaben.

Handgeschriebene Szenarien

Fixtures sind normales, überprüfbares JSON. Füge argumentspezifische Fälle direkt zu einem Tool hinzu:

{
  "schema": "mcpstub/v1",
  "server": { "name": "weather-fixture", "version": "1.0.0" },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get a fixture forecast",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "cases": [
        {
          "when": { "city": "Paris" },
          "result": { "content": [{ "type": "text", "text": "Paris: 21°C, clear" }] }
        },
        {
          "when": { "city": "Atlantis" },
          "error": { "code": -32004, "message": "Fixture city not found" }
        }
      ],
      "result": { "content": [{ "type": "text", "text": "Fixture forecast unavailable" }] }
    }
  ]
}

when führt einen rekursiven Teilmengen-Abgleich auf Argumentobjekten durch. Objektfälle können irrelevante Argumente ignorieren; Arrays werden nach Länge und Position abgeglichen. Der erste passende Fall gewinnt; ohne fallend einen passt, dient result als Fallback. Ohne beides liefert mcpstub ein deterministisches, generiertes Ergebnis, das den Toolnamen und die Argumente enthält.

Probiere das gepflegte Beispiel aus:

npx --yes github:jovial-liu/mcpstub#v1 check examples/weather.json
npx --yes github:jovial-liu/mcpstub#v1 serve examples/weather.json

Was es implementiert

• modernes 2026-07-28 server/discover, Ergebnis-Diskriminatoren und Cache-Metadaten;

• Legacy-initialize-Aushandlung, standardmäßig 2025-11-25;

• tools/list und deterministische tools/call-Ergebnisse oder JSON-RPC-Fehler;

• Auflistung von Ressourcen und Ressourcen-Templates sowie resources/read;

• Auflistung von Prompts sowie prompts/get;

• ping, unbekannte-Methode-Fehler und Parse-Fehler;

• optionale JSONL-Aufzeichnung der an den Stub gerichteten Aufrufe.

Beide Protokoll-Epochen stehen in demselben Fixture-Prozess zur Verfügung. Ein moderner Client startet mit server/discover; ein Legacy-Client startet mit initialize.

Optionale Aufruf-Überprüfungen

Dokumentiere, was das zu testende System den Stub tun ließ:

mcpstub serve fixture.json --log calls.jsonl

Das Log enthält Zeitstempel, Toolnamen und Argumente. Es ist opt-in, weil Argumente Geheimnisse oder private Daten enthalten können. Halte Aufrufprotokolle aus der Versionsverwaltung heraus, es sei denn, sie wurden geprüft und bereinigt.

CLI

mcpstub from <mcpdoctor.json> [--out mcpstub.json]
mcpstub check <fixture.json> [--json]
mcpstub serve <fixture.json> [--log calls.jsonl]
mcpstub --version

Das Fixture-Format wird über schema/fixture.schema.json versioniert. check Lehnt außerdem doppelte Namen und fehlerhaftige Fälle mit stabilen Befund-Codes ab.

Sicherheit und Grenzen

mcpstub startet keinen echten MCP-Server, ruft keine echten Tools auf, führt keine Shell aus, lädt keine Umgebungsanmeldedaten und tätigt keine Netzwerkanfragen. Es liest nur die von dir bezeichneten Fixtures und schreibt nur in einen explizit angegebenen Ausgabe- oder Log-Pfad.

Es ist eine Protokoll-Fixture, keine Sicherheits-Sandbox und kein vollständiger Server-Emulator:

• stdio wird unterstützt; Streamable HTTP und Autorisierung nicht unterstützt;

• Multi-Roundtrips-Anfragen, Subscriptions, Sampling, Elicitation und Erweiterungen werden nicht simuliert;

• Die angekündigten JSON-Schemas werden nicht zur Validierung von Aufrufargumenten verwendet;

• generierten Fixtures enthalten Verträge und Platzhalterantworten, keine Verhaltensaufzeichnungen;

• Ein bösartiges Fixture kann weiterhin bösartigen Text an die zu testende Client zurückgeben, also: Behandle Drittanbieter-Fixtures wie codeähnliche Testdaten.

Für aufgezeichnete Live-Sitzungen verwende einen kassettenbasierten Rekorder. mcpstub ist bewusst vertragsgetrieben: kleine Fixtures, explizite Fälle, deterministische Ergebnisse.

Entwicklung

git clone https://github.com/jovial-liu/mcpstub.git
cd mcpstub
npm run check

Node.js 20+ und keine Laufzeitabhängigkeiten. Siehe CONTRIBUTING.md und SECURITY.md.

Lizenz

MIT