MCP Weather Server

Um servidor MCP (Model Context Protocol) para busca de dados climáticos com suporte a streaming HTTP, desenvolvido em TypeScript.

🚀 Características

🌤️ Dados climáticos em tempo real - Temperatura, umidade, pressão, vento e mais
📡 Streaming HTTP - Requisições assíncronas e eficientes
🗺️ Múltiplas formas de busca - Por cidade, país ou coordenadas geográficas
🔮 Previsão do tempo - Previsão para 5 dias com dados detalhados
🌍 Suporte internacional - Cidades em qualquer país
📊 Dados estruturados - Resposta em JSON bem formatado
🐳 Docker ready - Containerizado para fácil deploy
☸️ Kubernetes ready - Configurado para deploy no AKS
🔧 Health checks - Endpoints para monitoramento
📈 Métricas - Endpoint básico de métricas

📋 Pré-requisitos

Node.js 18+
Docker (para containerização)
Azure CLI (para deploy no AKS)
kubectl (para gerenciamento do Kubernetes)
Chave da API OpenWeatherMap

🛠️ Instalação

1. Clone o repositório

git clone <seu-repositorio>
cd mcp-weather

2. Instale as dependências

npm install

3. Configure a API key

# Copie o arquivo de exemplo
cp .env.example .env

# Edite o arquivo .env com sua chave da API
nano .env

4. Obtenha uma chave da API OpenWeatherMap

Visite OpenWeatherMap
Crie uma conta gratuita
Gere uma API key
Configure no arquivo .env

🚀 Execução

Desenvolvimento

# Executar em modo desenvolvimento
npm run dev

# Executar em modo watch
npm run watch

Produção

# Build da aplicação
npm run build

# Executar em produção
npm start

Docker

# Build da imagem
npm run docker:build

# Executar container
npm run docker:run

# Ou usar docker-compose
npm run docker:compose

🔧 Ferramentas MCP Disponíveis

1. get_current_weather

Obtém dados climáticos atuais para uma cidade.

Parâmetros:

city (obrigatório): Nome da cidade
country (opcional): Código do país (ex: "BR", "US")
units (opcional): Unidade de medida ("metric", "imperial", "standard")

2. get_weather_forecast

Obtém previsão do tempo para 5 dias.

Parâmetros:

city (obrigatório): Nome da cidade
country (opcional): Código do país
units (opcional): Unidade de medida

3. get_weather_by_coordinates

Obtém dados climáticos usando coordenadas geográficas.

Parâmetros:

lat (obrigatório): Latitude
lon (obrigatório): Longitude
units (opcional): Unidade de medida

🧪 Teste

Cliente de exemplo

# Executar todos os exemplos
npm run client

# Clima atual
npm run client current "São Paulo" "BR"

# Previsão do tempo
npm run client forecast "Rio de Janeiro" "BR"

# Por coordenadas
npm run client coords -23.5505 -46.6333

# Listar recursos e ferramentas
npm run client list

Endpoints HTTP

# Health check
curl http://localhost:8080/health

# Status da aplicação
curl http://localhost:8080/status

# Métricas básicas
curl http://localhost:8080/metrics

📊 Recursos MCP

weather://current

Recurso para acessar dados climáticos atuais.

weather://forecast

Recurso para acessar previsões do tempo.

🐳 Deploy no Azure Kubernetes Service (AKS)

Pré-requisitos

Azure CLI instalado e configurado
kubectl instalado
Docker instalado
Variáveis de ambiente configuradas

Deploy automatizado

# Tornar script executável
chmod +x scripts/deploy-aks.sh

# Executar deploy
./scripts/deploy-aks.sh

Deploy manual

# 1. Criar Resource Group
az group create --name rg-mcp-weather-poc --location brazilsouth

# 2. Criar ACR
az acr create --resource-group rg-mcp-weather-poc --name acrmcpweather --sku Basic

# 3. Criar cluster AKS
az aks create --resource-group rg-mcp-weather-poc --name aks-mcp-weather --attach-acr acrmcpweather

# 4. Obter credenciais
az aks get-credentials --resource-group rg-mcp-weather-poc --name aks-mcp-weather

