mcpstub
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 disconnectsDer 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.jsonDas 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.jsonWas es implementiert
modernes
2026-07-28server/discover, Ergebnis-Diskriminatoren und Cache-Metadaten;Legacy-
initialize-Aushandlung, standardmäßig2025-11-25;tools/listund deterministischetools/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.jsonlDas 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 --versionDas 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 checkNode.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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Minimal streamable HTTP MCP server used for owned-account registry connectivity tests.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA lightweight mock MCP server for local testing and resilience experiments, providing predictable tool responses with simulated latency and errors.1MIT
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseNot gradedqualityCmaintenanceSpin up deterministic mock MCP servers from JSON fixture files for testing MCP clients and agents.MIT
- AlicenseNot gradedqualityBmaintenanceProvides 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