SQLite Shop MCP Server 🛍️

Servidor seguro y de alto rendimiento MCP (Model Context Protocol) en Python para conectar agentes de IA (Claude Desktop, Cursor, Antigravity, Gemini CLI) a la base de datos relacional de una tienda en línea (shop.db).

El servidor funciona localmente a través de la entrada/salida estándar (stdio), implementa protección de doble nivel contra modificaciones (Read-Only estricto), admite paginación automática, manejo de errores claro para la autocorrección de los agentes y cuenta con un 100% de cobertura de pruebas.

🌟 Características clave

1. Seguridad en varios niveles (Strict Read-Only):

   • Nivel físico (SQLite Engine): la base se abre mediante el URI file:shop.db?mode=ro. Cualquier intento de escritura se bloquea físicamente por la biblioteca C de SQLite (OperationalError: attempt to write a readonly database).

   • Nivel léxico (AST & Token Validator): las consultas se analizan antes de pasarlas a la base. Solo se permiten SELECT, WITH (CTE) y EXPLAIN. Cualquier operación destructiva (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, PRAGMA writable) y las cadenas de consultas con punto y coma se rechazan inmediatamente.

2. Diseño inteligente de herramientas (4 Tools):

   • get_database_schema: catálogo completo de todas las tablas, tipos, claves primarias/externas, número de filas y sugerencias temáticas.

   • describe_table: esquema detallado de una tabla específica.

   • get_sample_data: vista previa de los registros de una tabla sin escribir SQL.

   • execute_query: ejecución segura de SQL arbitrario con paginación automática (page, page_size), protección contra desbordamiento de contexto (hasta 1000 filas) y medición del tiempo de ejecución.

3. Manejo de errores amigable (Self-Correction):

   • No se exponen stacktraces de Python «crudos» hacia el exterior.

   • Cuando se produce un error al acceder a una columna inexistente, el servidor sugiere la lista de columnas disponibles en la tabla, lo que permite al modelo autocorregirse al instante.

4. Portabilidad:

   • No hay rutas absolutas hardcodeadas. La ruta se determina automáticamente con respecto al proyecto o mediante la variable de entorno SHOP_DB_PATH.

5. Pruebas y Docker:

   • 51 prueba automática pytest (seguridad, base de datos, integración, las 8 tareas de la especificación técnica).

   • Dockerfile y docker-compose.yml listos.

Related MCP server: Read-Only SQLite Shop Database MCP Server

🏗️ Arquitectura

[ AI Agent: Claude / Cursor / Antigravity ]
                   │  (stdio JSON-RPC)
                   ▼
           [ server.py ] (MCPServer stdio transport)
                   │
     ┌─────────────┴─────────────┐
     ▼                           ▼
[ src/security.py ]       [ src/db.py ]
(Валидация SQL,           (Подключение в mode=ro,
 защита от инъекций)       пагинация, сбор метрик)
                                 │
                                 ▼
                       [ shop.db (mode=ro) ]

Esquema de la base de datos shop.db

customers (150 строк)
    │
    └──< orders (750 строк)
             │
             └──< order_items (1900 строк) >── products (50 строк)

🚀 Inicio rápido

1. Instalación de dependencias (Install)

Se requiere Python 3.10+:

# Клонируйте репозиторий или перейдите в папку проекта
cd HW_MCP

# Установите зависимости
pip install -r requirements.txt

2. Configuración (Configure)

Por defecto, el servidor busca el archivo shop.db en la raíz del proyecto. Si es necesario, la ruta se puede redefinir mediante la variable de entorno:

# Windows (PowerShell)
$env:SHOP_DB_PATH = "C:\path\to\shop.db"

# Linux / macOS
export SHOP_DB_PATH="/path/to/shop.db"

3. Ejecución del servidor (Run)

El servidor se ejecuta en modo stdio:

python server.py

🤖 Conexión a agentes de IA (Connect to Agent)

Claude Desktop

Agregue la configuración al archivo de ajustes de Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": [
        "C:\\Users\\user\\OneDrive\\BackToTheFuture\\HW_MCP\\server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Cursor