# 5. Build e push da imagem
docker build -f deploy/Dockerfile -t acrmcpweather.azurecr.io/weather-mcp:latest .
docker push acrmcpweather.azurecr.io/weather-mcp:latest

# 6. Deploy no Kubernetes
kubectl apply -f deploy/aks-deployment.yaml

Limpeza de recursos

# Executar script de limpeza
./scripts/cleanup-aks.sh

📝 Exemplo de Resposta

Clima Atual

{
  "location": {
    "city": "São Paulo",
    "country": "BR",
    "coordinates": {
      "lat": -23.5505,
      "lon": -46.6333
    }
  },
  "current": {
    "temperature": 22.5,
    "feels_like": 24.1,
    "humidity": 65,
    "pressure": 1013,
    "description": "céu limpo",
    "icon": "01d",
    "wind_speed": 3.2,
    "wind_direction": 180,
    "visibility": 10,
    "uv_index": 5
  },
  "units": "metric",
  "timestamp": "2025-01-15T10:30:00Z"
}

🔧 Configuração para Claude Desktop

Adicione ao arquivo de configuração do Claude:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/mcp-weather/dist/index.js"],
      "env": {
        "OPENWEATHERMAP_API_KEY": "sua_api_key"
      }
    }
  }
}

📁 Estrutura do Projeto

mcp-weather/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   └── client.ts             # Cliente de exemplo
├── deploy/
│   ├── Dockerfile            # Dockerfile otimizado
│   ├── docker-compose.yml    # Docker Compose
│   └── aks-deployment.yaml   # Manifests Kubernetes
├── scripts/
│   ├── deploy-aks.sh         # Script de deploy AKS
│   └── cleanup-aks.sh        # Script de limpeza
├── tests/
│   └── (testes futuros)
├── package.json
├── tsconfig.json
└── README.md

🚨 Limitações da API

Plano Gratuito: 1000 chamadas/mês, 60 chamadas/minuto
Dados históricos: Limitados no plano gratuito
Resolução: Dados atualizados a cada 10 minutos

🐛 Troubleshooting

Problemas comuns

Erro de API Key

# Verifique se a variável está configurada
echo $OPENWEATHERMAP_API_KEY

Erro de conectividade

# Teste a conectividade com a API
curl "https://api.openweathermap.org/data/2.5/weather?q=London&appid=SUA_API_KEY"

Problema com Docker

# Limpar containers e imagens
docker system prune -a

Problema com Kubernetes

# Verificar logs dos pods
kubectl logs -f -n mcp-weather deployment/weather-mcp

# Verificar eventos
kubectl get events -n mcp-weather

📈 Monitoramento

Métricas disponíveis

Health check: /health
Readiness: /ready
Métricas: /metrics
Status: /status

Logs

# Logs do container
docker logs -f <container-id>

# Logs do Kubernetes
kubectl logs -f -n mcp-weather deployment/weather-mcp

🤝 Contribuição

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

📄 Licença

Distribuído sob a licença MIT. Veja LICENSE para mais informações.

🙏 Agradecimentos

OpenWeatherMap pela API de dados climáticos
Model Context Protocol pela especificação
Azure Kubernetes Service pela plataforma

⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!

MCP Weather Server

MCP Weather Server

🚀 Características

📋 Pré-requisitos

🛠️ Instalação

1. Clone o repositório

2. Instale as dependências

3. Configure a API key

4. Obtenha uma chave da API OpenWeatherMap

🚀 Execução

Desenvolvimento

Produção

Docker

🔧 Ferramentas MCP Disponíveis

1. get_current_weather

2. get_weather_forecast

3. get_weather_by_coordinates

🧪 Teste

Cliente de exemplo

Endpoints HTTP

📊 Recursos MCP

weather://current

weather://forecast

🐳 Deploy no Azure Kubernetes Service (AKS)

Pré-requisitos

Deploy automatizado

Deploy manual

Limpeza de recursos

📝 Exemplo de Resposta

Clima Atual

🔧 Configuração para Claude Desktop

📁 Estrutura do Projeto

🚨 Limitações da API

🐛 Troubleshooting

Problemas comuns

📈 Monitoramento

Métricas disponíveis

Logs

🤝 Contribuição

📄 Licença

🙏 Agradecimentos

Reviews