# mcp-servicos-pt

Servidor MCP de serviços portugueses. Primeiro conector: **IPMA**
(meteorologia) — API pública, sem chave, sem autenticação.

## Estrutura

```
src/mcp_servicos_pt/
├── server.py              # monta o servidor, regista conectores
├── __main__.py            # ponto de entrada (`python -m mcp_servicos_pt`)
├── core/connector.py       # contrato que cada conector cumpre
└── connectors/ipma/
    ├── client.py           # HTTP puro, fala com api.ipma.pt — sem MCP
    ├── models.py           # traduz a resposta bruta para JSON legível
    └── connector.py        # regista as tools no servidor MCP
```

## Instalar

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Testar a lógica (sem rede)

```bash
pytest tests/ -v
```

## Correr o servidor e testar com o MCP Inspector

O Inspector é a ferramenta oficial para testar um servidor MCP
visualmente, sem precisar de configurar o Claude Desktop.

```bash
npx @modelcontextprotocol/inspector python -m mcp_servicos_pt
```

Abre o URL que aparece no terminal, clica em "List Tools" e devem
aparecer `listar_localidades_pt` e `previsao_tempo_pt`. Chama
`listar_localidades_pt` primeiro para obteres um `globalIdLocal`
válido, e usa-o depois em `previsao_tempo_pt`.

## Ligar ao Claude Desktop

No ficheiro de configuração do Claude Desktop
(`~/Library/Application Support/Claude/claude_desktop_config.json`
no macOS, ou o equivalente no Windows/Linux), acrescenta:

```json
{
  "mcpServers": {
    "servicos-pt": {
      "command": "/caminho/completo/para/.venv/bin/python",
      "args": ["-m", "mcp_servicos_pt"],
      "cwd": "/caminho/completo/para/mcp-servicos-pt"
    }
  }
}
```

Reinicia o Claude Desktop e pergunta algo como "que tempo vai fazer em
Lisboa nos próximos dias?" — o modelo deve encadear as duas tools
sozinho.

## Nota importante sobre os nomes dos campos do IPMA

Este projeto foi construído num ambiente sem acesso de rede a
`api.ipma.pt`, por isso os nomes dos campos em `models.py` (`tMin`,
`tMax`, `idWeatherType`, `forecastDate`, ...) vêm da documentação
pública conhecida do IPMA, mas **não foram confirmados com uma
chamada real**. O código foi escrito de forma defensiva (usa `.get()`
em vez de aceder direto às chaves), por isso não deve rebentar mesmo
que um nome tenha mudado — mas antes de confiares nos valores,
corre `listar_localidades_pt` e `previsao_tempo_pt` no teu ambiente,
compara com a resposta bruta em https://api.ipma.pt/open-data/ e
ajusta `models.py` se algum campo não bater certo. O resto da
arquitetura não muda.

## Próximo passo

Para adicionar um segundo serviço (ex. `dados.gov.pt`):

1. Cria `connectors/dados_gov/{client,models,connector}.py` seguindo
   exatamente o mesmo padrão do IPMA.
2. Regista-o em `server.py`:
   `DadosGovConnector().register(mcp)`

Nada no núcleo precisa de mudar.