zod-contract-mock-forge-mcp

zod-contract-mock-forge-mcp

一个 MCP 服务，可将 Zod 模式转换为模拟数据、违规数据和契约测试，让你的 AI Agent 无需手动构造负载，也能分析 API 契约。

问题

Zod 模式是运行时代码。没有这一层，AI Agent 无法执行这些模式、检查其约束，也无法生成有效或无效的负载。Agent 也无法发现模式与 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 表示——供大模型理解契约
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 — 生成 3 个多样且有效的模拟数据，用于 CI 的随机种子：

{
  "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