Architecture

mcp-portugal is a thin MCP server over a set of pure functions. The AI client talks to it over stdio using the Model Context Protocol; the server validates inputs with zod and delegates to deterministic library code.

sequenceDiagram
  participant C as AI client
  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 validates arguments
  S->>L: validateNif(nif)
  L-->>S: { valid, entityType }
  S-->>C: JSON text result

Module map

Module	Responsibility
index.ts	MCP server: registers tools, wires stdio transport
lib/validators.ts	NIF / IBAN / postal-code checks (pure)
lib/holidays.ts	National holidays incl. Easter computation (pure)

Design principles

• Pure core, thin transport — all logic is testable without MCP; the server is a wrapper.
• Deterministic & offline — no network, no API keys; holidays are computed, not fetched.
• Validated inputs — zod schemas guard every tool before logic runs.
• Tested end to end — unit tests for the lib, plus a stdio integration test that drives the real server with an MCP client.