Shop MCP Server

Servidor MCP local para el análisis de la base de datos SQLite de una tienda en línea. El agente de IA invoca la herramienta MCP, el servidor convierte la consulta en SQL SELECT seguro, lee directamente shop.db y devuelve un resultado estructurado.

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

Características

• conexión directa a SQLite sin HTTP ni servidor de base de datos independiente;

• transporte MCP stdio;

• detección de query_shop e inspect_database mediante tools/list;

• ocho ejemplos de tareas en la descripción y en el JSON Schema de la herramienta;

• texto plano, intent JSON o SELECT seguro preparado;

• exclusión de los pedidos cancelled de todo el análisis;

• paginación y limitación del resultado;

• protección de solo lectura en varios niveles.

Related MCP server: Shop Analytics MCP Server

Instalación

Se requiere Python 3.11 o superior.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

La base de datos preparada ya se encuentra en data/shop.db. Contiene 150 clientes, el campo customers.country está relleno en todos los clientes y 45 clientes pertenecen a Germany.

Re-preparación de la base de datos

La base de datos original no se modifica. El comando crea una nueva copia de trabajo y añade country TEXT NOT NULL con valores sintéticos reproducibles:

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

La distribución depende únicamente de customers.id, por lo que la re-preparación produce los mismos valores. Los países son datos de prueba y no describen la ubicación real de los clientes.

Configuración de la ruta

La ruta se determina en el siguiente orden:

1. SHOP_DB_PATH;

2. archivo JSON de SHOP_MCP_CONFIG o config/shop_mcp.json;

3. data/shop.db relativo al directorio de trabajo.

Un ejemplo de variable de entorno se encuentra en .env.example, y la configuración del cliente MCP, en config/mcp.example.json. Reemplace /absolute/path/to/MCPDeveloper por la ruta absoluta al proyecto.

Ejecución

Normalmente, el servidor lo inicia el cliente MCP desde su configuración. Para iniciar el proceso manualmente:

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout está reservado para MCP JSON-RPC. La diagnosis no se envía al flujo del protocolo.

Herramientas

inspect_database

Argumentos:

{"action": "list_tables"}

o:

{"action": "describe_table", "table": "customers"}

query_shop

Argumentos:

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

Ejemplos declarados mediante tools/list:

1. ¿Qué tablas hay en la base de datos y qué campos tienen?

2. ¿Cuántos clientes hay de Alemania?

3. ¿En qué país hay más clientes?

4. ¿Qué cliente gastó más? Devuelve el nombre, el email y el importe total.

5. Muestra el top-5 de productos por cantidad vendida e ingresos.

6. Muestra el top-3 de categorías por ingresos.

7. ¿Qué ingresos hubo en 2025?

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

Se puede pasar un intent estructurado:

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

O una consulta preparada:

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

Reglas de negocio

• orders.status = 'cancelled' no participa en las métricas.

• Los gastos de los clientes y los ingresos anuales se calculan según orders.total_amount.

• Los ingresos de productos y categorías se calculan como quantity * unit_price.

• El intervalo del año es semiabierto: desde el 1 de enero inclusive hasta el 1 de enero del año siguiente exclusivo.

• En la base de datos suministrada, todos los pedidos pertenecen a 2026, por lo que los ingresos de 2025 son 0.

Seguridad

El servidor abre SQLite mediante mode=ro, activa query_only, establece el authorizer de SQLite, prohíbe múltiples sentencias, DML, DDL, ATTACH, PRAGMA que modifiquen, la carga de extensiones y limita el tiempo de ejecución.

Cualquier intento de ejecutar una operación distinta de SELECT devuelve una respuesta exacta:

Не доступный вариант запроса

Los errores internos de SQLite, el stack trace y las rutas locales no se devuelven al cliente.

Verificación

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

Las pruebas incluyen la ejecución real del servidor MCP como subprocess, la conexión de ClientSession mediante stdio, tools/list, la invocación de ambas herramientas, escenarios analíticos e intentos de modificación de la base de datos.

La especificación completa aprobada se encuentra en docs/specification.md.