🌤️ Weather MCP Server - Clean Architecture Edition [Docker + Redis]

Servidor MCP de Clima com Clean Architecture para Claude Desktop - Production Ready

Claude AI transformado em estação meteorológica profissional usando princípios SOLID

🎉 VERSÃO ATUAL: 2.0.0 - Clean Architecture Completa ✅ Refatoração concluída • ✅ Zero legacy code • ✅ Production ready

📊 Status do Projeto

Aspecto	Status	Descrição
Build		TypeScript compilation + Docker build
Tests		Unit tests + Integration tests
Security		Trivy vulnerability scan + npm audit
Docker		Multi-stage build otimizado
Deploy		CI/CD pipeline automatizado

🔄 CI/CD Pipeline

Este projeto implementa um pipeline CI/CD completo com GitHub Actions:

🔍 Lint & Type Check → 🧪 Tests → 🏗️ Build → 🔒 Security → 🐳 Docker → 🚀 Deploy

Pipeline Stages:

• 🔍 Lint & Type Check: ESLint + TypeScript compilation check
• 🧪 Tests: Unit tests com mocks + Integration tests com PostgreSQL/Redis
• 🏗️ Build: TypeScript compilation + artifact generation
• 🔒 Security: Trivy vulnerability scanner + npm audit
• 🐳 Docker: Multi-stage build + push to GitHub Container Registry
• 🚀 Deploy: Automated deployment para staging/production

Comandos de Teste Locais:

npm run test:unit        # Tests unitários (sem dependências)
npm run test:integration # Tests de integração (requer Docker)
npm run test:ci          # Tests para CI com coverage

---

🎯 O que é este projeto?

O Weather MCP Server é um servidor Model Context Protocol (MCP) que expande as capacidades do Claude Desktop, permitindo que ele consulte informações meteorológicas em tempo real de qualquer lugar do mundo usando uma arquitetura limpa e profissional.

🧠 Entendendo o MCP (Model Context Protocol)

O MCP é um protocolo desenvolvido pela Anthropic que permite ao Claude AI:

• 🔌 Conectar-se a APIs externas e bancos de dados
• 🛠️ Usar ferramentas personalizadas criadas pela comunidade
• 📊 Acessar dados em tempo real que não estão em seu conhecimento base
• 🎮 Executar ações específicas através de plugins

Em outras palavras: O MCP transforma o Claude de uma IA com conhecimento limitado em uma IA que pode acessar informações atualizadas do mundo real!

🌟 Funcionalidades Disponíveis

🎯 Funcionalidade	📋 Descrição	💡 Exemplo de Uso
🌡️ Clima Atual	Consulta temperatura, umidade, pressão e condições meteorológicas atuais	"Qual é a temperatura atual em São Paulo?"
🔮 Previsão do Tempo	Fornece previsões detalhadas para os próximos 5 dias	"Como estará o clima amanhã em Londres?"
📊 Histórico Meteorológico	Mantém registro de todas as consultas realizadas	"Mostre-me as últimas consultas de clima que fiz"
⚡ Cache Inteligente	Sistema Redis para consultas ultrarrápidas	95% das consultas vêm do cache

---

🚀 Demonstração Prática

Antes (Claude Desktop sem MCP):

🙋 Você: "Qual é a temperatura atual em Tóquio?"
🤖 Claude: "Desculpe, não tenho acesso a dados meteorológicos em tempo real..."

Depois (Claude Desktop com Weather MCP Server):

🙋 Você: "Qual é a temperatura atual em Tóquio?"
🤖 Claude: "🌤️ Em Tóquio agora:
           🌡️ Temperatura: 23°C (sensação térmica: 25°C)
           💧 Umidade: 68%
           🌬️ Vento: 12 km/h
           ☁️ Condições: Parcialmente nublado
           📊 Dados atualizados em tempo real via OpenWeatherMap"

---

🏗️ Arquitetura Clean + SOLID

graph TB
    subgraph "🎮 Presentation Layer"
        A[👤 Claude Desktop] --> B[🤖 MCP Server]
        B --> C[🎮 Weather Controller]
        B --> D[🎮 History Controller]
    end
    
    subgraph "🔧 Application Layer (Use Cases)"
        C --> E[🌤️ Get Weather Use Case]
        C --> F[🔮 Get Forecast Use Case]  
        C --> G[📊 Get Cache Stats Use Case]
        D --> H[📚 Get History Use Case]
    end
    
    subgraph "🏛️ Domain Layer"
        E --> I[⚡ Weather Entity]
        F --> I
        H --> J[📊 History Entity]
        K[🔗 Repository Interfaces]
    end
    
    subgraph "🏗️ Infrastructure Layer (Adapters)"
        E --> L[🌍 OpenWeather API Repository]
        E --> M[🗄️ PostgreSQL Repository]
        E --> N[⚡ Redis Cache Repository]
        F --> L
        F --> N
        H --> M
        L --> O[🌤️ OpenWeatherMap API]
        M --> P[🗄️ PostgreSQL Database]
        N --> Q[⚡ Redis Cache]
    end

