Arquitetura

O mcp-portugal é um servidor MCP fino por cima de um conjunto de funções puras. O cliente de IA fala com ele por stdio usando o Model Context Protocol; o servidor valida os inputs com zod e delega em código de biblioteca determinístico.

sequenceDiagram
  participant C as cliente IA
  participant S as mcp-portugal (stdio)
  participant L as lib (validators / holidays)
  C->>S: tools/list
  S-->>C: validate_nif, validate_iban, list_holidays, …
  C->>S: tools/call validate_nif {nif}
  S->>S: zod valida os argumentos
  S->>L: validateNif(nif)
  L-->>S: { valid, entityType }
  S-->>C: resultado em texto JSON

Mapa de módulos

Módulo	Responsabilidade
index.ts	Servidor MCP: regista as tools, liga o transporte stdio
lib/validators.ts	Verificações de NIF / IBAN / código postal (puras)
lib/holidays.ts	Feriados nacionais incl. cálculo da Páscoa (puro)

Princípios de design

• Núcleo puro, transporte fino — toda a lógica é testável sem MCP; o servidor é um wrapper.
• Determinístico & offline — sem rede, sem chaves; os feriados são calculados, não obtidos.
• Inputs validados — schemas zod guardam cada tool antes de a lógica correr.
• Testado ponta a ponta — testes unitários da lib, mais um teste de integração stdio que aciona o servidor real com um cliente MCP.