En Cursor, vaya a Settings > Features > MCP > Add New MCP Server:

• Name: sqlite-shop

• Type: command

• Command: python C:\Users\user\OneDrive\BackToTheFuture\HW_MCP\server.py

O cree el archivo .cursor/mcp.json en la raíz del espacio de trabajo del proyecto:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

Antigravity / Gemini CLI

Agregue la sección en mcp_config.json:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

🛠️ Descripción de las herramientas (MCP Tools)

1. get_database_schema

Devuelve la estructura completa de todas las tablas, los tipos de datos de las columnas, las claves primarias y externas, el número de filas y notas explicativas sobre los datos.

2. describe_table(table_name: str)

Devuelve el esquema detallado de las columnas y restricciones de la tabla seleccionada (customers, products, orders, order_items).

3. get_sample_data(table_name: str, limit: int = 10)

Devuelve muestras de filas de la tabla para un análisis preliminar del formato de los datos.

4. execute_query(query: str, page: int = 1, page_size: int = 50)

Ejecuta una consulta SQL de lectura segura.

• Parámetros:

  • query (string, obligatorio): consulta SQL (SELECT, WITH ... SELECT, EXPLAIN).

  • page (int, por defecto: 1): número de página.

  • page_size (int, por defecto: 50, máx: 1000): número de filas por página.

• Formato de respuesta:

  {
    "rows": [
      { "id": 1, "first_name": "Арина", "email": "..." }
    ],
    "page": 1,
    "page_size": 50,
    "total_rows_in_page": 50,
    "has_more": true,
    "execution_time_ms": 1.24
  }

📊 Solución de las 8 tareas de control de la especificación técnica

Todas las consultas se han verificado con datos reales de shop.db:

Verificación de seguridad (Safety Requirement)

Consulta del agente:

Eliminar todos los pedidos cancelados.

Respuesta del servidor MCP:

{
  "error": true,
  "error_type": "PermissionDenied",
  "message": "PermissionDenied: Modifying or destructive operations are not permitted (read-only server). Statement starts with 'DELETE'."
}

La base de datos permanece completamente intacta.

🧪 Ejecución de las pruebas automáticas

En el proyecto se ha implementado un conjunto completo de pruebas basadas en pytest:

• tests/test_security.py — verificación del bloqueo de expresiones destructivas, inyecciones SQL y cadenas de consultas.

• tests/test_db.py — verificación del mode=ro físico, del esquema, de la paginación y de las sugerencias ante errores.

• tests/test_server.py — pruebas de integración de invocación de herramientas y validación de las 8 tareas de los deberes.

pytest tests/ -v

Resultado:

============================= 51 passed in 0.87s ==============================

🐳 Ejecución en Docker

Construcción y ejecución del contenedor:

# Сборка образа
docker build -t sqlite-shop-mcp .

# Запуск с монтированием базы
docker run -i --rm -v $(pwd)/shop.db:/app/shop.db:ro sqlite-shop-mcp

O mediante docker-compose:

docker-compose run --rm sqlite-shop-mcp

📁 Estructura del repositorio

HW_MCP/
├── .agent/                  # Интеграция с OpenSpec агентами
├── openspec/                # Спецификация требований (OpenSpec living specs & changes)
├── src/
│   ├── __init__.py
│   ├── config.py            # Разрешение путей и настроек SQLite URI
│   ├── security.py          # Валидатор SQL-запросов (Read-Only enforcement)
│   └── db.py                # Слой SQLite (mode=ro, пагинация, сбор схем)
├── tests/
│   ├── test_security.py     # Тесты безопасности SQL
│   ├── test_db.py           # Тесты слоя БД и пагинации
│   └── test_server.py       # Интеграционные тесты 8 аналитических задач
├── Dockerfile               # Контейнеризация сервиса
├── docker-compose.yml
├── mcp_config_example.json  # Примеры конфигов для Claude Desktop, Cursor, Antigravity
├── requirements.txt         # Зависимости Python
├── server.py                # Главная точка входа MCP-сервера
├── shop.db                  # База данных SQLite интернет-магазина
└── README.md                # Полная документация проекта

📜 Licencia

MIT License.