# weather-mcp

Servidor **MCP** (Model Context Protocol) de previsão do tempo. Recebe o nome de
uma cidade (ex.: `Recife,BR`) e retorna a previsão usando a API do
[OpenWeather](https://openweathermap.org/) via [PyOWM](https://pyowm.readthedocs.io/).

O transporte é **Streamable HTTP**, então o servidor sobe em
`http://127.0.0.1:8000/mcp` e pode ser consumido por qualquer cliente MCP.

O código do servidor cabe em ~30 linhas (`server.py`) — feito para servir de
demo/exemplo em apresentações.

## Getting Started

### 1. Pré-requisitos

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (gerenciador de pacotes/projeto)
- Uma **API Key do OpenWeather** — crie uma conta gratuita em
  https://home.openweathermap.org/api_keys

### 2. Setup do projeto

```bash
# instala as dependências no ambiente virtual do projeto
uv sync
```

### 3. Configuração da API Key

A chave é lida da variável de ambiente `OPENWEATHER_API_KEY`.

```bash
export OPENWEATHER_API_KEY="sua_chave_aqui"
```

> Dica: você também pode criar um arquivo `.env` e carregá-lo (ex.:
> `export $(cat .env | xargs)`), mas exportar a variável já é suficiente.

### 4. Execução

```bash
uv run python server.py
```

Saída esperada:

```
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

O endpoint MCP fica disponível em **`http://127.0.0.1:8000/mcp`**.

### 5. Teste rápido (opcional)

Use o inspector oficial para explorar o servidor pelo navegador:

```bash
npx @modelcontextprotocol/inspector
```

No inspector, escolha o transporte **Streamable HTTP** e aponte para
`http://127.0.0.1:8000/mcp`. A tool disponível é `get_forecast(city)`.

## Configuração nos clientes MCP

Deixe o servidor rodando (`uv run python server.py`) antes de configurar os
clientes abaixo. Todos apontam para o mesmo endpoint HTTP.

### VSCode + GitHub Copilot

Crie o arquivo `.vscode/mcp.json` na raiz do workspace:

```json
{
  "servers": {
    "weather": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

Abra o **Copilot Chat** no modo **Agent**, clique no ícone de ferramentas e
confirme que a tool `get_forecast` aparece.

### Claude Code

Registre o servidor com transporte HTTP:

```bash
claude mcp add --transport http weather http://127.0.0.1:8000/mcp
```

Verifique com `claude mcp list`. Dentro de uma sessão, use `/mcp` para inspecionar
o servidor e suas tools.

### Codex

No arquivo de configuração `~/.codex/config.toml`, adicione:

```toml
[mcp_servers.weather]
url = "http://127.0.0.1:8000/mcp"
```

> Dependendo da versão do Codex CLI, o suporte a transporte HTTP exige habilitar
> o cliente RMCP. Se o servidor não conectar, adicione ao topo do
> `~/.codex/config.toml`:
>
> ```toml
> experimental_use_rmcp_client = true
> ```

## Como funciona

```python
# server.py
mcp = FastMCP("weather")
owm = OWM(os.environ["OPENWEATHER_API_KEY"])

@mcp.tool()
def get_forecast(city: str) -> str:
    forecast = owm.weather_manager().forecast_at_place(city, "3h").forecast
    ...

mcp.run(transport="streamable-http")
```

- `FastMCP` expõe a função decorada com `@mcp.tool()` como uma tool MCP.
- `forecast_at_place(city, "3h")` usa a previsão gratuita de 5 dias / 3 horas do
  OpenWeather.
- `transport="streamable-http"` sobe o servidor HTTP em `/mcp`.

## Exemplo de uso

Pergunte ao seu assistente:

> Qual a previsão do tempo para Recife?

Ele chamará `get_forecast("Recife,BR")` e responderá com base no retorno da tool.