Criando MCP Server de Clima Production-Ready com Clean Architecture, Cache Redis e Princípios SOLID | Guia Completo

No panorama em rápida evolução do desenvolvimento de IA, a integração entre modelos de linguagem e dados do mundo real tornou-se um pilar fundamental das aplicações modernas. Hoje, mergulharemos profundamente em um sofisticado MCP Server (Model Context Protocol) de Clima que transforma o Claude Desktop de uma IA estática numa estação metereológica dinâmica, aproveitando princípios de Clean Architecture, Cache Redis e SOLID.. Esta solução production-ready demonstra como criar aplicações alimentadas por IA que sejam escaláveis e mantíveis, criando uma ponte entre IA conversacional e serviços de dados em tempo real.

---

O Model Context Protocol (MCP) representa uma mudança de paradigma na forma como expandimos as capacidades da IA, e poucas implementações demonstram esse potencial de forma tão elegante quanto o Weather MCP Server. O projeto foi criado em TypeScript, exemplifica princípios modernos de arquitetura de software enquanto resolve um problema prático: permitir que o Claude Desktop acesse informações metereológicas em tempo real de qualquer lugar do mundo.

O que torna esse projeto especial?

Se você está curioso sobre a profundidade e as decisões arquitetônicas que moldaram este projeto, vamos explorar o que faz deste Weather MCP Server um exemplo excepcional de integração de IA production-ready.

glaucia86 / weather-mcp-server

A robust Weather MCP Server in TypeScript

🌤️ 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…

View on GitHub

A visão por trás do Clean Architecture

A Clean Architecture é um conceito que visa criar sistemas de software que sejam independentes de frameworks, bancos de dados e outras preocupações externas. O objetivo é permitir que a lógica de negócios permaneça intacta, mesmo quando as tecnologias subjacentes mudam. No contexto do Weather MCP Server, isso significa que a aplicação pode evoluir e se adaptar a novas necessidades sem comprometer sua estrutura fundamental.

A Glaucia Lemos, Softawe AI Engineer e ex-Microsoft trouxe a seguinte uma abordagem que demonstra em como criar integrações de IA que são:

• Mantíveis: separação clara de responsabilidade entre camadas arquiteturais, facilitando a manutenção e evolução do sistema.

• Escaláveis: projetadas para lidar com demandas crescentes e novas funcionalidades.

• Testáveis: estratégias abrangentes de testes unitários e de integração

• Extensíveis: fácil adição de novos provedores de clima ou fonte de dados.

Você pode explorar o código-fonte completo e a documentação do projeto no repositório do GitHub para entender melhor como esses princípios foram aplicados na prática.

Desvendando a Arquitetura MCP

O Model Context Protocol (MCP) representa uma abordagem revolucionária para expandir as capacidades da IA. Diferente das APIs tradicionais que requerem prompting constante, o MCP permite interações persistentes e contextuais entre modelos de IA e sistemas externos. Este Weather MCP Server demonstra como o MCP pode transformar o Claude Desktop de uma IA conversacional em um especialista metereológico.

Anatomia Técnica do MCP Server

Vamos entender um pouco mais o código: WeatherMCPServer.ts como contribui para a funcionalidade total:

Imports fundamentais e suas responsabilidades:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ListPromptsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

O Server é uma classe principal que gerencia todas as comunicações do MCP. Ela atua como o núcleo do protocolo, coordenando requisições e respostas entre Claude Desktop e nosso servidor metereológico.

O StudioServerTransport implementa o protocolo de comunicação via STDIO (Standard Input/Output). Esta é a ponte que permite ao Claude Desktop comunicar-se com o nosso servidor através da entrada e saída padrão, eliminando a necessidade de protocolos de rede complexos.

• Schemas de Requisição: cada schema define um tipo específico de interação:
  • CallToolRequestSchema: valida requisições para executar ferramentas específicas. Nesse caso, ele garante que as chamadas para ferramentas meteorológicas sejam formatadas corretamente e contenham todas as informações necessárias.
  • ListToolsRequestSchema: gerencia listagem de ferramentas disponíveis
  • ListResourcesRequestSchema: define recursos estáticos disponíveis.
  • ListPromptsRequestSchema: configura prompts predefinidos para interações.

Integração com o Clean Architecture

import { DIContainer } from '../../infrastructure/di/DIContainer.js';
import { WeatherController } from '../controllers/WeatherController.js';
import { HistoryController } from '../controllers/HistoryController.js';
import { ILogger } from '../../infrastructure/logger/Logger.js';

Estes imports demonstram a separação de responsabilidades do Clean Architecture, onde:

• DIContainer: Gerencia injeção de dependências, garantindo baixo acoplamento
• WeatherController: Implementa a lógica de apresentação para interações relacionadas ao clima
• HistoryController: Gerencia o histórico de interações e dados
• ILogger: Interface de logging que permite diferentes implementações

Construção e Inicialização do Server

