🌡️ MCP Weather Server

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 (>= 3.14): Linguagem de programação base do projeto.

• Model Context Protocol (MCP): Protocolo aberto que possibilita a comunicação estruturada de ferramentas e interfaces entre modelos de IA e servidores locais/remotos.

• 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: Biblioteca para construção declarativa de componentes de interface de usuário (como Card, Form, Column, Row, Text e controle de estado reativo).

• HTTPX: 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:

  • 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:

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. 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:

   uv sync

3. Execute o servidor localmente:

   uv run main.py

Opção 2: Executando com pip

1. Crie e ative um ambiente virtual:

   python -m venv .venv
   # No Windows (PowerShell):
   .venv\Scripts\Activate.ps1
   # No Linux/macOS:
   source .venv/bin/activate

2. Instale os pacotes necessários:

   pip install "fastmcp[apps]>=3.4.2" "prefab>=1.6.0" httpx pydantic

3. Execute o servidor:

   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:

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):

{
  "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.