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.

Related MCP server: redshift-mcp-server

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

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:

openssl rand -hex 32

2. Probar que levanta

npm start
# MCP tablero-supermercado escuchando en puerto 3300

Desde otra terminal:

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

3. Dejarlo corriendo como servicio (systemd)

# /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

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.

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)