JsonFabrica

@jsonfabrica/mcp-server

AI コーディングエージェント（Claude Desktop、Cursor、その他 MCP に対応するあらゆるクライアント）が、JsonFabrica の REST API を MCP ツールとして呼び出すことで、セッション中にスキーマに準拠したリアルな JSON テストデータを生成できる、ローカルの Model Context Protocol（MCP）サーバーです。

stdio トランスポートのみで動作します。AI クライアントがサブプロセスとして起動するため、ホストするネットワークサービスも、開放するポートもありません。設定した JsonFabrica ゲートウェイ以外とは通信しません。

JsonFabrica を初めてお使いですか？ 再利用可能なテンプレートから合成 JSON テストデータを生成する、API ファーストのサービスです。決定論的で、シードから再現可能であり、関連レコード間の参照整合性も保たれます。jsonfabrica.com と API ドキュメントをご覧ください。

インストール／実行

クライアントが npx 経由で起動するよう、MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "jsonfabrica": {
      "command": "npx",
      "args": ["-y", "@jsonfabrica/mcp-server"],
      "env": {
        "JSONFABRICA_API_KEY": "sk_live_...",
        "JSONFABRICA_API_URL": "https://api.jsonfabrica.com"
      }
    }
  }
}

• Claude Desktop — 上記のブロックを claude_desktop_config.json に追加し（Settings → Developer → Edit Config）、再起動します。
• Cursor — Settings → MCP → Add new MCP server を選択するか、ブロックを ~/.cursor/mcp.json に追加します。

jsonfabrica.com に登録し、Settings → API Keys から API キーを取得します。

または、ローカルテスト用に直接実行します。

npm install
npm run build
JSONFABRICA_API_KEY=sk_live_... node dist/index.js

セッションでの使用例

接続すると、エージェントは次のような操作ができます。

あなた： リアルな顧客レコードを 20 件、その顧客に紐付いた注文を 60 件生成して、fixtures/seed.json に保存してください。

エージェント： 顧客と注文の形状に対して jsonfabrica_create_template を呼び出し、各注文が生成された顧客 ID を参照するよう relations マップを指定して jsonfabrica_create_batch を呼び出し、結果をファイルに書き込みます。

ダッシュボードへの画面切り替えも、フィクスチャの手書きも不要です。

設定

環境変数	必須	デフォルト	備考
JSONFABRICA_API_KEY	はい	—	未設定でもサーバーは起動し、ツールの一覧を返しますが、すべてのツール呼び出しは「check JSONFABRICA_API_KEY」というエラーで失敗します。ログに記録されたり、ツールの出力に含まれたりすることはありません。
JSONFABRICA_API_URL	いいえ	https://api.jsonfabrica.com	JsonFabrica ゲートウェイのベース URL です。ゲートウェイをセルフホストする場合などに上書きしてください（例：http://localhost:4000）。

ツール

各ツールの説明には、呼び出す REST エンドポイントがそのまま記載されています。クライアントが読み込んでいる他の MCP サーバーとの名前の衝突を避けるため、ツール名には jsonfabrica_ という接頭辞が付いています。

ヘルスチェック／認証

ツール	エンドポイント	備考
jsonfabrica_health	GET /health	認証不要です。接続を確認します。
jsonfabrica_whoami	GET /v1/whoami	設定されたキーに対応する { tenantId, role } を返します。

テンプレート

ツール	エンドポイント
jsonfabrica_create_template	POST /v1/templates
jsonfabrica_list_templates	GET /v1/templates
jsonfabrica_get_template	GET /v1/templates/{templateId}
jsonfabrica_update_template	PUT /v1/templates/{templateId}
jsonfabrica_delete_template	DELETE /v1/templates/{templateId}
jsonfabrica_generate_from_template	POST /v1/templates/{templateId}/generate
jsonfabrica_generate_adhoc	POST /v1/templates/generate（永続化なし。永続化する生成と同じ料金が適用されます）