constructor() {
  this.server = new Server(
    {
      name: "weather-mcp",
      version: "1.0.0",
    },
    {
      capabilities: {
        tools: {},      // Ferramentas executáveis
        resources: {},  // Recursos estáticos
        prompts: {},    // Prompts predefinidos
      },
    }
  );

Capabilities do MCP Explicadas:

• Tools: Funções executáveis que o Claude pode chamar (ex: buscar clima atual)
• Resources: Dados estáticos ou dinâmicos que o Claude pode acessar (ex: histórico meteorológico)
• Prompts: Templates predefinidos para interações estruturadas

Sistema de Registro de Ferramentas

private registerTools() {
  // Register weather tools
  const weatherTools = this.weatherController.getToolDefinitions();
  weatherTools.forEach((tool) => {
    this.tools.set(tool.name, tool);
  });

  // Register history tools
  const historyTools = this.historyController.getToolDefinitions();
  historyTools.forEach(tool => {
    this.tools.set(tool.name, tool);
  });

  this.logger.debug(`[MCP] Registered ${this.tools.size} tools`);
}

Este método demonstra o padrão de registro dinâmico, onde:

• Controllers definem suas próprias ferramentas: Cada controller é responsável por declarar suas capacidades
• Registro centralizado: Todas as ferramentas são armazenadas em um Map para acesso eficiente
• Observabilidade: Logging detalhado para depuração e monitoramento

Handlers Especializados do Protocolo MCP

• 1. Handler de Listagem de Ferramentas:

this.server.setRequestHandler(ListToolsRequestSchema, async () => {
  const tools = Array.from(this.tools.values()).map(tool => ({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema,
  }));

  return { tools };
});

Este handler expõe metadados das ferramentas para o Claude Desktop, permitindo que ele entenda quais operações meteorológicas estão disponíveis.

• 2. Handler de Recursos:

this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "weather://current",
        mimeType: "application/json",
        name: "Current Weather",
        description: "Get current weather for any city"
      }
    ]
  };
});

Define recursos acessíveis via URI customizada, criando um "sistema de arquivos virtual" que o Claude pode explorar.

• 3. Handler de Execução de Ferramentas:

this.server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
  const { name, arguments: args } = request.params;

  const tool = this.tools.get(name);
  if(!tool) {
    throw new Error(`Tool ${name} not found`);
  }

  try {
    const result = await tool.handler(args);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  } catch (error) {
    this.logger.error(`[MCP] Error calling tool ${name}:`, error);
    throw error;
  }
});

Características Técnicas Avançadas:

• Validação de Ferramentas: Verifica existência antes da execução
• Tratamento de Erro Robusto: Captura e propaga erros de forma estruturada
• Serialização JSON: Padroniza respostas para garantir compatibilidade
• Observabilidade Completa: Logs detalhados para depuração

Ciclo de Vida e Gerenciamento de Estado

async start() {
  try {
    // Initialize infrastructure services
    await this.container.initialize();

    // Connect server to stdio
    const transport = new StdioServerTransport();
    await this.server.connect(transport);

    this.logger.info('Weather MCP Server started successfully');
  } catch (error) {
    this.logger.error('Failed to start MCP server:', error);
    throw error;
  }
}

Sequência de Inicialização:

1. Inicialização da Infraestrutura: Conexões de banco, cache e APIs externas
2. Configuração do Transporte: Estabelece canal de comunicação STDIO
3. Conexão do Servidor: Vincula o servidor ao transporte
4. Logging de Status: Confirma inicialização bem-sucedida

Esta arquitetura MCP representa uma evolução significativa em como construímos integrações de IA, proporcionando uma base sólida para aplicações que requerem acesso dinâmico a dados externos enquanto mantêm performance e confiabilidade de nível enterprise.

Excelência Arquitetural e Implementação

A arquitetura do projeto segue princípios de Clean Architecture, criando uma base robusta que separa a lógica de negócio das preocupações externas:

🏛️ Camada de Domínio (Regras de Negócio)
├── entities/           # Modelos de dados meteorológicos
└── repositories/       # Definições de contratos

🔧 Camada de Aplicação (Casos de Uso)
└── usecases/          # Operações de negócio
    ├── GetCurrentWeatherUseCase.ts
    ├── GetWeatherForecastUseCase.ts
    ├── GetWeatherHistoryUseCase.ts
    └── GetCacheStatisticsUseCase.ts

🏗️ Camada de Infraestrutura (Preocupações Externas)
├── repositories/      # Implementações de acesso a dados
│   ├── OpenWeatherMapApiRepository.ts
│   ├── PostgreSQLWeatherRepository.ts
│   └── RedisCacheRepository.ts
├── logger/           # Infraestrutura de logging
└── di/              # Injeção de dependências

🎮 Camada de Apresentação (Interface do Usuário)
├── controllers/      # Manipulação de requisições
└── servers/         # Implementação do servidor MCP

