Skip to main content
Glama

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 turns a contract into a deterministic modern or legacy test server

$ 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.

Related MCP server: Fake Pennylane MCP Server

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight mock MCP server for local testing and resilience experiments, providing predictable tool responses with simulated latency and errors.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A fake MCP server that emulates the Pennylane MCP experience for local development, testing, demos, and CI pipelines, providing deterministic fixtures and authentication modes without needing a real Pennylane account.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides a central gateway to 170+ offline mock MCP servers with deterministic fixture-based responses and per-server SQLite state, enabling realistic credential-free agent trajectory testing and multi-step workflow rehearsal.
      MIT