Shop Analytics MCP Server

Un servidor MCP de solo lectura, a través de stdio, que permite a un agente de IA responder preguntas analíticas sobre la base de datos SQLite de una tienda en línea (customers, products, orders, order_items), sin que pueda modificarla en ningún caso.

Consulta SPEC.md para conocer el fundamento completo del diseño (registro de decisiones, esquema, modelo de seguridad y estrategia de pruebas).

Requisitos

• Node.js >= 24.10.0 (necesario para setAuthorizer de node:sqlite, que se utiliza en la garantía de solo lectura que se indica más abajo). Compruébalo con node --version.

• Ninguna otra dependencia de ejecución aparte de las que instala npm ci.

Related MCP server: db-mcp

Instalar → configurar → ejecutar → conectar

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

• shop.db se incluye en este repositorio, listo para usar. Si alguna vez necesitas regenerarlo de forma determinista a partir del esquema, ejecuta npm run seed (consulta Base de datos más abajo).

• SHOP_DB_PATH es opcional; su valor por defecto es shop.db en el directorio de trabajo actual. No hay ninguna ruta absoluta codificada en el código fuente.

• El servidor habla MCP únicamente por stdio: no hay ningún servidor HTTP ni nada más que ejecutar.

Conectar un agente de IA

Los ejemplos de configuración para dos clientes están en config/:

• config/claude-code.mcp.json — cópialo en el .mcp.json de un proyecto, o ejecuta claude mcp add-json con su entrada shop-analytics. Completa antes las rutas absolutas de args/env.

• config/codex.mcp.toml — copia la tabla [mcp_servers.shop-analytics] en ~/.codex/config.toml (o en un .codex/config.toml del proyecto), o usa el comando codex mcp add que se indica en el comentario de cabecera del archivo.

Para probar el servidor manualmente sin ningún agente concreto, usa MCP Inspector, que es independiente de la herramienta o cliente:

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

Herramientas

El servidor expone exactamente 8 herramientas especializadas y de solo lectura: ninguna acepta ni ejecuta SQL arbitrario. Toda respuesta correcta tiene la forma { "data": [...], "meta": {...} }; todo error es un mensaje simple, seguro y legible por humanos (sin SQL, rutas de archivo ni trazas de pila), marcado con isError: true.

from/to se escriben como YYYY-MM-DD y definen un intervalo UTC semiabierto [from, to); from debe ser estrictamente anterior a to. Todas las métricas financieras y de recuento excluyen los pedidos con estado cancelled. Los contratos completos por herramienta (formas exactas de las respuestas, reglas de desempate) están en SPEC.md §4.

Seguridad

Tres capas independientes y de defensa en profundidad garantizan que la base de datos nunca se modifique, ni siquiera ante un prompt adversarial como «Elimina todos los pedidos cancelados»:

1. La conexión SQLite se abre con readOnly: true.

2. PRAGMA query_only = ON se establece inmediatamente después de abrir la conexión.

3. Un authorizer de SQLite deniega explícitamente toda acción de escritura/DDL (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, transacciones, ...).

Además, ninguna herramienta acepta SQL en bruto, nombres de tablas ni nombres de columnas: cada consulta es una sentencia preparada fija, y todas las entradas se validan con zod y se pasan como parámetro enlazado, nunca mediante interpolación de cadenas.

Base de datos

shop.db se genera a partir de database/schema.sql con un script de generación de datos determinista: volver a ejecutarlo produce datos idénticos byte a byte en cada ejecución (semilla PRNG fija, sin dependencia del reloj):

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

El script de generación también comprueba, en el momento de generar los datos, que el conjunto no tenga clasificaciones ambiguas (p. ej., un único país líder, un único mayor gastador) y que los ingresos de 2025 no sean cero — consulta SPEC.md §3.

Desarrollo

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

Este proyecto se construyó con TDD: para cada módulo se escribió primero una prueba que fallaba y luego la implementación, herramienta por herramienta. La suite de integración cubre los 8 escenarios de aceptación de extremo a extremo, entradas con forma de inyección SQL, combinaciones de parámetros inválidas, y comprueba que el hash SHA-256 del archivo de la base de datos no cambia tras cada ejecución.

Estructura del proyecto

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)