MCP POC

A proof-of-concept MCP server built with Node.js and TypeScript, compatible with Claude Desktop.

View on GitHub →

MCP POC - Model Context Protocol Server

Un servidor MCP (Model Context Protocol) desarrollado en Node.js/TypeScript con arquitectura modular que es compatible con Claude Desktop.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo abierto desarrollado por Anthropic que permite a los modelos de IA interactuar de forma segura con herramientas y fuentes de datos externas. Piensa en MCP como el "USB-C" de las integraciones de IA: un estándar único que conecta muchos servicios.

Componentes de MCP:

  • Servidores MCP: Actúan como puentes hacia APIs, bases de datos o código
  • Clientes MCP: Utilizan el protocolo para interactuar con los servidores
  • Hosts MCP: Sistemas que gestionan la comunicación (como Claude Desktop)

Características

Este servidor MCP incluye tres herramientas de ejemplo:

  1. greeting - Genera saludos personalizados en español (formal/informal)
  2. calculator - Realiza operaciones matemáticas básicas (suma, resta, multiplicación, división)
  3. get_current_datetime - Obtiene la fecha y hora actual en diferentes formatos

Instalación

🚀 Opción 1: Desde NPM (Recomendado)

# Instalar globalmente
npm install -g @sokardys/mcp-poc

# O usar npx (sin instalación)
npx sokardys-mcp-poc

💻 Opción 2: Desarrollo local

git clone <tu-repositorio>
cd mcp-poc
npm install
npm run build

3. Configurar Claude Desktop

Edita el archivo de configuración de Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade la configuración del servidor:

Para instalación NPM:

{
  "mcpServers": {
    "mcp-poc": {
      "command": "npx",
      "args": ["@sokardys/mcp-poc@latest"],
      "env": {
      }
    }
  }
}

Para desarrollo local:

{
  "mcpServers": {
    "mcp-poc": {
      "command": "node",
      "args": [
        "/ruta/completa/a/tu/proyecto/mcp-poc/build/index.js"
      ]
    }
  }
}

Importante: Para desarrollo local, cambia /ruta/completa/a/tu/proyecto/mcp-poc/ por la ruta real donde clonaste el proyecto.

4. Reiniciar Claude Desktop

Cierra y vuelve a abrir Claude Desktop para cargar la nueva configuración.

Uso

Una vez configurado, puedes usar las herramientas en Claude Desktop:

Ejemplos de uso:

  • Saludo: "Saluda a María de forma formal" → Usa greeting
  • Cálculo: "Calcula 15 × 8" → Usa calculator
  • Fecha: "¿Qué hora es?" → Usa get_current_datetime

Herramientas disponibles:

HerramientaDescripciónParámetros
greetingSaludos personalizadosname (string), formal (boolean)
calculatorOperaciones matemáticasoperation (add/subtract/multiply/divide), a (number), b (number)
get_current_datetimeFecha y hora actualformat (short/long/iso)

Scripts disponibles

# Compilar el proyecto
npm run build

# Modo desarrollo (recompilación automática)
npm run dev

# Ejecutar directamente (después de compilar)
npm start

# Inspeccionar el servidor MCP
npm run inspector

# Testing
npm test                # Ejecutar todos los tests
npm run test:watch      # Tests en modo watch
npm run test:ui         # Interfaz visual de tests
npm run test:coverage   # Tests con cobertura de código

Testing

Este proyecto incluye un suite completo de tests usando Vitest y mcpgod:

Ejecutar tests

# Tests básicos
npm test

# Tests en modo watch (reejecutar al cambiar código)
npm run test:watch

# Interfaz visual para tests
npm run test:ui

# Tests con reporte de cobertura
npm run test:coverage

Qué se testea

Los tests validan:

✅ Lista de herramientas - Verifica que todas las herramientas están disponibles ✅ Herramienta greeting - Formatos formal e informal, nombres personalizados ✅ Calculadora - Suma, resta, multiplicación, división con validación Zod ✅ Manejo de errores - División por cero, parámetros faltantes, McpError apropiados ✅ Fecha y hora - Diferentes formatos (corto, largo, ISO), zonas horarias ✅ Validación de entrada - Schemas Zod, tipos incorrectos, parámetros requeridos ✅ Arquitectura modular - Separación resolver/usecase, orquestador central

Pruebas manuales con mcpgod

# Listar herramientas disponibles
npx mcpgod tools build/index.js

# Probar herramientas específicas
npx mcpgod tool build/index.js greeting name="Ana" formal=true
npx mcpgod tool build/index.js calculator operation="add" a=15 b=25
npx mcpgod tool build/index.js get_current_datetime format="long"

Recursos adicionales

Licencia

MIT - consulta el archivo LICENSE para más detalles.

¡Disfruta construyendo herramientas increíbles con MCP! 🚀

Related Servers