zod-contract-mock-forge-mcp

zod-contract-mock-forge-mcp

Zod スキーマをモック、違反データ、コントラクトテストに変換する MCP サーバーです。AI エージェントがペイロードを手作業で作成せずに、API コントラクトを推論できるようにします。

問題

Zod スキーマは実行時コードです。このレイヤーがなければ、AI エージェントはスキーマを実行したり、制約を調べたり、有効／無効なペイロードを生成したりできません。また、スキーマと OpenAPI ドキュメントの間で気づかないうちに差異が生じていないか、スキーマの変更によって既存のテストフィクスチャが壊れないかも検出できません。

ツール

モックの生成

ツール	引数	戻り値
generate_valid_mock	schema_code、count?	スキーマに適合する有効なモックデータ
generate_mock_variants	schema_code、count?、seed?	構造的に有効でありながら値に多様性のある N 個のモック — プロパティベーステスト向け

違反データの生成

ツール	引数	戻り値
generate_boundary_violations	schema_code	各制約に対する無効なペイロード：フィールドの欠落、型の不一致、最小値／最大値、メールアドレス／uuid／url
generate_exhaustive_union_violations	schema_code	z.union() または z.discriminatedUnion() のすべての分岐について、各バリアントの違反データ

スキーマ分析

ツール	引数	戻り値
introspect_schema	schema_code	JSON Schema 表現 — LLM によるコントラクトの理解向け
read_schema_from_file	file_path、export_name?	TypeScript／JS ファイルから Zod スキーマ式を抽出します
detect_schema_drift	zod_file_path、schema_export_name、openapi_file_path、openapi_schema_name?	Zod と OpenAPI の差分を報告します — missing_in_openapi、missing_in_zod、type_conflict、required_mismatch
evaluate_schema_evolution	schema_file_path、schema_export_name、old_schema_content?	古いスキーマからモックを生成し、新しいスキーマに対して検証します — テスト実行前に破壊的変更を検出します

コントラクトテスト

ツール	引数	戻り値
scaffold_api_contract_test	framework、base_url、endpoint、method、schema_code、test_name?	Playwright、Jest、Vitest、または MSW 用のコントラクトテストのひな形
suggest_contract_fix	schema_code、payload	JSON ペイロードを検証し、各違反の内容と修正案を説明します

セットアップ

1. インストール

npm install -g zod-contract-mock-forge-mcp

2. エディターに追加

Cursor / VS Code（.cursor/mcp.json または .vscode/mcp.json）

{
  "mcpServers": {
    "zod-forge": {
      "command": "zod-contract-mock-forge-mcp"
    }
  }
}

Claude Code

claude mcp add zod-forge zod-contract-mock-forge-mcp

使用例

My schema file is src/schemas/user.ts, exported as UserSchema.
My OpenAPI spec is docs/openapi.yaml.

1. introspect_schema — what are the constraints on this schema?
2. generate_mock_variants — give me 10 diverse valid payloads (seed: 42) for CI reproducibility
3. generate_exhaustive_union_violations — test every branch of the role discriminated union
4. detect_schema_drift — has the Zod schema diverged from the OpenAPI docs?
5. evaluate_schema_evolution — does my schema change break any existing mock data?

出力例

generate_mock_variants — CI 用にシードされた、多様で有効なモック 3 件：

{
  "schema_id": "schema_a1b2c3d4",
  "count": 3,
  "all_valid": true,
  "variants": [
    { "name": "Colleen Rowe", "age": 37 },
    { "name": "Pat Reynolds", "age": 24 },
    { "name": "Veronica Konopelski", "age": 45 }
  ]
}

detect_schema_drift — OpenAPI にフィールドがなく、Zod に余分なフィールドがある場合：

{
  "drift_count": 2,
  "drifts": [
    {
      "field_path": "role",
      "drift_type": "missing_in_openapi",
      "zod_value": "string",
      "openapi_value": null
    },
    {
      "field_path": "email",
      "drift_type": "missing_in_zod",
      "zod_value": null,
      "openapi_value": "string"
    }
  ]
}

evaluate_schema_evolution — 新しい必須フィールドが既存のモックに影響する場合：

{
  "breaking_change": true,
  "sample_count": 20,
  "invalid_mock_count": 20,
  "failure_reasons": [
    {
      "field_path": "status",
      "zod_code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "affected_mock_count": 20
    }
  ]
}

スクリプト

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)
npm test             # Vitest

ライセンス

MIT