MCP Server Sample

Ejemplo de Servidor MCP

Este proyecto demuestra cómo construir un servidor MCP con integración a APIs externas y validación de datos.

Este repositorio contiene un ejemplo de implementación de un servidor MCP (Model Context Protocol) en Node.js/TypeScript, que proporciona dos herramientas para obtener información meteorológica usando la API del National Weather Service (NWS) de EE. UU.

Funcionalidades

• get-alerts: Devuelve alertas meteorológicas activas para un estado (código de dos letras, ej: CA, NY).
• get-forecast: Devuelve el pronóstico del tiempo para coordenadas geográficas (latitud, longitud).
• Validación de entrada usando Zod.
• Integración con la API del NWS usando fetch (capa de infraestructura).
• Comunicación vía stdio usando el protocolo MCP (@modelcontextprotocol/sdk).

Arquitectura

El proyecto sigue una arquitectura en capas inspirada en patrones de Domain-Driven Design (DDD):

• Domain (src/domain): Definición de interfaces y tipos que representan las estructuras de datos (ej: AlertFeature, ForecastPeriod, AlertsResponse).

• Infrastructure (src/infrastructure): Implementación de servicios externos, como el NWSApiService, responsable de realizar las llamadas HTTP a la API del NWS.

• Application (src/application): Contiene la lógica de negocio en el WeatherService, que procesa y formatea los datos provenientes de la infraestructura.

• Interface (src/interface): Incluye controladores (WeatherToolsController) que registran las herramientas en el servidor MCP, definen esquemas de validación y devuelven los resultados.

• Entry Point (src/main.ts): Inicializa el McpServer, configura el transporte (StdioServerTransport), instancia servicios y controladores, e inicia la escucha en stdio.

La estructura de carpetas es la siguiente:

src/
├── domain/
│   └── models/           # Interfaces de domínio
├── infrastructure/
│   └── services/         # Implementações da API externa (NWS)
├── application/
│   └── services/         # Lógica de negócio e formatação de dados
├── interface/
│   └── controllers/      # Registro das ferramentas MCP e validação
└── main.ts               # Ponto de entrada do servidor
build/                     # Código JavaScript compilado

Instalación

git clone <REPOSITÓRIO_URL>
cd mcp-server-sample
npm install
npm run build

Uso

Después del build, puedes ejecutar el servidor directamente:

node build/main.js

O, si está registrado como binario (weather):

npm link
weather

El servidor se iniciará en la salida estándar (stdio) y esperará solicitudes MCP.

Consumir con clientes de IA (Claude Desktop)

En Archivo > Configuración > Desarrollador

Editar configuración

claude_desktop_config.json

{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": ["C:\\Fontes\\mcp-server-sample\\build\\main.js"]
        }
    }
}