✅ Princípios SOLID Aplicados:

🔤 Princípio	✅ Como foi aplicado	💡 Benefício
S - Single Responsibility	Cada classe tem apenas uma responsabilidade	Código mais limpo e focado
O - Open/Closed	Extensível via interfaces, fechado para modificação	Fácil adicionar novas APIs
L - Liskov Substitution	Implementações intercambiáveis via contratos	Flexibilidade total
I - Interface Segregation	Interfaces pequenas e específicas	Sem dependências desnecessárias
D - Dependency Inversion	Dependências injetadas via abstrações	Testabilidade e desacoplamento

---

📋 Pré-requisitos

🔧 Software Necessário:

📦 Software	📏 Versão Mínima	🔗 Download	✅ Verificar
Node.js	18.0+	nodejs.org	node --version
Docker Desktop	Mais recente	docker.com	docker --version
Claude Desktop	Mais recente	claude.ai/download	Abrir aplicativo
Git	Qualquer	git-scm.com	git --version

🔑 Chaves de API:

1. 🌍 OpenWeatherMap API Key (GRATUITA)
   • 🔗 Acesse: openweathermap.org/api
   • 📝 Crie uma conta gratuita
   • 🗝️ Obtenha sua API key (sem custo)
   • 💡 Permite 1.000 consultas por dia grátis

---

📥 Instalação Completa

🗂️ Passo 1: Baixar o Projeto

# Clonar repositório
git clone https://github.com/glaucia86/weather-mcp-server.git

# Entrar na pasta
cd weather-mcp-server

# Verificar estrutura
ls -la

📦 Passo 2: Instalar Dependências

# Instalar pacotes Node.js
npm install

# Verificar instalação
npm list --depth=0

⚙️ Passo 3: Configurar Ambiente

Criar arquivo .env:

# Copiar exemplo
cp .env.example .env

Configuração do .env:

# 🌍 API do OpenWeatherMap (OBRIGATÓRIO)
WEATHER_API_KEY=sua_api_key_aqui

# 🗄️ Banco de Dados (PostgreSQL)
DATABASE_URL=postgresql://mcp_user:mcp_pass@localhost:5432/weather_mcp

# ⚡ Cache (Redis) 
REDIS_URL=redis://localhost:6379

# 🖥️ Configurações do Servidor
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

🔨 Passo 4: Compilar e Iniciar

# Compilar TypeScript
npm run build

# Iniciar infraestrutura (PostgreSQL + Redis)
npm run docker:up

# Aguardar inicialização
sleep 30

# Testar sistema
npm run test:manual

---

🎮 Configuração do Claude Desktop

📍 Localizar Arquivo de Configuração:

🖥️ Sistema	📂 Caminho do Arquivo
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

⚙️ Configuração:

{
  "mcpServers": {
    "weather-mcp": {
      "command": "node",
      "args": ["/caminho/completo/para/weather-mcp-server/dist/mcp-entry.js"],
      "env": {
        "WEATHER_API_KEY": "SUA_API_KEY_OPENWEATHERMAP",
        "DATABASE_URL": "postgresql://mcp_user:mcp_pass@localhost:5432/weather_mcp",
        "REDIS_URL": "redis://localhost:6379",
        "NODE_ENV": "production",
        "LOG_LEVEL": "error",
        "MCP_MODE": "true"
      }
    }
  }
}

⚠️ IMPORTANTE:

• Substitua /caminho/completo/para/ pelo seu caminho real
• Substitua SUA_API_KEY_OPENWEATHERMAP pela sua chave OpenWeatherMap
• Feche COMPLETAMENTE o Claude Desktop e reabra após salvar

---

🎪 Como Usar

1️⃣ Consultas de Clima Atual

💬 "Qual é o clima atual em São Paulo?"
💬 "Como está o tempo em Londres agora?"
💬 "Temperatura atual no Rio de Janeiro"

2️⃣ Previsões do Tempo

💬 "Qual será a previsão do tempo para amanhã em Paris?"
💬 "Como estará o clima nos próximos 3 dias em Tokyo?"
💬 "Previsão de 5 dias para London"

3️⃣ Histórico e Análises

💬 "Me mostre o histórico de consultas meteorológicas"
💬 "Quais foram as últimas cidades que consultei?"
💬 "Histórico de clima de São Paulo dos últimos 10 registros"

4️⃣ Estatísticas do Sistema

💬 "Mostre as estatísticas do cache Redis"
💬 "Qual é a performance do sistema?"

---

🛠️ Scripts Disponíveis

