shop-mcp

Before output, need be certain about preserving placeholders GXP1-GXP11. We do.

Let's generate final answer now# shop-mcp — Read-Only SQLite MCP Server

Servidor MCP en Python que proporciona al agente de IA (por ejemplo, Pi) un acceso seguro de solo lectura a la base de datos SQLite shop.db a través de stdio.

El agente explora el esquema de la base de datos por sí mismo, escribe consultas SQL y resuelve tareas analíticas. El servidor no contiene respuestas prefabricadas: solo herramientas para explorar y ejecutar consultas de solo lectura.

AI Agent (Pi)
        │  stdio
        ▼
┌────────────────────┐
│     MCP Server     │   list_tables / describe_table / read_query
└─────────┬──────────┘
          ▼
   SQL validation            ← только один SELECT / WITH ... SELECT
          ▼
   read-only guard           ← connection authorizer
          ▼
   SQLite (mode=ro)          ← файл физически невозможно изменить

1. Requisitos

• Python 3.13+

• uv

• El archivo de base de datos shop.db (ya se encuentra en la raíz del proyecto)

Related MCP server: safe-sql-mcp

2. Instalación

uv sync

uv creará el entorno virtual e instalará las dependencias. No es necesario crear venv manualmente.

3. Configuración de la base de datos

La ruta de la base de datos no está fijada en el código y se configura mediante una variable de entorno.

Opción A — variable de entorno (ruta absoluta):

export SHOP_DB_PATH=/absolute/path/to/shop.db
export MAX_RESULT_ROWS=1000   # опционально, default 1000

Opción B — sin configuración (fallback): si SHOP_DB_PATH no está definida, el servidor utiliza shop.db de la raíz del proyecto.

También es posible copiar .env.example a .env y especificar allí los valores (el servidor lee .env de la raíz del proyecto; las variables de entorno tienen prioridad):

cp .env.example .env

4. Ejecutar MCP localmente

uv run python -m shop_mcp.server

El servidor funciona a través de stdio y espera el protocolo MCP en stdin/stdout. No es necesario ejecutarlo por separado; lo inicia el propio cliente (Pi). La ejecución manual anterior es útil únicamente para depuración.

Una configuración incorrecta (por ejemplo, si no existe el archivo de la base de datos) finaliza el proceso con un mensaje claro en stderr.

5. Conectar MCP a Pi

Pi conecta los servidores MCP mediante el paquete pi-mcp-adapter y lee la configuración de .mcp.json en la raíz del proyecto. Este archivo ya está incluido en el repositorio:

{
  "mcpServers": {
    "shop": {
      "command": "uv",
      "args": ["run", "python", "-m", "shop_mcp.server"],
      "cwd": "/Users/stalexsm/projects/shop-mcp"
    }
  }
}

En otra máquina, ajuste cwd a la ruta absoluta del directorio del proyecto (o sustitúyalo por env con la variable SHOP_DB_PATH):

{
  "mcpServers": {
    "shop": {
      "command": "uv",
      "args": ["run", "python", "-m", "shop_mcp.server"],
      "cwd": "/absolute/path/to/shop-mcp",
      "env": {
        "SHOP_DB_PATH": "/absolute/path/to/shop.db",
        "MAX_RESULT_ROWS": "1000"
      }
    }
  }
}

No se requiere ejecutar un servidor HTTP aparte ni mantener manualmente python server.py en la terminal: el propio Pi inicia el proceso por stdio (de forma perezosa, en el primer acceso a las herramientas).

Si el adaptador aún no está instalado:

pi install npm:pi-mcp-adapter

Después, reinicie Pi en el directorio del proyecto. Las herramientas del servidor aparecerán en el panel /mcp.

6. Herramientas disponibles

list_tables

Lista las tablas de la base de datos con una breve descripción y el número de filas. Punto de partida para explorar el esquema. No se requiere SQL.

describe_table

Estructura de una tabla: columnas (name, type, nullable, primary_key, default) y claves foráneas en formato orders.customer_id -> customers.id. Una tabla inexistente genera un error claro con la lista de tablas disponibles.

read_query

Ejecuta una consulta SQL de solo lectura (SELECT o WITH ... SELECT).

Parámetros:

• sql (obligatorio) — el texto de la consulta;

• max_rows (opcional) — límite de filas solicitado; el límite estricto del servidor MAX_RESULT_ROWS (1000 por defecto) no puede superarse.

