Servidor MCP shop-db

Servidor de solo lectura MCP (transporte stdio), que da a un agente de IA acceso a la base de datos SQLite de una tienda online shop.db: clientes, productos, pedidos y posiciones de pedidos.

Construido sobre el MCP Python SDK oficial (v2).

Metadatos de desarrollo

El proyecto fue totalmente generado por un agente de codificación de IA (Claude Code, modelo Fable 5) según la especificación SPEC.md.

Related MCP server: db-mcp

Herramientas (tools)

Seguridad

Es imposible modificar la base de datos a través de este servidor. Tres niveles independientes de protección:

1. Validación de la consulta — todo lo que no sean un único SELECT/WITH (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, DEPTAG, ATTACH, varias sentencias seguidas, una escritura oculta tras un comentario) se rechaza con un mensaje claro antes de ejecutarse.

2. Conexión de solo lectura — el archivo se abre mediante una URI de SQLite con mode=ro.

3. PRAGMA query_only = ON en cada conexión.

Incluso una escritura que pase la validación (por ejemplo, WITH ... INSERT) choca con el modo solo lectura al nivel de la conexión.

Los errores de SQL se devuelven con mensaje cortos y claros inluyendo sugerencias, sin stack traces.

Istalación

Se requ¡ere Python 3.10+.

Mediante uv (recomeando — con la primera ejecución se istala todo autoomáticamente):

uv sync

O con pip:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuración

El servidor busca la base de dators en el fichero shop.db al lado de server.py — la base entregada en la tarea está incluida en el repotorio. Para usar orto fichero, defina la variable de entorno SHOP_DB_PATH:

export SHOP_DB_PATH=/path/to/shop.db

seed_db.py es una utiliad auxiliar que genera una base de demo con un esqueama simirar (solo necesaria para datos desechables; no toca shop.db a menos que se le pida exprésamente):

python seed_db.py /tmp/demo.db

Arranque

El servidor se comunicable por stdo — lo inicia el clente MCP, no elusuário manualmente. Para comprovar que aranca sin errores:

uv run python server.py

(El servidor esperá mensajes MCP en stdin; salida con Ctrl+C)

Conexión al agente

Claude Code

En el repoitorio está [. Mcp.json](. Mcp.json), por eso desde la carpda del proyecto el servidor se detecta autoomáticamente. Para regitrar manualmente:

claude mcp add shop-db -- uv run --directory /absolute/path/to/sqlite-mcp python server.py

Clude Desktop (o culquier o tro clente con JSON)

Agréguel a claude_desktop_config.json (ver examples/clud_dektop_config.example.json) — al instalar con pip, as dependenclase deben estar instaladas en el intérprete que se indica el config:

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/sqlite-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/sqlite-mcp/server.py"]
    }
  }
}

O con uv (no se necesita instalación manual):

{
  "mcpServers": {
    "shop-db": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/sqlite-mcp", "python", "server.py"]
    }
  }
}

Docer

docker build -t shop-db-mcp .

{
  "mcpServers": {
    "shop-db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shop-db-mcp"]
    }
  }
}

Ejemplos preguntas que responden agentes

• Mostrar as todas las tablas disponibles y explicaba qué información tiene contra cada.

• . mini escribe cómo los plistas de Alemania.

• estante *cual país clientes a tener mátex.

• mín cliente gastado mas.

• ¿Sebastes

• , *Cuales son los súdarios categorías? ...

• . Cañitos de ingreso hemos genrado en 2025?

• ¿Qué cliente ha rrazado más pedidos?

Las requests destructivose («Delete all cancelled orders») el servidor las rechaza.

Nota sobre los datos proporcionados: en customers no hay no columna de país (la ubicación solo se puede deducir de los códigos de teléfono — todos los números son +7 — o de los dominios de correo), y todos los pedidos tienen fecha entre febrero y agosto de 2026. Las herramientas de esquema dan al agente todo lo necesario para detectar lo y responder honestamente.

Resumen de las pruebas en un agente real

Todas las tareas de la especificación se probaron en agentes headless reales (claude -p "<script>" --mcp-config .mcp.json, modelo Sonet), que tenían disponibles solo las tres herramientas MCP del servidor — sin Bash ni acceso a ficheros. Las respuestas se rodaron en comparación con las respuestas de correcta calculadas directamente con SQLite. Resumen: 9/9.

Observación en transcritos: los agentes casi siempre necesitaban list_tables + una consulta SQL agregada — los descrip de las tablas en las respuesta de herramientas (including hint about priority país and receita formula) worked as diseño.

Esque de la base de datos

customers ──< orders ──< order_items >── products

• customers (150 filas) — id, first_name, last_name, email, phone, created_at

• products (50 filas) — id, name, category, price, stock_quantity, created_at

• orders (750 filas) — id, customer_id → customers, order_date, status (new/processing/shipped/completed/cancelled), total_amount

• order_items (1900 filas) — id, order_id → orders, product_id → products,quantity, unit_price

Pruebas

uv run pytest

36 tests cover all three tools, pagination, error handling, read-only guarantees (include multi-feature and hidden scanner) and the demo data generator.

Estructura del proyecto

server.py        # MCP-сервер (3 инструмента, read-only защита)
shop.db          # выданная в задании база данных
SPEC.md          # спецификация, по которой сгенерирован проект
seed_db.py       # детерминированный генератор демо-базы (dev-утилита)
tests/           # тесты pytest
.mcp.json        # конфиг проекта для Claude Code
examples/        # пример конфига для Claude Desktop
Dockerfile       # опциональный запуск в контейнере