Shop Analytics MCP

Servidor MCP en TypeScript para el análisis seguro de la base de datos SQLite de una tienda en línea. Funciona solo a través de stdio y proporciona seis herramientas especializadas; no se acepta SQL arbitrario.

Requisitos

• Node.js 24.10+;

• npm;

• sqlite3 CLI solo para volver a aplicar la migración.

Related MCP server: mcp-analytics-server

Instalación y ejecución

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

SHOP_DB_PATH tiene prioridad. Si la variable no está definida, el servidor busca shop.db en el directorio de trabajo actual. La ruta a la base de datos no está incrustada en el código fuente.

Datos

En el repositorio se encuentra una shop.db ya migrada. Contiene los países de los clientes y los datos del año 2025. Los valores monetarios se interpretan como EUR y no se convierten.

Para aplicar la migración a la base de datos original una vez:

npm run migrate

El esquema original se encuentra en database/schema.sql, y la migración determinista en database/001-add-analytics-data.sql.

Conexión con el cliente

Las plantillas de configuración listas se encuentran en config/:

• claude-code.mcp.json;

• codex.mcp.json;

• cursor.mcp.json.

Reemplace /absolute/path/to/mcp-server en la plantilla elegida por la ruta a este proyecto. Todas las configuraciones ejecutan dist/src/index.js a través de stdio y pasan la ruta a shop.db mediante SHOP_DB_PATH.

Herramientas

Las métricas financieras y de productos, así como el número de pedidos, excluyen cancelled. Los importes se devuelven en campos con el sufijo Eur. Los rankings aceptan limit de 1 a 100; los períodos usan fechas YYYY-MM-DD.

Ejemplo de funcionamiento

A continuación se muestra cómo el cliente MCP llama a get_database_schema para describir las tablas y luego a get_customer_metrics para contar los clientes de Alemania.

Seguridad

• SQLite se abre con readOnly: true y PRAGMA query_only = ON.

• El autorizador de SQLite prohíbe la escritura, DDL, ATTACH, DETACH y transacciones.

• Todos los valores se vinculan como parámetros SQL.

• Las herramientas no aceptan SQL, por lo que el agente no puede enviar una sentencia destructiva.

• Los errores de validación no revelan SQL, rutas absolutas ni stack traces.

Pruebas

npm test

Las pruebas cubren las respuestas de referencia de las ocho preguntas de aceptación, la inyección SQL en el parámetro de país, la prohibición de DELETE, la inmutabilidad SHA-256 de la copia temporal de la base de datos y la interacción MCP a través de stdio.

Preguntas de aceptación

1. Muéstrame todas las tablas disponibles y explica qué información contiene cada tabla.

2. ¿Cuántos clientes son de Alemania?

3. ¿Qué país tiene más clientes?

4. ¿Quién es el cliente que gastó más dinero?

5. ¿Cuáles son los 5 productos más vendidos?

6. ¿Cuáles son las 3 principales categorías de productos por ingresos?

7. ¿Cuántos ingresos generamos en 2025?

8. ¿Qué cliente realizó más pedidos?