FAQ & resolução de problemas

O servidor não aparece no Claude Desktop / Cursor

Verifica o caminho e o JSON da config MCP e reinicia totalmente o cliente. Confirma que o comando corre isolado: npx -y mcp-portugal deve arrancar e imprimir mcp-portugal ready (stdio) no stderr. É necessário Node 20+.

Como testo sem um cliente?

Usa o MCP Inspector: npx @modelcontextprotocol/inspector npx -y mcp-portugal e depois chama uma ferramenta como list_holidays com { "year": 2026 }.

Os feriados são oficiais / estão sempre corretos?

Cobrem os feriados nacionais obrigatórios, incluindo os móveis (baseados na Páscoa) calculados pelo algoritmo Gregoriano Anónimo. Feriados municipais e a Terça-feira de Carnaval (facultativa) são excluídos de propósito, por não serem nacionais por lei.

O validate_nif confirma que o NIF é real?

Não — valida apenas estrutura e dígito de controlo, e classifica o tipo de contribuinte. Não contacta a AT.

Corre totalmente offline?

Sim. Todas as ferramentas são determinísticas e locais — sem rede, sem chaves de API.

Posso acrescentar as minhas ferramentas?

Sim — põe a lógica pura em src/lib/, regista uma tool em src/index.ts com um schema zod, e acrescenta um teste. Ver CONTRIBUTING.