marianoGarmendia/mcp-calculator-server

🧮 MCP Calculator Server

Un servidor MCP (Model Context Protocol) de ejemplo que implementa funcionalidades de calculadora. Este proyecto demuestra cómo crear y configurar un servidor MCP funcional para que los modelos de IA puedan realizar operaciones matemáticas.

📖 ¿Qué es MCP?

MCP (Model Context Protocol) es un protocolo que permite a los modelos de IA acceder a herramientas y datos externos de manera segura y estructurada. Los servidores MCP actúan como intermediarios que proporcionan funcionalidades específicas a los modelos de IA.

🔄 Cómo funciona MCP

Tu servidor MCP Calculator funciona como un proceso de Node.js que:

1. Se ejecuta en segundo plano (no es un servidor web)
2. Comunica a través de stdin/stdout (entrada/salida estándar)
3. Procesa comandos JSON-RPC para realizar cálculos matemáticos
4. Devuelve resultados en formato JSON

🚀 Instalación y Configuración

Prerrequisitos

• Node.js (versión 16 o superior)
• npm o yarn
• TypeScript (instalado globalmente o como dependencia)

Instalación

1. Clona este repositorio:

git clone <url-del-repositorio>
cd calculator-server

2. Instala las dependencias:

npm install

🎯 Comandos de Uso

Opción 1: Inspector MCP (Recomendado para desarrollo)

npm run inspector

¿Qué hace?

• Compila automáticamente el código TypeScript
• Abre una interfaz interactiva en tu terminal
• Te permite probar todas las funciones de calculadora
• Muestra logs en tiempo real
• Ideal para desarrollo y debugging

Ejemplo de uso:

> add(5, 3)
Resultado: 8

> multiply(6, 7)
Resultado: 42

> chat("Hello")
Resultado: You said: Hello, respond with a greeting, Hi! How are you?

Opción 2: Build completo y ejecución separada

# 1. Compilar todo el proyecto
npm run build:full

# 2. Ejecutar el servidor (en una terminal)
npm run start:server

# 3. En otra terminal, ejecutar el cliente
npm run start:client

Opción 3: Cliente de prueba simple

npm run test:simple

¿Qué hace?

• Ejecuta automáticamente una secuencia de pruebas
• Muestra el proceso de comunicación MCP
• Perfecto para verificar que todo funciona

Opción 4: Cliente TypeScript

npm run test-client-typescript

📋 Comandos Disponibles

🧮 Funciones Disponibles

El servidor proporciona las siguientes funciones:

Operaciones matemáticas básicas:

• add(a, b) - Suma dos números
• subtract(a, b) - Resta dos números
• multiply(a, b) - Multiplica dos números
• divide(a, b) - Divide dos números

Herramientas adicionales:

• help() - Muestra información de ayuda
• chat(query) - Simula un chatbot simple

Recursos disponibles:

• greeting://{name} - Genera un saludo personalizado

🔧 Configuración para Clientes MCP Reales

Para Claude Desktop:

1. Abre la configuración de Claude Desktop
2. Busca la sección de MCP Servers
3. Agrega esta configuración:

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

Para otros clientes MCP:

Cada cliente tiene su propia configuración, pero el patrón es similar:

• command: node
• args: ["ruta/al/archivo/build/index.js"]

🔍 Flujo de Comunicación MCP

1. Inicialización (Handshake)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "clientInfo": {
      "name": "Mi Cliente",
      "version": "1.0.0"
    }
  }
}

2. Listar herramientas disponibles

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

3. Ejecutar una función

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "add",
    "arguments": {
      "a": 15,
      "b": 25
    }
  }
}

📁 Estructura del Proyecto

calculator-server/
├── src/                              # Código fuente TypeScript
│   └── index.ts                     # Servidor MCP principal
├── build/                           # Código compilado JavaScript
│   ├── index.js                     # Servidor compilado
│   └── client/                      # Cliente compilado
├── client/                          # Clientes de ejemplo
│   └── client_example_typescript.ts # Cliente TypeScript
├── package.json                     # Configuración del proyecto
├── tsconfig.json                    # Configuración TypeScript
├── build-script.js                  # Script de build automatizado
├── test-simple.js                   # Script de prueba simple
├── run-application.js               # Script de ejecución completa
└── README.MD                        # Este archivo

🛠️ Desarrollo y Debugging

Compilar el proyecto:

npm run build:full

Ejecutar en modo desarrollo:

npm run inspector

Ver logs del servidor:

npm run start:server

Probar comunicación MCP:

npm run test:simple

❓ Preguntas Frecuentes

¿Por qué no veo un servidor web?

MCP no usa HTTP. Es un protocolo de comunicación directa entre procesos a través de stdin/stdout.

¿Cómo sé si el servidor está funcionando?

Usa npm run inspector para ver la interfaz interactiva o npm run test:simple para ejecutar pruebas automáticas.

¿Puedo usar el servidor desde otro programa?

Sí, cualquier programa que pueda ejecutar Node.js y comunicarse por stdin/stdout.

¿Cómo agrego nuevas funciones matemáticas?

Edita el archivo src/index.ts y agrega nuevas funciones al servidor MCP usando server.tool().

¿Puedo desplegar este servidor en la nube?

El servidor actual usa transporte stdio, que es para uso local. Para desplegar en la nube necesitarías implementar un transporte HTTP/WebSocket.

🎯 Próximos Pasos

1. Prueba el inspector: npm run inspector
2. Ejecuta el cliente de prueba: npm run test:simple
3. Explora los ejemplos de clientes:
   • npm run example:simple - Cliente simple
   • npm run example:client - Cliente completo
   • npm run example:quick - Cliente de ejemplo (rápido)
   • npm run example:run - Cliente de ejemplo (con build automático)
4. Configura en tu cliente MCP preferido
5. ¡Disfruta de tu calculadora MCP!

📚 Ejemplos de Integración

Si quieres integrar tu servidor MCP en otras aplicaciones, consulta la carpeta examples/ que incluye:

• JavaScript Simple - Comunicación JSON-RPC básica
• JavaScript Completo - Cliente con clase MCPClient
• Python - Ejemplo de cliente en Python

Cada ejemplo muestra la secuencia completa de comunicación MCP y cómo llamar a las herramientas de calculadora.

📚 Recursos Adicionales

• Documentación oficial de MCP
• Especificación del protocolo MCP
• Ejemplos de servidores MCP
• SDK de MCP para Node.js

🤝 Contribución

Este es un proyecto de ejemplo y práctica. Las contribuciones son bienvenidas para mejorar la funcionalidad y documentación.

📄 Licencia

Este proyecto está bajo la Licencia MIT.

⚠️ Nota: Este es un proyecto de ejemplo y práctica. No está diseñado para uso en producción sin las modificaciones y mejoras apropiadas.

¡Tu servidor MCP Calculator está listo para usar! 🎉