shop-db MCP Server

Un servidor de solo lectura Model Context Protocol que brinda a los agentes de IA acceso analítico a una base de datos SQLite de comercio electrónico (customers, orders, order_items, products) — sin ninguna capacidad de modificar datos.

Construido para Node.js v24.19+, ejecutando archivos fuente TypeScript directamente (sin paso de compilación) usando node:sqlite y node:test nativos.

Setup

npm install

El repositorio ya incluye un ./shop.db poblado en la raíz del proyecto — no se necesita ningún paso de siembra. Nada en npm start o npm test escribe en él: el servidor lo abre en modo solo lectura, y la suite de pruebas construye sus propias bases de datos desechables en tests/ a partir de tests/fixtures/seed.sql.

Related MCP server: shop-mcp

Run the server

npm start

El servidor se comunica a través de stdio (StdioServerTransport) — está pensado para ser lanzado por un cliente MCP (Claude Code, Claude Desktop, etc.), no para ejecutarse de forma interactiva.

Tests

npm test

Ejecuta node --test contra tests/, cubriendo casos límite de validación SQL (palabras clave de mutación, evasión por comentarios, inyección de múltiples sentencias, CTEs, EXPLAIN) y las tres herramientas MCP de extremo a extremo contra bases de datos de prueba aisladas construidas a partir de tests/fixtures/seed.sql. El ./shop.db confirmado nunca es leído ni escrito por la suite de pruebas.

Configuración de la ruta de la base de datos

Por defecto, el servidor lee ./shop.db (relativo al directorio de trabajo desde el que se lanza). Sobrescríbelo con la variable de entorno DB_PATH:

DB_PATH=/absolute/path/to/shop.db npm start

Herramientas

• list_tables — lista las 4 tablas con una breve descripción de cada una.

• describe_table — definiciones de columnas, tipos, claves primarias y hasta 3 filas de muestra, para una tabla (tableName) o todas las tablas (omítelo).

• read_query — ejecuta una consulta de solo lectura SELECT/WITH/EXPLAIN/PRAGMA (query, obligatorio) y devuelve hasta limit filas (opcional, por defecto 100, máximo 1000). Cualquier intento de mutación (INSERT, UPDATE, DELETE, DROP, ...) se rechaza con un error claro, incluso si está disfrazado con comentarios SQL o envuelto en un CTE.

Configuración del agente de IA

{
  "mcpServers": {
    "shop-db": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.ts"],
      "env": {
        "DB_PATH": "/absolute/path/to/shop.db"
      }
    }
  }
}

Documentación del proyecto

• AGENTS.md — instrucciones para agentes de codificación de IA que trabajan en este repositorio (también cargado como CLAUDE.md mediante enlace simbólico).

• CONTEXT.md — modelo de dominio y arquitectura de seguridad.