Skip to main content
Glama

mcpstub

本物のコントラクトから生成されるフェイクMCPサーバーです。

mcpstub は、mcpdoctor のレポートまたは小さなJSONフィクスチャを、決定的なstdioサーバーに変換します。実際の認証情報、不安定なAPI、手書きのJSON-RPC配線を必要とせずに、MCPクライアント、ゲートウェイ、エージェントハーネスをテストできます。

mcpstub がコントラクトを決定的なモダン/レガシーテストサーバーに変換する

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

Node.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…

    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