# 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
```bash
git clone <seu-repositorio>
cd mcp-weather
```
### 2. Instale as dependências
```bash
npm install
```
### 3. Configure a API key
```bash
# 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
1. Visite [OpenWeatherMap](https://openweathermap.org/api)
2. Crie uma conta gratuita
3. Gere uma API key
4. Configure no arquivo `.env`
## 🚀 Execução
### Desenvolvimento
```bash
# Executar em modo desenvolvimento
npm run dev
# Executar em modo watch
npm run watch
```
### Produção
```bash
# Build da aplicação
npm run build
# Executar em produção
npm start
```
### Docker
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Tornar script executável
chmod +x scripts/deploy-aks.sh
# Executar deploy
./scripts/deploy-aks.sh
```
### Deploy manual
```bash
# 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
```bash
# Executar script de limpeza
./scripts/cleanup-aks.sh
```
## 📝 Exemplo de Resposta
### Clima Atual
```json
{
"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:
```json
{
"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
1. **Erro de API Key**
```bash
# Verifique se a variável está configurada
echo $OPENWEATHERMAP_API_KEY
```
2. **Erro de conectividade**
```bash
# Teste a conectividade com a API
curl "https://api.openweathermap.org/data/2.5/weather?q=London&appid=SUA_API_KEY"
```
3. **Problema com Docker**
```bash
# Limpar containers e imagens
docker system prune -a
```
4. **Problema com Kubernetes**
```bash
# 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
```bash
# Logs do container
docker logs -f <container-id>
# Logs do Kubernetes
kubectl logs -f -n mcp-weather deployment/weather-mcp
```
## 🤝 Contribuição
1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request
## 📄 Licença
Distribuído sob a licença MIT. Veja `LICENSE` para mais informações.
## 🙏 Agradecimentos
- [OpenWeatherMap](https://openweathermap.org/) pela API de dados climáticos
- [Model Context Protocol](https://github.com/modelcontextprotocol) pela especificação
- [Azure Kubernetes Service](https://azure.microsoft.com/services/kubernetes-service/) pela plataforma
---
⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!
