zod-contract-mock-forge-mcp

zod-contract-mock-forge-mcp

Um servidor MCP que transforma esquemas Zod em mocks, violações e testes de contrato — para que seu agente de IA possa raciocinar sobre contratos de API sem precisar criar payloads manualmente.

O Problema

Esquemas Zod são código em tempo de execução. Um agente de IA não consegue executá-los, inspecionar suas restrições ou gerar payloads válidos/inválidos sem esta camada. O agente também não consegue detectar quando o esquema e a documentação OpenAPI divergiram silenciosamente, ou se uma alteração no esquema quebra fixtures de teste existentes.

Ferramentas

Geração de mocks

Ferramenta	Argumentos	O que retorna
generate_valid_mock	schema_code, count?	Dados mock válidos que correspondem ao esquema
generate_mock_variants	schema_code, count?, seed?	N mocks estruturalmente válidos, mas com valores diversos — para testes baseados em propriedades

Geração de violações

Ferramenta	Argumentos	O que retorna
generate_boundary_violations	schema_code	Payloads inválidos para cada restrição: campos ausentes, incompatibilidades de tipo, min/max, email/uuid/url
generate_exhaustive_union_violations	schema_code	Violações por variante para cada ramo de um z.union() ou z.discriminatedUnion()

Análise de esquema

Ferramenta	Argumentos	O que retorna
introspect_schema	schema_code	Representação JSON Schema — para compreensão do contrato pelo LLM
read_schema_from_file	file_path, export_name?	Extrai a expressão do esquema Zod de um arquivo TypeScript/JS
detect_schema_drift	zod_file_path, schema_export_name, openapi_file_path, openapi_schema_name?	Compara Zod vs OpenAPI — relata missing_in_openapi, missing_in_zod, type_conflict, required_mismatch
evaluate_schema_evolution	schema_file_path, schema_export_name, old_schema_content?	Gera mocks a partir do esquema antigo, valida contra o novo — detecta mudanças que quebram antes da execução dos testes

Testes de contrato

Ferramenta	Argumentos	O que retorna
scaffold_api_contract_test	framework, base_url, endpoint, method, schema_code, test_name?	Código-base de teste de contrato para Playwright, Jest, Vitest ou MSW
suggest_contract_fix	schema_code, payload	Valida um payload JSON e explica cada violação com uma sugestão de correção

Configuração

1. Instalação

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

2. Adicione ao seu editor

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

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

Claude Code

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

Exemplo 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?

Exemplo de saída

generate_mock_variants — 3 mocks válidos diversos, com seed 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 ausente no OpenAPI, campo extra no 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 — novo campo obrigatório quebra 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

Licença

MIT