Integração da Stack Tecnológica:

• TypeScript: Type safety e recursos modernos do JavaScript
• Redis: Cache ultrarrápido com 95% de taxa de acerto
• PostgreSQL: Persistência confiável de dados para histórico meteorológico
• Docker: Deployment e desenvolvimento containerizados
• OpenWeatherMap API: Fonte abrangente de dados meteorológicos

Revolução de Performance Através de Cache Inteligente

Uma das conquistas mais impressionantes do projeto é sua estratégia de cache, que oferece melhorias notáveis de performance:

Métrica                | Com Cache Redis | Sem Cache | Melhoria
----------------------- | ---------------- | --------- | --------
Tempo de Resposta       | 23ms             | 315ms     | 13.6x mais rápido
Taxa de Acerto do Cache | 95%              | 0%       | Economia massiva
Chamadas de API         | 5 (por 50 requisições) | 50      | 90% de redução

Recursos de Cache Inteligente:

• TTL Diferenciado: 10 minutos para clima atual, 1 hora para previsões
• Geração Inteligente de Chaves: Nomes de cidades normalizados previnem duplicatas no cache
• Fallback Gracioso: Sistema continua funcionando mesmo se o Redis falhar
• Estatísticas Automáticas: Monitoramento em tempo real da performance do cache

Integração com Claude Desktop Simplificada

O projeto fornece instruções claras, passo a passo, para integração com o Claude Desktop:
Exemplo de Configuração:

{
  "mcpServers": {
    "weather-mcp": {
      "command": "node",
      "args": ["/caminho/para/weather-mcp-server/dist/mcp-entry.js"],
      "env": {
        "WEATHER_API_KEY": "sua_chave_openweathermap",
        "DATABASE_URL": "postgresql://mcp_user:mcp_pass@localhost:5432/weather_mcp",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Ferramentas MCP Disponíveis:

• get_current_weather: Clima em tempo real para qualquer cidade
• get_weather_forecast: Previsões detalhadas de 5 dias
• get_weather_history: Consultar dados meteorológicos históricos
• get_cache_statistics: Monitorar performance do sistema

Contribuindo para o Futuro da Integração de IA

Este projeto representa mais do que apenas um serviço meteorológico—é um blueprint para criar servidores MCP production-ready que expandem as capacidades da IA de formas significativas.

Por Que Você Deveria Explorar Este Projeto:

• Aprender Clean Architecture: Veja princípios SOLID aplicados em um projeto TypeScript do mundo real
• Dominar Estratégias de Cache: Entenda como implementar cache Redis de alta performance
• Explorar Desenvolvimento MCP: Ganhe experiência prática com o Model Context Protocol
• Estudar Melhores Práticas de CI/CD: Aprenda com um pipeline de deploy automatizado completo
• Contribuir para a Inovação: Ajude a melhorar e expandir esta implementação MCP fundamental

Começando e Contribuindo

O projeto recebe contribuições de desenvolvedores de todos os níveis de habilidade. Se você está interessado em:

• Adicionar novos provedores de dados meteorológicos
• Implementar estratégias adicionais de cache
• Melhorar o pipeline CI/CD
• Aprimorar a documentação
• Criar novas ferramentas MCP

Suas contribuições podem ajudar a moldar o futuro da integração IA-dados.

Início Rápido:

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

# Instalar dependências
npm install

# Iniciar ambiente de desenvolvimento
npm run docker:up (docker-compose up -d)
npm run build
npm run start

Recursos Adicionais

Para aprofundar seu entendimento das tecnologias e padrões usados neste projeto:

• Documentação do Model Context Protocol
• Guia de Clean Architecture em TypeScript
• Melhores Práticas de Cache Redis
• Princípios SOLID Explicados
• Docker Compose: Ambiente de desenvolvimento para aplicações de grande porte

Junte-se à Revolução MCP! 🚀

O projeto Weather MCP Server representa um passo significativo à frente na integração IA-dados. Ao combinar Clean Architecture, cache inteligente e práticas production-ready, ele demonstra como criar extensões de IA que são tanto poderosas quanto mantíveis.

⭐ Dê uma Estrela no Repositório: github.com/glaucia86/weather-mcp-server
🍴 Fork e Contribua: Ajude a melhorar esta implementação MCP fundamental
📖 Aprenda e Aplique: Use este projeto como blueprint para seus próprios servidores MCP

Seja você criando seu primeiro servidor MCP ou procurando aprimorar suas integrações de IA existentes, este projeto oferece insights valiosos e padrões práticos que você pode aplicar imediatamente. O futuro do desenvolvimento de IA está nessas integrações transparentes entre modelos de linguagem e dados do mundo real—e este Weather MCP Server mostra exatamente como construí-las da forma correta.

Pronto para transformar o Claude Desktop na sua estação meteorológica pessoal? Comece a explorar o código hoje mesmo! 🌤️🤖