# tablero-mcp

Servidor MCP (Model Context Protocol) que expone la información del supermercado
como herramientas de análisis para Claude o ChatGPT, en lugar de dar acceso SQL
directo. Corre sobre la RÉPLICA de solo lectura, nunca sobre el servidor productivo.

## Qué hace

En vez de que el modelo de IA escriba SQL libre contra la base (riesgoso y poco
confiable), este servidor expone **herramientas ya armadas y probadas**:

- `ventas_por_periodo` — tendencia de ventas por día/semana/mes
- `top_productos` — ranking de productos por facturación o unidades
- `comparar_periodos` — variación % entre dos rangos de fechas
- `historial_precios_producto` — cambios de precio de un producto
- `movimientos_stock` — kardex de un producto en un rango de fechas
- `stock_actual` — último stock registrado (todos los productos o uno puntual)
- `resumen_cliente` — frecuencia, gasto total y ticket promedio de un cliente
- `clientes_en_riesgo` — clientes habituales que dejaron de comprar
- `consulta_sql_personalizada` — SELECT libre como último recurso, con tope de filas

Cuando llegue el diccionario de datos real del sistema, ajustar los nombres de
tabla/columna en `src/config/schema.js` — es el único lugar que hay que tocar,
el resto del código no depende de nombres hardcodeados.

## 1. Instalación en el servidor (la réplica, no el productivo)

```bash
git clone <este-repo> tablero-mcp   # o copiar la carpeta por scp
cd tablero-mcp
npm install
cp .env.example .env
nano .env   # completar DB_HOST, DB_USER, DB_PASSWORD, DB_NAME y generar MCP_AUTH_TOKEN
```

Generar un token fuerte:

```bash
openssl rand -hex 32
```

## 2. Probar que levanta

```bash
npm start
# MCP tablero-supermercado escuchando en puerto 3300
```

Desde otra terminal:

```bash
curl http://localhost:3300/health
# {"status":"ok"}
```

## 3. Dejarlo corriendo como servicio (systemd)

```ini
# /etc/systemd/system/tablero-mcp.service
[Unit]
Description=Tablero MCP - Supermercado
After=network.target mysql.service

[Service]
WorkingDirectory=/opt/tablero-mcp
ExecStart=/usr/bin/node src/index.js
Restart=always
EnvironmentFile=/opt/tablero-mcp/.env
User=www-data

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now tablero-mcp
```

## 4. Exponerlo con HTTPS (recomendado: Nginx + Certbot)

El protocolo MCP viaja sobre HTTP; para producción hay que ponerlo detrás de un
proxy con TLS (Nginx + Let's Encrypt) y, si se puede, restringir por IP de origen
además del token.

```nginx
server {
    listen 443 ssl;
    server_name mcp.tu-dominio.com;

    location /mcp {
        proxy_pass http://127.0.0.1:3300;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
    }
}
```

## 5. Conectarlo a Claude / ChatGPT

- **Claude.ai / Claude Desktop**: Configuración → Conectores → Agregar conector
  personalizado. URL: `https://mcp.tu-dominio.com/mcp`. En el header de
  autenticación poner `Authorization: Bearer <MCP_AUTH_TOKEN>`.
- **ChatGPT** (con soporte de conectores MCP en su plan): mismo esquema, URL +
  bearer token.

## Seguridad — checklist antes de exponerlo a internet

- [ ] El usuario de MySQL (`DB_USER`) tiene `GRANT SELECT` explícito, tabla por
      tabla, no `ON *.*`
- [ ] Corre contra la réplica, verificado (`DB_HOST` NO es el servidor productivo)
- [ ] `MCP_AUTH_TOKEN` es largo y aleatorio, no un valor default
- [ ] HTTPS habilitado (no HTTP plano en producción)
- [ ] Firewall (UFW) restringido a los orígenes que realmente necesitan pegarle
- [ ] `consulta_sql_personalizada` — evaluar si conviene deshabilitarla al
      principio y habilitarla solo si hace falta (comentar su registro en
      `src/index.js` → `registerClientesTools`)