# 🌡️ MCP Weather Server

[![Python Version](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Supported-orange.svg)](https://modelcontextprotocol.io/)
[![FastMCP](https://img.shields.io/badge/FastMCP-v3.4.2%2B-green.svg)](https://github.com/jlowin/fastmcp)

Um servidor MCP (Model Context Protocol) desenvolvido em Python que fornece uma interface de usuário interativa e ferramentas backend para consulta de temperatura em tempo real em qualquer cidade do mundo. O projeto utiliza a API pública e gratuita da **Open-Meteo** (sem necessidade de chave de API) e renderiza as informações utilizando componentes visuais declarativos de UI.

---

## 🎯 Objetivo

O principal objetivo deste projeto é estender as capacidades de assistentes de IA (como Claude Desktop ou outros clientes MCP) permitindo que eles:
1. Apresentem um formulário interativo de pesquisa de clima diretamente na interface de chat.
2. Busquem dados meteorológicos em tempo real por meio de ferramentas baseadas no protocolo MCP.
3. Exibam o resultado formatado em um card estilizado e amigável para o usuário.

---

## 🛠️ Tecnologias Utilizadas

O projeto foi construído utilizando tecnologias modernas e eficientes no ecossistema Python:

- **[Python](https://www.python.org/) (>= 3.14)**: Linguagem de programação base do projeto.
- **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)**: Protocolo aberto que possibilita a comunicação estruturada de ferramentas e interfaces entre modelos de IA e servidores locais/remotos.
- **[FastMCP](https://github.com/jlowin/fastmcp) (com suporte a `[apps]`)**: Framework moderno para criação rápida de servidores MCP em Python, incluindo suporte integrado a aplicações e interfaces visuais.
- **[Prefab UI](https://github.com/jlowin/prefab)**: Biblioteca para construção declarativa de componentes de interface de usuário (como `Card`, `Form`, `Column`, `Row`, `Text` e controle de estado reativo).
- **[HTTPX](https://www.python-httpx.org/)**: Cliente HTTP para Python, utilizado para realizar as consultas assíncronas/síncronas às APIs de geocodificação e previsão do tempo.
- **[Open-Meteo API](https://open-meteo.com/)**:
  - *Geocoding API*: Para converter o nome da cidade informado em coordenadas geográficas (latitude e longitude).
  - *Weather Forecast API*: Para buscar a temperatura atual com base nas coordenadas obtidas.

---

## 📁 Estrutura do Projeto

A estrutura do projeto é minimalista e organizada da seguinte forma:

```text
mcp_weather/
├── .gitignore            # Arquivos e pastas a serem ignorados pelo Git
├── .python-version       # Definição da versão do Python utilizada
├── pyproject.toml        # Configuração do projeto e suas dependências (PEP 518/621)
├── uv.lock               # Arquivo de lock de dependências gerado pelo gerenciador 'uv'
├── main.py               # Código-fonte principal contendo o servidor MCP e as ferramentas
└── README.md             # Documentação do projeto (este arquivo)
```

### Detalhamento do `main.py`
- **Geolocalização e Clima (`_get_current_temperature`)**: Função auxiliar que faz chamadas HTTP seguras para o Open-Meteo, tratando erros comuns (como cidades não encontradas ou indisponibilidade de API).
- **Ferramenta de Backend (`get_temperature`)**: Ferramenta registrada no FastMCP que recebe o payload do formulário, valida os dados e executa a busca meteorológica.
- **Interface de Usuário (`consultar_temperatura`)**: Ponto de entrada de UI do servidor. Ela define o estado inicial da aplicação, cria um formulário dinâmico a partir de um modelo Pydantic e renderiza os cards de sucesso ou erro de forma condicional (`If/Else`).

---

## 🚀 Instalação e Execução

Este projeto utiliza o gerenciador de pacotes moderno [**uv**](https://github.com/astral-sh/uv). Caso não tenha o `uv` instalado, você pode utilizar o `pip` tradicional.

### Opção 1: Executando com `uv` (Recomendado)

1. Certifique-se de estar com o Python 3.14 ou superior configurado.
2. Instale as dependências e crie o ambiente virtual automaticamente:
   ```bash
   uv sync
   ```
3. Execute o servidor localmente:
   ```bash
   uv run main.py
   ```

### Opção 2: Executando com `pip`

1. Crie e ative um ambiente virtual:
   ```bash
   python -m venv .venv
   # No Windows (PowerShell):
   .venv\Scripts\Activate.ps1
   # No Linux/macOS:
   source .venv/bin/activate
   ```
2. Instale os pacotes necessários:
   ```bash
   pip install "fastmcp[apps]>=3.4.2" "prefab>=1.6.0" httpx pydantic
   ```
3. Execute o servidor:
   ```bash
   python main.py
   ```

---

## 🔍 Testando com o MCP Inspector

O `@modelcontextprotocol/inspector` é uma ferramenta excelente para testar e depurar servidores MCP de forma rápida, sem a necessidade de configurá-los previamente em clientes complexos de IA.

Para testar este servidor com o inspetor, execute o seguinte comando no terminal:

```bash
npx @modelcontextprotocol/inspector uv run main.py
```

Isso iniciará o inspetor em seu navegador. Para verificar o resultado:
1. Conecte-se ao servidor MCP pelo painel do Inspetor.
2. Clique na aba **Apps** no menu do inspetor.
3. Selecione o app MCP que consulta o clima na cidade informada para interagir com o formulário e validar a resposta da temperatura.

---

## 🔌 Configuração no Claude Desktop

Para utilizar este servidor diretamente no **Claude Desktop**, adicione a configuração do servidor ao seu arquivo de configuração do Claude (`claude_desktop_config.json`).

### Caminho do arquivo de configuração
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Exemplo de Configuração
Substitua o caminho executável de acordo com o seu ambiente (usando `uv` para execução automática):

```json
{
  "mcpServers": {
    "mcp-weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\Gustavo\\workspace\\test\\mcp_weather",
        "run",
        "main.py"
      ]
    }
  }
}
```

*Nota: Certifique-se de ajustar o caminho absoluto da pasta para corresponder exatamente à localização no seu computador.*

---

## 💡 Como Funciona a Interface

Ao interagir com um modelo de linguagem que suporta o servidor, o assistente pode acionar a ferramenta visual `consultar_temperatura`. O fluxo de execução funciona assim:

1. **Apresentação**: O usuário solicita o clima, e o modelo renderiza o formulário `consultar_temperatura`.
2. **Entrada de Dados**: O usuário preenche o campo de texto com o nome da cidade desejada (ex: `São Paulo` ou `Tokyo`) e clica em **Consultar**.
3. **Processamento**: O botão aciona a ferramenta de backend `get_temperature` via ação reativa `CallTool`.
4. **Atualização de Estado**:
   - Se a busca for bem-sucedida, o estado `weather_result` é atualizado com as coordenadas e temperatura atuais, exibindo um card azul com a temperatura e localização resolvida (ex: `São Paulo, Brazil`).
   - Se ocorrer um erro (ex: cidade inexistente), a tela exibe uma mensagem de erro estilizada num card vermelho.
5. **Rodapé**: Link de atribuição de dados para a API parceira Open-Meteo.