Zod Contract Mock Forge Mcp

io.github.vola-treblaPublished by GitHub account vola-treblav0.2.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyDeveloper ToolsData & Analytics

Overview

AI-generated overview

Local MCP server that turns Zod schemas into valid mocks, boundary violations, drift reports and contract test scaffolding for an AI assistant.

What you can do
  • Generate valid mock data and seeded, value-diverse mock variants from Zod schema code
  • Produce invalid payloads for each constraint and per-branch violations for unions and discriminated unions
  • Introspect schemas into JSON Schema and extract schema expressions from TypeScript/JS files
  • Diff a Zod schema against an OpenAPI spec and flag breaking changes in schema evolution
  • Scaffold contract tests for Playwright, Jest, Vitest or MSW and explain payload violations with fix suggestions
When to use it
Useful when an assistant works on TypeScript APIs with Zod schemas and needs payloads, negative test cases, OpenAPI drift checks or contract test boilerplate without writing them by hand.
Requirements
Runs as a local stdio process installed from the npm package zod-contract-mock-forge-mcp (Node.js); registered in an editor such as Cursor, VS Code or Claude Code. No authentication, environment variables or headers are declared. Desktop only.
Before you install
Tools read schema and OpenAPI files from paths you supply and return their contents as JSON Schema or extracted code, so point them only at files you are willing to share with the assistant. Generated tests and mocks are scaffolding to review before use.

Installation

In SourceWeft

  1. Open Zod Contract Mock Forge Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 87e8f46

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts