Zod Contract Mock Forge Mcp

io.github.vola-trebla由 GitHub 帳號 vola-trebla 發布v0.2.0更新於 Oct 24, 2026

MCP server for deterministic mock generation and API contract scaffolding using Zod schemas

已驗證STDIO僅桌面開發者工具資料與分析

概覽

AI 產生的概覽

本機 MCP 伺服器，把 Zod schema 轉成有效 mock 資料、邊界違規案例、漂移報告與契約測試骨架，供 AI 助理使用。

可以做什麼
  • 依 Zod schema 程式碼產生有效 mock 資料，以及可設定種子的多樣化 mock 變體
  • 為每項限制產生無效載荷，並為 union 與 discriminated union 的每個分支產生違規案例
  • 將 schema 內省為 JSON Schema，並從 TypeScript/JS 檔案擷取 schema 運算式
  • 比對 Zod schema 與 OpenAPI 規格，並評估 schema 變更是否造成破壞性影響
  • 為 Playwright、Jest、Vitest 或 MSW 產生契約測試骨架，並說明載荷違規原因與修正建議
適用情境
適合助理處理使用 Zod schema 的 TypeScript API 時使用，需要產生請求載荷、負向測試案例、檢查 OpenAPI 漂移或產生契約測試樣板程式碼。
執行需求
以本機 stdio 程序執行，需透過 npm 安裝 zod-contract-mock-forge-mcp（Node.js），並在 Cursor、VS Code 或 Claude Code 等編輯器中註冊。未宣告任何驗證、環境變數或標頭。僅支援桌面端。
安裝前請注意
相關工具會讀取你提供的 schema 與 OpenAPI 檔案路徑，並以 JSON Schema 或擷取出的程式碼形式回傳內容，因此只應指向願意交給助理的檔案。產生的測試與 mock 屬於骨架程式碼，使用前需人工檢查。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Zod Contract Mock Forge Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

zod-contract-mock-forge-mcp

[npm version] [npm downloads] [CI] [License: MIT]

An MCP server that turns Zod schemas into mocks, violations, and contract tests — so your AI agent can reason about API contracts without manually crafting payloads.

The Problem

Zod schemas are runtime code. An AI agent cannot execute them, introspect their constraints, or generate valid/invalid payloads without this layer. The agent also cannot detect when the schema and the OpenAPI docs silently diverged, or whether a schema change breaks existing test fixtures.

Tools

Mock generation

ToolArgumentsWhat it returns
generate_valid_mockschema_code, count?Valid mock data matching the schema
generate_mock_variantsschema_code, count?, seed?N structurally valid but value-diverse mocks — for property-based testing

Violation generation

ToolArgumentsWhat it returns
generate_boundary_violationsschema_codeInvalid payloads for each constraint: missing fields, type mismatches, min/max, email/uuid/url
generate_exhaustive_union_violationsschema_codePer-variant violations for every branch of a z.union() or z.discriminatedUnion()

Schema analysis

ToolArgumentsWhat it returns
introspect_schemaschema_codeJSON Schema representation — for LLM understanding of the contract
read_schema_from_filefile_path, export_name?Extracts the Zod schema expression from a TypeScript/JS file
detect_schema_driftzod_file_path, schema_export_name, openapi_file_path, openapi_schema_name?Diffs Zod vs OpenAPI — reports missing_in_openapi, missing_in_zod, type_conflict, required_mismatch
evaluate_schema_evolutionschema_file_path, schema_export_name, old_schema_content?Generates mocks from old schema, validates against new — detects breaking changes before tests run

Contract testing

ToolArgumentsWhat it returns
scaffold_api_contract_testframework, base_url, endpoint, method, schema_code, test_name?Contract test boilerplate for Playwright, Jest, Vitest, or MSW
suggest_contract_fixschema_code, payloadValidates a JSON payload and explains each violation with a fix suggestion

Setup

1. Install

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

2. Add to your editor

Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)
json
{  "mcpServers": {    "zod-forge": {      "command": "zod-contract-mock-forge-mcp"    }  }}
Claude Code
bash
claude mcp add zod-forge zod-contract-mock-forge-mcp

Example usage

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 reproducibility3. generate_exhaustive_union_violations — test every branch of the role discriminated union4. 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?

Example output

generate_mock_variants — 3 diverse valid mocks, seeded for CI:

json
{  "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 — field missing in OpenAPI, extra field in Zod:

json
{  "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 — new required field breaks existing mocks:

json
{  "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    }  ]}

Scripts

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

License

MIT

來源：README.md，提交 87e8f46

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v0.2.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分