Se admite la analítica habitual de SQLite: JOIN, LEFT JOIN, GROUP BY, HAVING, ORDER BY, LIMIT/OFFSET, COUNT/SUM/AVG/MIN/MAX, DISTINCT, CASE, CTE.

El resultado es un JSON estructurado:

{
  "columns": ["name", "revenue"],
  "rows": [["Ноутбук UltraBook 15", 6569270.0]],
  "row_count": 1,
  "truncated": false,
  "execution_time_ms": 0.716
}

truncated: true indica que, debido al límite, solo se ha devuelto una parte de las filas: refine la consulta (LIMIT, WHERE, agregación) y no considere los datos completos.

7. Modelo de seguridad

Tres niveles de protección independientes:

1. Validación SQL: se permite exactamente una única sentencia que comience por SELECT o WITH. Se prohíben INSERT, UPDATE, DELETE, REPLACE INTO, DROP, ALTER, CREATE, ATTACH, DETACH, VACUUM, REINDEX, PRAGMA y otras operaciones de modificación. Las consultas con varias sentencias (SELECT ...; DELETE ...) se rechazan por completo. El validador reconoce literales de cadena, comentarios e identificadores entrecomillados; por tanto, un 'DELETE' dentro de una cadena no se considera una infracción.

2. Autorizador de conexión: todo lo que no sea una lectura (SELECT, leer una tabla, invocar una función) se rechaza en la fase de preparación de la consulta.

3. mode=ro: el archivo SQLite se abre en modo de solo lectura; incluso si se eluden los dos primeros niveles, la escritura física es imposible.

Los errores se devuelven al agente de forma comprensible (Database query failed: no such column: foo), sin traceback, rutas del sistema de archivos ni detalles de implementación.

shop.db es la fuente de verdad de solo lectura: el servidor no modifica ni el contenido ni la estructura del archivo. Esto está confirmado por una prueba de integridad (checksum + contadores de filas antes/después de todos los intentos de operaciones destructivas).

8. Preguntas de ejemplo

Haga estas preguntas al agente de Pi: él mismo invocará list_tables, describe_table y read_query:

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

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

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

• ¿Cuáles son las 3 categorías de producto con mayores ingresos?

• ¿Cuántos ingresos generamos en 2025?

• ¿Qué cliente realizó más pedidos?

Referencia de lógica de negocio (el agente la deduce de las descripciones de las herramientas; el servidor no codifica respuestas):

• los ingresos por productos/categorías se calculan como SUM(order_items.quantity * order_items.unit_price);

• los pedidos con estado cancelled no se tienen en cuenta;

• los ingresos por año se calculan según orders.order_date; si no hay pedidos, la respuesta correcta es 0.

Pregunta sobre los países

¿Cuántos clientes son de Alemania? — no se puede responder con fiabilidad: la tabla customers no tiene un campo country (solo first_name, last_name, email, phone, created_at). El servidor proporciona al agente información fiable sobre el esquema, y el agente debe informar de que los datos requeridos no existen en la base de datos, en lugar de deducir el país a partir del correo o teléfono o de adivinarlo.

9. Pruebas

uv run pytest

Conjunto de pruebas (66):

• tests/test_database.py — conexión de solo lectura, descubrimiento del esquema, claves foráneas, cierre de conexiones;

• tests/test_security.py — todas las operaciones prohibidas (sección 24 de la especificación), multi-sentencia, prueba de integridad de la base de datos;

• tests/test_tools.py — pruebas de integración de las herramientas MCP mediante una sesión de cliente real (transporte in-memory), incluida la gestión de errores;

• tests/test_analytics.py — escenarios analíticos (sección 27) contrastados con una fuente SQLite independiente, límites de tamaño del resultado.

Las pruebas no modifican shop.db (la prueba de integridad compara el checksum del archivo).

10. Solución de problemas

Estructura del proyecto

shop-mcp/
├── README.md
├── pyproject.toml
├── uv.lock
├── .env.example
├── .gitignore
├── .mcp.json              # конфигурация MCP для Pi
├── shop.db                # read-only source of truth
├── scripts/
│   └── smoke_stdio.py     # ручной smoke-тест через реальный stdio
├── src/shop_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP-инструменты (stdio)
│   ├── database.py        # read-only слой доступа к SQLite
│   ├── security.py        # SQL validation + single-statement guard
│   ├── models.py          # структуры результатов
│   └── config.py          # SHOP_DB_PATH / MAX_RESULT_ROWS
└── tests/
    ├── test_database.py
    ├── test_security.py
    ├── test_tools.py
    └── test_analytics.py