Super Calculadora MCP

# 🧮 Super Calculadora MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)

**Servidor MCP (Model Context Protocol) con más de 30 herramientas matemáticas y estadísticas para LM Studio, Claude Desktop y cualquier cliente MCP.**

---

## 📖 Descripción

Este servidor MCP convierte a tu modelo de lenguaje en una **calculadora científica y estadística de alto rendimiento**. Proporciona herramientas para:

- Aritmética básica y avanzada  
- Trigonometría (radianes y grados)  
- Estadística descriptiva (media, mediana, moda, varianza, desviación, cuartiles, percentiles)  
- Combinatoria (permutaciones y combinaciones)  
- Operaciones con listas/vectores (suma, producto, mínimo, máximo, rango)

Todo ello con manejo robusto de errores, límites de seguridad y mensajes claros para el modelo.

---

## ✨ Características

- ✅ **30+ herramientas** listas para usar.
- ✅ **Modular y extensible**: agrega nuevas funciones en segundos.
- ✅ **Validaciones estrictas**: previene divisiones por cero, raíces negativas, etc.
- ✅ **Límites de seguridad**: evita abusos con listas de hasta 1000 elementos.
- ✅ **Mensajes de error en lenguaje natural**: el modelo entenderá qué falló y podrá pedir correcciones.
- ✅ **Código limpio y bien comentado**.
- ✅ **Compatible con cualquier cliente MCP**: LM Studio, Claude Desktop, Cursor, etc.

---

## 📋 Requisitos previos

- **Node.js** (versión 18 o superior)
- **npm** (incluido con Node.js)
- Un cliente MCP, por ejemplo:
  - [LM Studio](https://lmstudio.ai/) (recomendado)
  - [Claude Desktop](https://claude.ai/download)
  - Cualquier otro que soporte MCP

---

## ⚙️ Instalación

1. **Clona o descarga el repositorio**:

```bash
git clone https://github.com/tu-usuario/super-calculadora-mcp.git
cd super-calculadora-mcp

2. Instala las dependencias:

npm install

El único paquete necesario es @modelcontextprotocol/sdk.

3. (Opcional) Verifica que funciona:

node server.js

Si no ves errores y el proceso queda en espera, todo está bien. Presiona Ctrl + C para salir.

🔧 Configuración en LM Studio

1. Abre LM Studio y asegúrate de tener un modelo cargado (por ejemplo, qwen2.5-coder-7b-instruct).

2. En la interfaz, ve a la sección de "MCP Servers" o edita directamente el archivo de configuración (normalmente ~/.lmstudio/mcp-servers.json).

3. Agrega esta entrada (cambiando la ruta absoluta a tu server.js):

{
  "mcpServers": {
    "super-calculadora": {
      "command": "node",
      "args": [
        "C:/ruta/completa/a/super-calculadora-mcp/server.js"
      ]
    }
  }
}

Nota: Usa barras inclinadas (/) o doble barra invertida (\\) en Windows.

4. Reinicia LM Studio (o recarga los servidores MCP).

5. En la conversación, asegúrate de que el modo de herramientas esté en "Auto" (no "Ask") para que ejecute las herramientas automáticamente.

6. Aumenta el tamaño de contexto del modelo a al menos 8192 tokens para evitar errores de límite.

Related MCP server: calculator-mcp-server

🧪 Ejemplos de uso

Pregunta en lenguaje natural en el chat de LM Studio:

El modelo detectará automáticamente la herramienta adecuada y te devolverá el resultado formateado.

📚 Lista completa de herramientas

Aritmética básica

• sumar – a + b

• restar – a - b

• multiplicar – a * b

• dividir – a / b (con control de división por cero)

Aritmética avanzada

• potencia – a ^ b

• raiz_cuadrada – √a

• raiz_cubica – ∛a

• logaritmo – log base b de a (base 10 por defecto)

• log_natural – ln a

• exponencial – e^a

• factorial – n!

• modulo – a % b

• valor_absoluto – |a|

• redondear – a con n decimales

• piso – floor(a)

• techo – ceil(a)

Trigonometría

• seno, coseno, tangente (en radianes)

• arcoseno, arcocoseno, arcotangente (devuelven radianes)

• grados_a_radianes, radianes_a_grados

Estadística (trabajan con listas de números)

• media – media aritmética

• mediana – valor central

• moda – valor(s) más frecuente(s)

• varianza – poblacional o muestral (parámetro sample: true/false)

• desviacion_estandar – poblacional o muestral

• rango – máximo – mínimo

• cuartiles – Q1, Q2, Q3

• percentil – percentil p (0-100)

• suma_lista – sumatoria

• producto_lista – producto

• minimo, maximo – valores extremos

Combinatoria

• permutaciones – nPr

• combinaciones – nCr

🧩 Extensibilidad

Agregar una nueva herramienta es muy sencillo. Solo tienes que añadir un objeto a la constante toolDefinitions dentro de server.js con la siguiente estructura:

nuevaOperacion: {
  description: "Breve descripción de lo que hace (la usará el modelo para decidir)",
  schema: {
    type: "object",
    properties: {
      parametro1: { type: "number" },
      parametro2: { type: "string", enum: ["opcion1", "opcion2"] }
    },
    required: ["parametro1"]
  },
  handler: (args) => {
    // Lógica de cálculo
    return resultado;
  },
  format: (args, result) => {
    return `🧮 ${args.parametro1} -> ${result}`;
  }
}

Guarda, reinicia el servidor y el modelo detectará automáticamente la nueva herramienta.

⚠️ Limitaciones y consideraciones

• Tamaño máximo de lista: 1000 elementos (configurable en MAX_LIST_SIZE).

• Factorial: limitado a n ≤ 170 para evitar Infinity.

• Seguridad: no se ejecuta código arbitrario; todas las operaciones son matemáticas puras.

• Formato de argumentos: todos los números deben ser number; enteros para factorial y combinatoria.

• Contexto: asegura que el modelo tenga suficiente tamaño de contexto (mínimo 4096, recomendado 8192 o más).

🤝 Contribución

Si deseas mejorar este proyecto, ¡eres bienvenido!

1. Haz un fork del repositorio.

2. Crea una rama con tu nueva funcionalidad (git checkout -b feature/nueva-funcion).

3. Haz commit de tus cambios (git commit -m 'Agrega nueva función X').

4. Haz push a la rama (git push origin feature/nueva-funcion).

5. Abre un Pull Request.

📄 Licencia

Este proyecto está bajo la licencia MIT. Si lo usas, solo te pedimos que menciones la fuente original. 😊

📬 Contacto

Creado por [Tu nombre / usuario de GitHub] – si tienes dudas, sugerencias o ideas, abre un issue o contáctame.

¡A calcular se ha dicho! 🚀

---

## 📂 Archivos a subir a GitHub

Tu repositorio debe tener al menos:

super-calculadora-mcp/ ├── server.js (el código principal) ├── package.json (con las dependencias) ├── README.md (el que acabamos de crear) └── .gitignore (opcional, para ignorar node_modules)

**`.gitignore`** sugerido:

node_modules/ *.log .DS_Store

---

## 🔄 Próximos pasos

1. Crea un repositorio en GitHub (público o privado).
2. Sube todos los archivos.
3. Comparte el enlace con quien quieras.

¡Ya estás listo para el mundo open source! Si quieres que traduzca el README al inglés o añadir alguna sección más, me dices. 💪🔥