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 分