English Français العربية

io.github.vola-trebla/zod-contract-mock-forge-mcp

السجل الرسمي أخرى

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

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package zod-contract-mock-forge-mcp
Claude Code 
claude mcp add zod-contract-mock-forge-mcp -- npx -y zod-contract-mock-forge-mcp@0.2.0
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "zod-contract-mock-forge-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "zod-contract-mock-forge-mcp@0.2.0"
            ]
        }
    }
}

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. zod-contract-mock-forge-mcp
  2. The Problem
  3. Tools
  4. Setup
  5. Example usage
  6. Example output
  7. Scripts
  8. License

zod-contract-mock-forge-mcp

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
npm install -g zod-contract-mock-forge-mcp
2. Add to your editor
Cursor / VS Code (.cursor/mcp.json or .vscode/mcp.json)
{
  "mcpServers": {
    "zod-forge": {
      "command": "zod-contract-mock-forge-mcp"
    }
  }
}
Claude Code
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 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?

Example output

generate_mock_variants — 3 diverse valid mocks, seeded for 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 — field missing in OpenAPI, extra field in 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 — new required field breaks existing mocks:

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

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

License

MIT

الأسئلة الشائعة

ما هو io.github.vola-trebla/zod-contract-mock-forge-mcp؟

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

كيف أثبّت io.github.vola-trebla/zod-contract-mock-forge-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add zod-contract-mock-forge-mcp -- npx -y zod-contract-mock-forge-mcp@0.2.0. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.vola-trebla/zod-contract-mock-forge-mcp إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.vola-trebla/zod-contract-mock-forge-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.vola-trebla/zod-contract-mock-forge-mcp؟

ينشره vola-trebla. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.