---

```markdown
# 🧮 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**:

```bash
npm install
```

El único paquete necesario es `@modelcontextprotocol/sdk`.

3. **(Opcional) Verifica que funciona**:

```bash
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`):

```json
{
  "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.

---

## 🧪 Ejemplos de uso

Pregunta en lenguaje natural en el chat de LM Studio:

| Pregunta del usuario | Herramienta utilizada |
|----------------------|------------------------|
| *"Suma 45 y 32"* | `sumar` |
| *"Calcula la raíz cúbica de 27"* | `raiz_cubica` |
| *"¿Cuál es la media de [4, 8, 15, 16, 23, 42]?"* | `media` |
| *"Dame la moda de [1, 2, 2, 3, 4, 4, 4]"* | `moda` |
| *"Calcula el logaritmo natural de 100"* | `log_natural` |
| *"¿Cuántas combinaciones de 5 elementos tomados de 2?"* | `combinaciones` |
| *"Redondea 3.14159 a 2 decimales"* | `redondear` |
| *"Convierte 45 grados a radianes"* | `grados_a_radianes` |

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:

```javascript
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. 💪🔥