Exemplo de Servidor MCP

Este projeto demonstra como construir um servidor MCP com integração a APIs externas e validação de dados.

Este repositório contém um exemplo de implementação de um servidor MCP (Model Context Protocol) em Node.js/TypeScript, que fornece duas ferramentas para obter informações meteorológicas usando a API do National Weather Service (NWS) dos EUA.

Funcionalidades

• get-alerts: Retorna alertas meteorológicos ativos para um estado (código de duas letras, ex: CA, NY).

• get-forecast: Retorna a previsão do tempo para coordenadas geográficas (latitude, longitude).

• Validação de entrada usando Zod.

• Integração com a API do NWS usando fetch (camada de infraestrutura).

• Comunicação via stdio usando o protocolo MCP (@modelcontextprotocol/sdk).

Arquitetura

O projeto segue uma arquitetura em camadas inspirada em padrões de Domain-Driven Design (DDD):

• Domain (src/domain): Definição de interfaces e tipos que representam as estruturas de dados (ex: AlertFeature, ForecastPeriod, AlertsResponse).

• Infrastructure (src/infrastructure): Implementação de serviços externos, como o NWSApiService, responsável por realizar as chamadas HTTP à API do NWS.

• Application (src/application): Contém a lógica de negócio no WeatherService, que processa e formata os dados vindos da infraestrutura.

• Interface (src/interface): Inclui controladores (WeatherToolsController) que registram as ferramentas no servidor MCP, definem schemas de validação e retornam os resultados.

• Entry Point (src/main.ts): Inicializa o McpServer, configura o transporte (StdioServerTransport), instancia serviços e controladores, e inicia escuta em stdio.

A estrutura de pastas é a seguinte:

Instalação

Uso

Após o build, você pode executar o servidor diretamente:

Ou, se registrado como binário (weather):

O servidor iniciará na saída padrão (stdio) e aguardará requisições MCP.

Consumir com clients IA (Claude Desktop)

Em Arquivo > Configurações > Desenvolvedor

Editar configuração

claude_desktop_config.json