Skip to main content
Glama
README.md
# MCP Excel Académico

Servidor **MCP** (Model Context Protocol) en TypeScript que da a un asistente de IA tres herramientas para trabajar con planillas de cálculo locales: inspeccionarlas, limpiar filas incompletas y generar un resumen estadístico. Está pensado para docencia e investigación académica y funciona con opencode, Claude Desktop, Cursor o cualquier cliente MCP por stdio.

## 1. Descripción y problema académico

En trabajos de laboratorio, estadística o investigación clínica es habitual recibir un Excel con:

- celdas vacías que distorsionan promedios y conteos;
- hojas con decenas de columnas cuyo significado no está documentado;
- la necesidad de repetir a mano la misma limpieza y el mismo resumen para cada entrega.

Hacerlo manualmente es lento y difícil de reproducir: dos personas pueden obtener resultados distintos aplicando criterios diferentes. Este MCP convierte esas tres tareas en herramientas explícitas, con parámetros validados y resultados verificables, para que el asistente pueda ayudar sin editar el archivo "a ciegas". Los datos se procesan **localmente**, sin subirlos a ningún servicio externo.

El flujo recomendado es siempre: **inspeccionar → limpiar → resumir**.

## 2. Requisitos

- **Node.js 18 o superior** y `npm` (ver `node --version`).
- Un **cliente MCP**: [opencode](https://opencode.ai) (recomendado), Claude Desktop, Cursor o el MCP Inspector.
- Un archivo de datos local (en este repo, `datos_ejemplo.xlsx`).
- No hace falta tener Microsoft Excel instalado: la lectura y escritura se hacen con la librería `xlsx` (SheetJS).

Funciona en Windows, macOS y Linux. En Windows, si PowerShell bloquea `npm.ps1` por su política de scripts, usa `npm.cmd` en todos los comandos.

## 3. Instalación paso a paso

```bash
git clone https://github.com/Maurichilean3d/mcp-starter-kit.git mcp-excel-academico
cd mcp-excel-academico
npm install
npm run build
npm test
```

`npm test` compila el código y ejecuta la prueba de humo; debe terminar con `Prueba de humo superada.` y listar las siete herramientas (las cuatro de la plantilla más las tres de Excel).

Después:

1. Abre tu cliente MCP **en esa misma carpeta** (`opencode`).
2. El archivo `opencode.json` ya registra el servidor; reinicia el cliente si ya estaba abierto antes de compilar.
3. Para probar sin conexión, ejecuta `npm run inspect` y llama a las herramientas desde el Inspector.

Si quieres volver a generar el archivo de ejemplo original (esto **sobrescribe** `datos_ejemplo.xlsx`):

```bash
node scripts/crear-datos-ejemplo.mjs
```

## 4. Archivo de ejemplo

`datos_ejemplo.xlsx` contiene datos clínicos **ficticios** de laboratorio:

| Hoja | Contenido |
|---|---|
| `Laboratorio` | 20 registros, 13 columnas (identificador, fecha, género, edad, hemoglobina, hematocrito, leucocitos, plaquetas, glucosa, creatinina, sodio, potasio y diagnóstico). Tiene 7 celdas vacías repartidas en género, edad, plaquetas, glucosa, sodio y potasio. |
| `Referencias` | Rangos de referencia de los análisis. |

Al ejecutar las herramientas se añaden `Datos_Limpios` (13 filas sin celdas vacías) y `Resumen_Estadistico` (9 columnas numéricas).

## 5. Herramientas propias

| Herramienta | Qué hace | Escritura |
|---|---|---|
| `excel_inspeccionar` | Lee y describe la estructura de una hoja. | No (solo lectura) |
| `excel_limpiar_datos` | Elimina filas con celdas vacías, con filtro opcional, y guarda el resultado en `Datos_Limpios`. | Sí: exige `confirmar: true` |
| `excel_resumen_estadistico` | Calcula estadística descriptiva y la guarda en `Resumen_Estadistico`. | Sí: exige `confirmar: true` |

Las rutas se resuelven y validan antes de abrir el archivo; solo se aceptan extensiones `.xlsx`, `.xlsm` y `.xls`.

### 5.1. `excel_inspeccionar`

Devuelve: hojas del libro, hoja inspeccionada, columnas, total de filas, primeras 5 filas y cantidad de celdas vacías **por columna**. Úsala siempre antes de las otras dos.

**Parámetros**

- `archivo` (obligatorio): ruta al archivo Excel.
- `hoja` (opcional): nombre de la hoja; por defecto, la primera (`Laboratorio`).

**Ejemplo en lenguaje natural**

> *"Inspecciona datos_ejemplo.xlsx y dime qué columnas tienen datos incompletos."*

**Ejemplo de llamada**

```json
{
  "archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx"
}
```

**Resultado esperado (extracto)**

```json
{
  "hojas": ["Laboratorio", "Referencias"],
  "columnas": ["id_paciente", "fecha_muestra", "genero", "edad", "..."],
  "total_filas": 20,
  "celdas_vacias_por_columna": { "genero": 1, "edad": 1, "glucosa_mg_dL": 2 }
}
```

### 5.2. `excel_limpiar_datos`

Elimina **todas** las filas que tengan al menos una celda vacía. Opcionalmente filtra por una columna y un valor (comparación exacta, sin distinguir mayúsculas). Guarda el resultado en la hoja `Datos_Limpios` del **mismo archivo**, conservando la hoja original. Si la hoja destino ya existe, se sobrescribe.

**Parámetros**

- `archivo` (obligatorio): ruta al archivo Excel.
- `hoja` (opcional): hoja de origen; por defecto, la primera.
- `columna` y `valor` (opcionales, **deben ir juntos**): filtro a aplicar.
- `confirmar` (obligatorio): literal `true` para autorizar la escritura.

**Ejemplo en lenguaje natural**

> *"Limpia los datos incompletos de datos_ejemplo.xlsx y guárdalos en una hoja nueva; confirma la escritura."*

**Ejemplo de llamada**

```json
{
  "archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
  "confirmar": true
}
```

Para quedarse solo con las filas completas de un diagnóstico:

```json
{
  "archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
  "columna": "diagnostico",
  "valor": "Diabetes tipo 2",
  "confirmar": true
}
```

**Resultado esperado (extracto)**

```json
{
  "hoja_destino": "Datos_Limpios",
  "filas_originales": 20,
  "filas_eliminadas": 7,
  "filas_guardadas": 13,
  "filtro": null
}
```

### 5.3. `excel_resumen_estadistico`

Para cada columna cuyos valores no vacíos sean todos numéricos calcula: `conteo`, `promedio`, `desviacion_estandar`, `minimo` y `maximo`. La desviación es **muestral** (denominador `n - 1`) y los resultados se redondean a 4 decimales. Escribe una hoja `Resumen_Estadistico` con columnas `Columna`, `Conteo`, `Promedio`, `Desviacion_Estandar`, `Minimo` y `Maximo`.

**Parámetros**

- `archivo` (obligatorio): ruta al archivo Excel.
- `hoja` (opcional): hoja a analizar; por defecto, la primera. Para analizar los datos ya limpios, indica `"Datos_Limpios"`.
- `confirmar` (obligatorio): literal `true` para autorizar la escritura.

**Ejemplo en lenguaje natural**

> *"Genera el resumen estadístico de la hoja Datos_Limpios de datos_ejemplo.xlsx y confírmalo."*

**Ejemplo de llamada**

```json
{
  "archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
  "hoja": "Datos_Limpios",
  "confirmar": true
}
```

**Resultado esperado (extracto)**

```json
{
  "columnas_numericas": 9,
  "estadisticas": [
    {
      "columna": "hemoglobina_g_dL",
      "conteo": 13,
      "promedio": 13.05,
      "desviacion_estandar": 1.27,
      "minimo": 10.8,
      "maximo": 15
    }
  ]
}
```

> Los valores del extracto son ilustrativos; ejecuta la herramienta para obtener los cálculos reales sobre la hoja que elijas.

## 6. Responsabilidad, Seguridad y Límites conocidos

**Permisos y privacidad**

- El MCP solo accede a **archivos locales** cuya ruta proporciona el usuario; no abre conexiones de red ni envía datos a servicios externos.
- La validación de extensión admite actualmente `.xlsx`, `.xlsm` y `.xls`. **`.csv` forma parte del alcance previsto de la política de permisos, pero todavía no está implementado**: intentar usarlo devuelve un error controlado. No documents `.csv` como soportado hasta añadirlo al validador de `src/lib/excel.ts`.
- No se usan claves de API ni secretos en el código.
- Los datos de `datos_ejemplo.xlsx` son ficticios. Para datos reales de personas, anonimízalos y verifica que tienes autorización para procesarlos; este MCP no sustituye una revisión ética ni normativa.

**Confirmación y writing**

- `excel_limpiar_datos` y `excel_resumen_estadistico` declaran `destructiveHint: true` y exigen `confirmar: true`. Sin ese literal, devuelven un error y no tocan el archivo.
- Ambas escriben dentro del mismo libro y **sobrescriben** `Datos_Limpios` / `Resumen_Estadistico` si ya existen. No hay papelera, historial ni `undo`: haz una copia antes de ejecutarlas sobre un archivo importante.
- La limpieza **no elimina la hoja original**; solo añade una hoja nueva. Aun así, revisa el resultado antes de usarlo como fuente oficial.

**Límites conocidos**

- La primera fila se trata como encabezados; no se admiten tablas con encabezados en otra fila ni celdas combinadas complejas.
- Las filas totalmente vacías se ignoran; una fila se considera incompleta si **cualquier** columna está vacía (no hay umbral configurable).
- El filtro es de igualdad exacta (ignorando mayúsculas); no admite comodines, rangos ni expresiones regulares.
- No se evalúan fórmulas: se leen los valores guardados en caché por Excel.
- Una columna solo entra al resumen si todos sus valores no vacíos son numéricos o cadenas convertibles a número; las fechas y columnas mixtas se omiten.
- La desviación estándar es muestral; para población completa hay que ajustar el denominador.
- `hoja` selecciona una sola hoja por llamada; no se puede resumir el libro completo de una vez.
- Las extensiones `.xlsm` y `.xls` pasan el validador pero solo `.xlsx` se usa en las pruebas; las macros no se ejecutan ni se conservan de forma garantizada.
- No hay límite de tamaño de archivo ni bloqueos concurrentes: evita abrir el mismo libro en Excel mientras se escribe desde el MCP.

**Uso de IA generativa**

Este proyecto fue desarrollado con asistencia de **IA generativa** (opencode junto a un modelo de lenguaje) para redactar el código, las descripciones de las herramientas y esta documentación. El resultado fue compilado (`npm run build`), probado (`npm test`) y verificado manualmente ejecutando las tres herramientas sobre `datos_ejemplo.xlsx`. La IA es una herramienta de apoyo: las decisiones sobre qué datos limpiar, qué archivos autorizar y cómo interpretar los resultados son responsabilidad de quien usa el MCP.

## 7. Estructura relevante

```
src/index.ts                      Arranque; carga automática de src/tools/
src/tools/excel.ts                Las 3 herramientas de Excel
src/lib/excel.ts                  Validación de rutas, lectura/escritura y helpers
scripts/crear-datos-ejemplo.mjs   Generador del archivo de ejemplo
scripts/smoke-test.mjs            Prueba de humo del servidor
datos_ejemplo.xlsx                Libro de práctica
opencode.json                     Registro del MCP en opencode
docs/, AGENTS.md                  Guías y reglas de la plantilla original
```

## 8. Comandos útiles

| Comando | Qué hace |
|---|---|
| `npm install` | Instala dependencias (incluye `xlsx`). |
| `npm run build` | Compila TypeScript a `dist/`; obligatorio tras cambiar código. |
| `npm test` | Compila y verifica handshake, listado y ejecución de herramientas. |
| `npm run inspect` | Abre el MCP Inspector para probar las herramientas con interfaz visual. |
| `node scripts/crear-datos-ejemplo.mjs` | Recrea el Excel de ejemplo desde cero. |

## Licencia

MIT. Proyecto derivado de la plantilla `mcp-starter-kit`; conserva las herramientas de ejemplo `hora_actual`, `saludar`, `listar_aplicaciones` y `abrir_aplicacion`.