zod-contract-mock-forge-mcp

zod-contract-mock-forge-mcp

Un servidor MCP que convierte esquemas Zod en mocks, violaciones y pruebas de contrato — para que tu agente de IA pueda razonar sobre contratos de API sin crear payloads manualmente.

El Problema

Los esquemas Zod son código en tiempo de ejecución. Un agente de IA no puede ejecutarlos, inspeccionar sus restricciones, ni generar payloads válidos o inválidos sin esta capa. El agente tampoco puede detectar cuándo el esquema y la documentación OpenAPI divergen silenciosamente, o si un cambio en el esquema rompe fixtures de prueba existentes.

Herramientas

Generación de mocks

Herramienta	Argumentos	Qué devuelve
generate_valid_mock	schema_code, count?	Datos mock válidos que coinciden con el esquema
generate_mock_variants	schema_code, count?, seed?	N mocks estructuralmente válidos pero con valores diversos — para pruebas basadas en propiedades

Generación de violaciones

Herramienta	Argumentos	Qué devuelve
generate_boundary_violations	schema_code	Payloads inválidos para cada restricción: campos faltantes, errores de tipo, min/max, email/uuid/url
generate_exhaustive_union_violations	schema_code	Violaciones por variante para cada rama de un z.union() o z.discriminatedUnion()

Análisis de esquemas

Herramienta	Argumentos	Qué devuelve
introspect_schema	schema_code	Representación JSON Schema — para que el LLM entienda el contrato
read_schema_from_file	file_path, export_name?	Extrae la expresión del esquema Zod de un archivo TypeScript/JS
detect_schema_drift	zod_file_path, schema_export_name, openapi_file_path, openapi_schema_name?	Compara Zod vs OpenAPI — reporta missing_in_openapi, missing_in_zod, type_conflict, required_mismatch
evaluate_schema_evolution	schema_file_path, schema_export_name, old_schema_content?	Genera mocks desde el esquema antiguo, valida contra el nuevo — detecta cambios que rompen antes de ejecutar pruebas

Pruebas de contrato

Herramienta	Argumentos	Qué devuelve
scaffold_api_contract_test	framework, base_url, endpoint, method, schema_code, test_name?	Plantilla de prueba de contrato para Playwright, Jest, Vitest o MSW
suggest_contract_fix	schema_code, payload	Valida un payload JSON y explica cada violación con una sugerencia de corrección

Configuración

1. Instalación

npm install -g zod-contract-mock-forge-mcp

2. Añadir a tu editor

Cursor / VS Code (.cursor/mcp.json o .vscode/mcp.json)

{
  "mcpServers": {
    "zod-forge": {
      "command": "zod-contract-mock-forge-mcp"
    }
  }
}

Claude Code

claude mcp add zod-forge zod-contract-mock-forge-mcp

Ejemplo de uso

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?

Ejemplo de salida

generate_mock_variants — 3 mocks válidos diversos, con semilla para 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 — campo faltante en OpenAPI, campo extra en 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 — nuevo campo obligatorio rompe mocks existentes:

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

Licencia

MIT