Labsco
vola-trebla logo

zod-contract-mock-forge-mcp

from vola-trebla

Generates deterministic mocks and boundary violations from Zod schemas

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#scraping

zod-contract-mock-forge-mcp

npm downloads

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

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