mcpstub
mcpstub
本物のコントラクトから生成されるフェイクMCPサーバーです。
mcpstub は、mcpdoctor のレポートまたは小さなJSONフィクスチャを、決定的なstdioサーバーに変換します。実際の認証情報、不安定なAPI、手書きのJSON-RPC配線を必要とせずに、MCPクライアント、ゲートウェイ、エージェントハーネスをテストできます。
$ 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有用なループ
実サーバーを一度調査し、コントラクトを確認してから、ローカルスタブに対してテストします:
# 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生成されたフィクスチャには、ツール名、説明、スキーマ、アノテーション、リソース、テンプレート、プロンプト、サーバー識別情報が保持されます。プレースホルダーの結果─本番ツールの出力ではありません─を生成します。
Related MCP server: Fake Pennylane MCP Server
手書きシナリオ
フィクスチャは、普通にレビューできるJSONです。ツールに引数固有のケースを直接追加できます:
{
"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 は、引数オブジェクトに対して再帰的な部分集合マッチングを行います。オブジェクトのケースは無関係な引数を無視でき、配列は長さと位置でマッチします。最初にマッチしたケースが優先され、次に result がフォールバックになります。どちらもない場合、mcpstub はツール名と引数を含む決定的な生成結果を返します。
メンテナンス済みのサンプルもお試しください:
npx --yes github:jovial-liu/mcpstub#v1 check examples/weather.json
npx --yes github:jovial-liu/mcpstub#v1 serve examples/weather.json実装内容
モダン
2026-07-28のserver/discover、結果ディスクリミネーター、キャッシュメタデータ;レガシー
initializeのネゴシエーション(デフォルトは2025-11-25);tools/listと決定的なtools/call結果、またはJSON-RPCエラー;リソースとリソーステンプレートの一覧、および
resources/read;プロンプトの一覧、および
prompts/get;ping、未知メソッドエラー、パースエラー;スタブに対して行われた呼び出しの、オプションのJSONL記録。
どちらのプロトコル時代も同じフィクスチャプロセスから利用できます。モダンクライアントは server/discover から始まり、レガシークライアントは initialize から始まります。
オプションの呼び出し検証
テスト対象システムがスタブに何を要求したかを記録します:
mcpstub serve fixture.json --log calls.jsonlログにはタイムスタンプ、ツール名、引数が含まれます。引数にはシークレットやプライベートデータが含まれることがあるため、オプトイン方式です。レビューとサニタイズを行うまでは、呼び出しログをソース管理に入れないでください。
CLI
mcpstub from <mcpdoctor.json> [--out mcpstub.json]
mcpstub check <fixture.json> [--json]
mcpstub serve <fixture.json> [--log calls.jsonl]
mcpstub --versionフィクスチャ形式は schema/fixture.schema.json によりバージョン管理されます。check は重複名や不正なケースも、安定したフィンディングコード付きで拒否します。
安全性と制限
mcpstub は、実際のMCPサーバーを起動せず、実際のツールを呼び出さず、シェルを実行せず、環境変数の認証情報を読み込まず、ネットワークリクエストも行いません。指定したフィクスチャだけを読み込み、明示された出力先もしくはログパスにのみ書き込みます。
プロトコル用のフィクスチャであり、セキュリティサンドボックスでも完全なサーバーエミュレーターでもありません:
stdio はサポートされますが、Streamable HTTP と認可はサポートされません;
マルチラウンドトリップのリクエスト、サブスクリプション、サンプリング、エリシテーション、拡張はシミュレーションされません;
広告されたJSONスキーマは呼び出し引数の検証には使われません;
生成されたフィクスチャには、ビヘイビアの記録ではなくコントラクトとプレースホルダー応答が含まれます;
悪意のあるフィクスチャは、テスト対象のクライアントに悪意のあるテキストを返す可能性があります。そのため、第三者のフィクスチャはコードと同様のテストデータとしてレビューしてください。
録画された本番セッションが必要な場合は、カセット型レコーダーを使用してください。mcpstub は意図的にコントラクト駆動です。小さなフィクスチャ、明示的なケース、決定的な結果。
開発
git clone https://github.com/jovial-liu/mcpstub.git
cd mcpstub
npm run checkNode.js 20+、ランタイム依存ゼロです。CONTRIBUTING.md と SECURITY.md をご覧ください。
ライセンス
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