{
  "markdown": "# zod-contract-mock-forge-mcp\n\n[![npm version](https://img.shields.io/npm/v/zod-contract-mock-forge-mcp.svg)](https://www.npmjs.com/package/zod-contract-mock-forge-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/zod-contract-mock-forge-mcp.svg)](https://www.npmjs.com/package/zod-contract-mock-forge-mcp)\n[![CI](https://github.com/vola-trebla/zod-contract-mock-forge-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vola-trebla/zod-contract-mock-forge-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn 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.\n\n## The Problem\n\nZod 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.\n\n## Tools\n\n### Mock generation\n\n| Tool                     | Arguments                        | What it returns                                                           |\n| ------------------------ | -------------------------------- | ------------------------------------------------------------------------- |\n| `generate_valid_mock`    | `schema_code`, `count?`          | Valid mock data matching the schema                                       |\n| `generate_mock_variants` | `schema_code`, `count?`, `seed?` | N structurally valid but value-diverse mocks — for property-based testing |\n\n### Violation generation\n\n| Tool                                   | Arguments     | What it returns                                                                                |\n| -------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |\n| `generate_boundary_violations`         | `schema_code` | Invalid payloads for each constraint: missing fields, type mismatches, min/max, email/uuid/url |\n| `generate_exhaustive_union_violations` | `schema_code` | Per-variant violations for every branch of a `z.union()` or `z.discriminatedUnion()`           |\n\n### Schema analysis\n\n| Tool                        | Arguments                                                                          | What it returns                                                                                             |\n| --------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `introspect_schema`         | `schema_code`                                                                      | JSON Schema representation — for LLM understanding of the contract                                          |\n| `read_schema_from_file`     | `file_path`, `export_name?`                                                        | Extracts the Zod schema expression from a TypeScript/JS file                                                |\n| `detect_schema_drift`       | `zod_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` |\n| `evaluate_schema_evolution` | `schema_file_path`, `schema_export_name`, `old_schema_content?`                    | Generates mocks from old schema, validates against new — detects breaking changes before tests run          |\n\n### Contract testing\n\n| Tool                         | Arguments                                                                  | What it returns                                                            |\n| ---------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| `scaffold_api_contract_test` | `framework`, `base_url`, `endpoint`, `method`, `schema_code`, `test_name?` | Contract test boilerplate for Playwright, Jest, Vitest, or MSW             |\n| `suggest_contract_fix`       | `schema_code`, `payload`                                                   | Validates a JSON payload and explains each violation with a fix suggestion |\n\n## Setup\n\n### 1. Install\n\n```bash\nnpm install -g zod-contract-mock-forge-mcp\n```\n\n### 2. Add to your editor\n\n#### Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"zod-forge\": {\n      \"command\": \"zod-contract-mock-forge-mcp\"\n    }\n  }\n}\n```\n\n#### Claude Code\n\n```bash\nclaude mcp add zod-forge zod-contract-mock-forge-mcp\n```\n\n## Example usage\n\n```\nMy schema file is src/schemas/user.ts, exported as UserSchema.\nMy OpenAPI spec is docs/openapi.yaml.\n\n1. introspect_schema — what are the constraints on this schema?\n2. generate_mock_variants — give me 10 diverse valid payloads (seed: 42) for CI reproducibility\n3. generate_exhaustive_union_violations — test every branch of the role discriminated union\n4. detect_schema_drift — has the Zod schema diverged from the OpenAPI docs?\n5. evaluate_schema_evolution — does my schema change break any existing mock data?\n```\n\n## Example output\n\n**`generate_mock_variants`** — 3 diverse valid mocks, seeded for CI:\n\n```json\n{\n  \"schema_id\": \"schema_a1b2c3d4\",\n  \"count\": 3,\n  \"all_valid\": true,\n  \"variants\": [\n    { \"name\": \"Colleen Rowe\", \"age\": 37 },\n    { \"name\": \"Pat Reynolds\", \"age\": 24 },\n    { \"name\": \"Veronica Konopelski\", \"age\": 45 }\n  ]\n}\n```\n\n**`detect_schema_drift`** — field missing in OpenAPI, extra field in Zod:\n\n```json\n{\n  \"drift_count\": 2,\n  \"drifts\": [\n    {\n      \"field_path\": \"role\",\n      \"drift_type\": \"missing_in_openapi\",\n      \"zod_value\": \"string\",\n      \"openapi_value\": null\n    },\n    {\n      \"field_path\": \"email\",\n      \"drift_type\": \"missing_in_zod\",\n      \"zod_value\": null,\n      \"openapi_value\": \"string\"\n    }\n  ]\n}\n```\n\n**`evaluate_schema_evolution`** — new required field breaks existing mocks:\n\n```json\n{\n  \"breaking_change\": true,\n  \"sample_count\": 20,\n  \"invalid_mock_count\": 20,\n  \"failure_reasons\": [\n    {\n      \"field_path\": \"status\",\n      \"zod_code\": \"invalid_type\",\n      \"expected\": \"string\",\n      \"received\": \"undefined\",\n      \"affected_mock_count\": 20\n    }\n  ]\n}\n```\n\n## Scripts\n\n```bash\nnpm run build        # compile TypeScript → dist/\nnpm run lint         # ESLint\nnpm run format       # Prettier --write\nnpm run format:check # Prettier check (used in CI)\nnpm test             # Vitest\n```\n\n## License\n\nMIT\n",
  "bytes": 6733,
  "sha": "bf4e4c1928ec7adf732049d174ce510291c2f0923362f2f6f7d50a1e6f0ef5a3",
  "repo_slug": "vola-trebla/zod-contract-mock-forge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vola_trebla_zod_contract_mock__ca381750/readme"
}