テンプレートの body 文字列では、山括弧を使った JsonFabrica の関数呼び出しプレースホルダー構文を使用します。例：<getRandomFullName()>、<getRandomEmail()>、<createSeq('orderNo')>。組み込み関数の全カタログは jsonfabrica.com/docs/functions に記載されています。これは記述用のリファレンスであり、このサーバーがツールとして公開するものではありません。

シーケンス

ツール	エンドポイント
jsonfabrica_create_sequence	POST /v1/sequences
jsonfabrica_list_sequences	GET /v1/sequences
jsonfabrica_get_sequence	GET /v1/sequences/{name}
jsonfabrica_update_sequence	PATCH /v1/sequences/{name}
jsonfabrica_delete_sequence	DELETE /v1/sequences/{name}
jsonfabrica_bump_sequence	POST /v1/sequences/{name}/bump

バッチ

ツール	エンドポイント
jsonfabrica_create_batch	POST /v1/batches（小規模なバッチは同期実行され、200 と results を返します。大規模なバッチはキューに登録され、202 を返します。jsonfabrica_get_batch でポーリングしてください）
jsonfabrica_get_batch	GET /v1/batches/{batchId}

どちらのツールも同じ形式を返します：{ batchId, status, seed, results?, error? }。 status は queued | running | completed | failed です。バッチが completed になると results が含まれ、生成されたドキュメントがエイリアスごとにグループ化されます。各値はドキュメント自体の配列です。

{
  "batchId": "4f1c…",
  "status": "completed",
  "seed": 42,
  "results": {
    "customer": [{ "id": "c-1", "name": "Ada Lovelace" }],
    "order": [{ "id": "o-1", "customerId": "c-1" }, { "id": "o-2", "customerId": "c-1" }]
  }
}

失敗したバッチでは、results の代わりに error: { code, message } が含まれます。合計50件未満のドキュメントを含むバッチ（API のデフォルトしきい値）は同期実行されます。これより大きなバッチは 202 { batchId, status: "queued", seed } を返します。

使用状況

ツール	エンドポイント
jsonfabrica_get_usage	GET /v1/usage — { tenantId, usageTotal, asOf } を返します

明示的に対象外

• POST /v1/signup と PATCH /v1/billing/tier — 認証なしで利用できる、アカウント作成／請求プラン変更用のエンドポイントです。これらをラップすると、モデルがユーザーに代わって実際の有料サブスクリプションを作成したり、請求プランを変更したりできるため、設計上対象外としています（生成 API のみを対象とします）。
• POST /v1/webhooks/stripe — Stripe 専用の Webhook 取り込み機能であり、開発者向けの機能ではありません。

エラー処理

各ツールはエラーを内部で捕捉し、読みやすいメッセージを含む MCP isError: true の結果を返します。ハンドラーから例外をスローしたり、ホストプロセスをクラッシュさせたりすることはありません。よくあるケースは次のとおりです。

• 401 → 「API キーが無効か、指定されていません。JSONFABRICA_API_KEY を確認してください。」
• 403 → API キーのテナントには、その呼び出しを実行する権限がありません。
• 402（アカウントがブロックされている場合）→ 上流の blockReason をそのまま渡します。
• ネットワーク障害（ゲートウェイに到達できない場合）→ 設定された JSONFABRICA_API_URL を示すメッセージを返します。
• その他の場合 → JsonFabrica API error [CODE] (HTTP status): message。

トラブルシューティング

• 401 / 「API キーが無効か、指定されていません」 → JSONFABRICA_API_KEY が設定され、有効であることを確認してください。
• 接続拒否 / UPSTREAM_UNREACHABLE → JSONFABRICA_API_URL と、ゲートウェイが実際に起動しており、このプロセスの実行環境から到達できることを確認してください。
• 403 / FORBIDDEN → API キーのテナントには、その呼び出しを実行する権限がありません。

開発

npm install
npm run build   # tsc -p tsconfig.json
npm test        # build + node --test dist/
npm start       # node dist/index.js (requires JSONFABRICA_API_KEY)

ソースの構成は OpenAPI 仕様のタグに対応しており、src/tools/ の下にタグごとに1つのファイルがあります。fetch、ベース URL、Authorization ヘッダーを扱うのは src/client.ts のみです。

ライセンス

MIT — LICENSE を参照してください。