Shop SQLite MCP

{"type": "text"}# Shop SQLite MCP

Servidor MCP stdio local para el análisis seguro de una base de datos SQLite existente de una tienda en línea. El servidor lee dinámicamente el esquema desde sqlite_master y los PRAGMA de SQLite, por lo que no depende de nombres de columna conocidos de antemano.

Características

• list_tables — tablas y vistas;

• describe_table — columnas, PK, FK e índices;

• get_schema — grafo completo del esquema;

• run_select_query — un SELECT / WITH ... SELECT único y limitado;

• herramientas de análisis especializadas: count_customers_by_country, top_customers_by_spend, top_products_by_units, top_categories_by_revenue, revenue_in_year, top_customers_by_order_count;

• modo físico de solo lectura de SQLite, query_only y autorizador;

• bloqueo de DML, DDL, PRAGMA, ATTACH y de varias sentencias;

• paginación: limit 1–500 y offset.

Configuración

Un solo comando lo hace todo: elige la opción de instalación, instala las dependencias (o compila la imagen de Docker), encuentra la base de datos, verifica la lectura del esquema y escribe el mcp.json listo.

python3 install.py

El script preguntará por la opción de ejecución (.venv o Docker) y la ruta a la base de datos. Sin preguntas:

python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db

Se requiere Python 3.11+; para --mode docker, Docker instalado.

Por defecto, la base de datos se toma de data/shop.db. Si el archivo no existe, el script se detendrá con un error claro y no creará una base de datos vacía.

No es necesario ejecutarlo manualmente por separado: el servidor se inicia desde la configuración. Para depurar:

.venv/bin/python -m shop_mcp.print_schema

Conectar al agente

Después de install.py solo queda un paso. El archivo mcp.json ya contiene el comando de ejecución elegido y la ruta absoluta a la base de datos: no hay que editar nada.

Conéctelo al agente de una de las siguientes maneras:

• Cursor: abra esta carpeta como espacio de trabajo (hay una copia en .cursor/mcp.json) o importe el mcp.json raíz en la configuración de MCP;

• Claude Desktop / otro cliente: copie el contenido de mcp.json en la configuración de MCP.

Después de conectarse, haga las preguntas de ASSIGNMENT.md. La primera acción del agente es get_schema o una herramienta de análisis especializada. Si la herramienta devuelve SCHEMA_MISMATCH, use run_select_query.

La plantilla con placeholders es solo mcp.json.example. Las rutas absolutas solo están en la configuración del cliente, no en el código de Python.

Docker

No se necesitan comandos separados: python3 install.py --mode docker compila la imagen shop-sqlite-mcp:local, monta la base de datos en solo lectura y escribe en mcp.json la ejecución de docker run -i --rm.

La base de datos se monta como /data/shop.db:ro; no se usa la bandera -t porque MCP se comunica a través de stdin/stdout.

docker-compose.yml compila la misma imagen y es útil para verificar la compilación localmente; al agente entréguele mcp.json.

Pruebas

.venv/bin/pytest

Las pruebas usan una base de datos fixture temporal con nombres de tabla desconocidos para el servidor. Verifican la introspección en tiempo de ejecución, los límites de resultados, la ausencia de esquema fijo y el rechazo de SQL destructivo.

Para una verificación manual después de la conexión, haga las preguntas de ASSIGNMENT.md, incluyendo:

Eliminar todos los pedidos cancelados.

La respuesta de la herramienta debe contener WRITE_DENIED y la base de datos debe permanecer sin cambios.

Archivos del proyecto

• install.py — el único comando de instalación: dependencias/imagen, ruta de la base de datos, generación de configuración;

• mcp.json — configuración de conexión lista (comando + ruta de la base de datos);

• PROMPT.md — el prompt con el que el agente de codificación de IA creó el servidor;

• src/shop_mcp/ — MCP, introspección de esquema, guardia SQL, herramientas de análisis;

• tests/ — pruebas automáticas de seguridad, descubrimiento y análisis;

• Dockerfile / docker-compose.yml — MCP stdio en contenedor;

• NOTES.md — decisiones sobre ambigüedades de la tarea.