🎯 Finalidade	💻 Comando	📋 Descrição
Start Server	npm start	Servidor principal
MCP Server	npm run start:mcp	Servidor MCP para Claude Desktop
Build	npm run build	Compila TypeScript
Test MCP	npm run test:manual	Testa servidor MCP
Dev Mode	npm run dev	Desenvolvimento com hot-reload
Clean	npm run clean	Remove builds anteriores
Docker Up	npm run docker:up	Inicia PostgreSQL + Redis
Docker Down	npm run docker:down	Para containers
Migrate	npm run migrate	Executa migrações de banco

---

🏗️ Estrutura do Projeto

src/
├── 🏛️ domain/                    # Camada de Domínio (Business Rules)
│   ├── entities/                # Entidades do domínio
│   │   └── Weather.ts          # Modelos meteorológicos
│   └── repositories/           # Contratos/Interfaces
│       └── IRepositories.ts    # Interfaces dos repositórios
│
├── 🔧 application/              # Camada de Aplicação (Use Cases)
│   └── usecases/               # Casos de uso específicos
│       ├── GetCurrentWeatherUseCase.ts
│       ├── GetWeatherForecastUseCase.ts
│       ├── GetWeatherHistoryUseCase.ts
│       └── GetCacheStatisticsUseCase.ts
│
├── 🏗️ infrastructure/          # Camada de Infraestrutura (Adapters)
│   ├── logger/                 # Sistema de logging
│   │   └── Logger.ts
│   ├── repositories/           # Implementações dos repositórios
│   │   ├── PostgreSQLWeatherRepository.ts
│   │   ├── RedisCacheRepository.ts
│   │   └── OpenWeatherMapApiRepository.ts
│   └── di/                     # Dependency Injection
│       └── DIContainer.ts
│
├── 🎮 presentation/             # Camada de Apresentação
│   ├── controllers/            # Controllers
│   │   ├── WeatherController.ts
│   │   └── HistoryController.ts
│   └── servers/               # Servidores
│       └── WeatherMCPServer.ts
│
├── 🛡️ middleware/              # Middleware de Segurança
│   └── security.ts
│
├── 📊 monitoring/              # Monitoramento
│   └── health.ts
│
├── 🧪 scripts/                 # Scripts Utilitários (3 essenciais)
│   ├── benchmark-cache.ts     # Benchmark de performance
│   ├── migrate.ts            # Migração de banco
│   └── test-mcp-server.ts    # Teste do servidor MCP
│
├── index.ts                   # Entry point principal
└── mcp-entry.ts              # Entry point MCP

---

⚡ Performance e Cache

📈 Métricas de Performance Reais:

📊 Métrica	⚡ Com Cache	🐌 Sem Cache	🎯 Melhoria
Resposta API	23ms	315ms	13.6x mais rápido
Taxa de Acerto	95%	0%	Economia massiva
Chamadas API	5 (em 50 requests)	50	90% menos

🔍 Verificar Cache:

# Ver todas as chaves do cache
docker exec weather-cache redis-cli keys "*"

# Estatísticas do Redis
docker exec weather-cache redis-cli info stats

# Ver TTL de uma chave
docker exec weather-cache redis-cli ttl "weather:sao paulo"

---

🚨 Solução de Problemas

❌ "Cannot find module"

# Limpeza completa
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build

❌ "Connection refused" (PostgreSQL)

# Verificar containers
docker ps

# Reiniciar infrastructure
npm run docker:down
npm run docker:up

# Aguardar inicialização
sleep 30

❌ MCP não conecta no Claude Desktop

1. ✅ Verifique se o caminho no claude_desktop_config.json está correto
2. 📂 Confirme se dist/mcp-entry.js existe (npm run build)
3. 🔄 Feche completamente o Claude Desktop e reabra
4. 🧪 Teste manual: node dist/mcp-entry.js

---

📊 Status Atual - Agosto 2025

✅ Clean Architecture 100% Implementada:

• Arquitetura Completa: domain/, application/, infrastructure/, presentation/
• Dependency Injection: Container DI funcionando perfeitamente
• Princípios SOLID: Aplicados rigorosamente
• 4 MCP Tools: Registradas e funcionando no Claude Desktop
• Database + Cache: PostgreSQL + Redis operacionais
• Zero Legacy Code: Arquivos desnecessários removidos

🎯 MCP Tools Funcionais:

🔧 Tool	📋 Função	✅ Status
get_current_weather	Clima atual de qualquer cidade	✅ Funcionando
get_weather_forecast	Previsão 5 dias	✅ Funcionando
get_weather_history	Histórico de consultas	✅ Funcionando
get_cache_statistics	Estatísticas do sistema	✅ Funcionando

---

🤝 Contribuindo

1. 🍴 Fork este repositório
2. 🌿 Crie uma branch (git checkout -b feature/MinhaFeature)
3. 💻 Desenvolva sua funcionalidade
4. ✅ Teste completamente
5. 📝 Commit (git commit -m 'Adiciona MinhaFeature')
6. 📤 Push (git push origin feature/MinhaFeature)
7. 🔄 Abra um Pull Request

---

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

---

👩‍💻 Autora