Shop Database MCP Server

Un servidor local de solo lectura del Model Context Protocol para explorar y analizar el fixture educativo SQLite de tienda incluido. Expone exactamente tres herramientas: list_tables, describe_table y query_database.

El shop.db incluido contiene valores educativos sintéticos de países. Son datos deterministas ficticios, no atributos personales inferidos.

1. Instalación

Requisitos: Node.js 20 o más reciente, npm y una plataforma compatible con better-sqlite3 (o un conjunto de herramientas local de compilación de C/C++ si npm no puede obtener un binario nativo precompilado).

npm install

2. Configuración

No se requiere configuración cuando se utiliza el shop.db incluido. Para seleccionar otra base de datos compatible, defina una ruta absoluta o relativa:

export SHOP_DB_PATH=/path/to/shop.db

El servidor resuelve la base de datos predeterminada en relación con su propio módulo, no con el directorio de trabajo del que llama. Nunca creará una base de datos ausente. Consulte .env.example; los archivos de entorno no se cargan automáticamente.

3. Preparar o verificar el fixture

npm run prepare-db

Este comando de configuración explícito agrega o valida atómicamente el fixture determinista y sintético customers.country y su índice. Conserva los campos e IDs de clientes existentes y es idempotente. start, dev ni el runtime del servidor nunca lo invocan. El repositorio ya contiene la base de datos preparada, por lo que normalmente esto actúa como verificación.

4. Compilación

npm run typecheck
npm run build

5. Ejecución

npm run start

El proceso habla MCP a través de stdin/stdout y espera a un cliente. No imprime un banner de inicio; stdout está reservado exclusivamente para mensajes MCP. El modo de desarrollo está disponible como npm run dev.

6. Conexión

En configuration.example.json se proporciona una configuración genérica de MCP stdio:

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

Para Codex CLI, añada el servidor desde la línea de comandos:

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

O copie la plantilla de config/codex-config.example.toml en su configuración de Codex y reemplace los marcadores de posición:

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

Ejecute codex mcp list, inicie Codex y use /mcp para verificar que shop_database y las tres herramientas estén disponibles.

7. Pruebas

npm test

El conjunto cubre los límites de entrada, la tokenización y rechazo de SQL, la serialización, el descubrimiento de esquemas, todas las analíticas de aceptación, la paginación, los enlaces con nombre, el comportamiento del protocolo stdio y la inmutabilidad de la base de datos en la matriz de consultas destructivas.

Ejemplos de avisos

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 más dinero gastó?

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

6. ¿Cuáles son las 3 categorías de productos con más ingresos?

7. ¿Cuántos ingresos generamos en 2025?

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

Reglas de consulta y garantía de solo lectura

La base de datos se abre con readonly: true y fileMustExist: true y luego se coloca en modo SQLite de solo consulta. La política SQL solo permite una sentencia SELECT o un WITH ... SELECT no recursivo; se rechazan mutaciones, DDL, PRAGMA, adjuntos, mantenimiento, carga de extensiones, CTE recursivas y sentencias adicionales. Las declaraciones preparadas también deben identificarse como de solo lectura. Los valores del usuario solo se pasan mediante enlaces con nombre.

Cada página de resultados contiene como máximo 500 filas. Use un ORDER BY determinista y continúe con next_offset mientras que has_more sea verdadero. El controlador SQLite síncrono no puede interrumpir una consulta con alta carga de CPU dentro del proceso; v1 se apoya en las restricciones de consulta, la salida limitada y el tiempo de espera recomendado de 15 segundos del cliente MCP, más que en una fecha límite estricta de ejecución en el servidor.

Los ingresos, los gastos, las unidades vendidas y las ventas de productos/categorías excluyen los pedidos cancelados. Los recuentos de pedidos realizados incluyen todos los estados. Los ingresos de pedido completo y el gasto de clientes utilizan orders.total_amount; los ingresos históricos de productos/categorías utilizan order_items.quantity * order_items.unit_price. Las fechas no tienen zona horaria y los filtros por año natural emplean intervalos medio-abiertos. La base de datos no declara una moneda, por lo que los montos son unidades monetarias.

Solución de problemas

• DATABASE_UNAVAILABLE: verifique SHOP_DB_PATH, la existencia del archivo y el permiso de lectura. El servidor no crea bases de datos.

• DATABASE_SCHEMA_MISMATCH: use el fixture incluido o ejecute npm run prepare-db; una base de datos personalizada debe tener todas las tablas, columnas, claves ajenas (foreign keys) y requisitos previos del fixture necesarios.

• Si falla la instalación de la dependencia nativa: use una versión de Node.js con soporte e instale las herramientas de compilación de su plataforma y vuelva a ejecutar npm install.

• Errores de framing MCP o JSON: no agregue console.log ni otros registros en stdout al código de ejecución. Envíe los diagnósticos solo a stderr.

• Si una consulta devuelve SQL_ERROR: primero inspeccione las tablas, utilice alias únicos para los nombres de columna de resultado duplicados y verifique los nombres de los marcadores de posición y la sintaxis SQL.