SQLite Shop MCP Server 🛍️

Безопасный, высокопроизводительный сервер MCP (Model Context Protocol) на Python для подключения AI-агентов (Claude Desktop, Cursor, Antigravity, Gemini CLI) к реляционной базе данных интернет-магазина (shop.db).

Сервер работает локально через стандартный ввод/вывод (stdio), реализует двухуровневую защиту от изменений (строгий Read-Only), поддерживает автопагинацию, понятную обработку ошибок для самоисправления агентов и сопровождается 100% покрытием тестами.

🌟 Ключевые возможности

1. Многоуровневая безопасность (Strict Read-Only):

   • Физический уровень (SQLite Engine): база открывается через URI file:shop.db?mode=ro. Любая попытка записи физически блокируется C-библиотекой SQLite (OperationalError: attempt to write a readonly database).

   • Лексический уровень (AST & Token Validator): запросы анализируются до передачи в базу. Разрешены только SELECT, WITH (CTE) и EXPLAIN. Любые деструктивные операции (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, PRAGMA writable) и цепочки запросов через точку с запятой немедленно отклоняются.

2. Умный дизайн инструментов (4 Tools):

   • get_database_schema: полный каталог всех таблиц, типов, первичных/внешних ключей, количества строк и предметных подсказок.

   • describe_table: подробная схема конкретной таблицы.

   • get_sample_data: предварительный просмотр записей таблицы без написания SQL.

   • execute_query: безопасное выполнение произвольного SQL с автоматической пагинацией (page, page_size), защитой от переполнения контекста (до 1000 строк) и замером времени выполнения.

3. Дружелюбная обработка ошибок (Self-Correction):

   • Никаких «сырых» питоновских стектрейсов наружу.

   • При ошибке обращения к несуществующей колонке сервер подсказывает список доступных колонок в таблице, позволяя модели мгновенно самоисправиться.

4. Портативность:

   • Никаких захардкоженных абсолютных путей. Путь определяется автоматически относительно проекта либо через переменную окружения SHOP_DB_PATH.

5. Тестирование и Docker:

   • 51 автотест pytest (безопасность, база данных, интеграция, все 8 задач из ТЗ).

   • Готовые Dockerfile и docker-compose.yml.

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

🏗️ Архитектура

[ 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) ]

Схема базы данных shop.db

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

🚀 Быстрый старт

1. Установка зависимостей (Install)

Требуется Python 3.10+:

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

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

2. Конфигурация (Configure)

По умолчанию сервер ищет файл shop.db в корне проекта. При необходимости путь можно переопределить через переменную окружения:

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

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

3. Запуск сервера (Run)

Сервер запускается в режиме stdio:

python server.py

🤖 Подключение к AI-агентам (Connect to Agent)

Claude Desktop

Добавьте конфигурацию в файл настроек 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

В Cursor перейдите в Settings > Features > MCP > Add New MCP Server:

• Name: sqlite-shop

• Type: command

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

Либо создайте в корне проектного воркспейса файл .cursor/mcp.json:

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

Antigravity / Gemini CLI

Добавьте секцию в mcp_config.json:

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

🛠️ Описание инструментов (MCP Tools)

1. get_database_schema

Возвращает полную структуру всех таблиц, типы данных колонок, первичные и внешние ключи, количество строк и пояснительные заметки к данным.

2. describe_table(table_name: str)

Возвращает детальную схему колонок и ограничений выбранной таблицы (customers, products, orders, order_items).

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

Возвращает образцы строк из таблицы для предварительного анализа формата данных.

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

Выполняет безопасный SQL-запрос на чтение.

• Параметры:

  • query (string, обязательный): SQL-запрос (SELECT, WITH ... SELECT, EXPLAIN).

  • page (int, по умолчанию: 1): номер страницы.

  • page_size (int, по умолчанию: 50, макс: 1000): количество строк на странице.

• Формат ответа:

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

📊 Решение 8 контрольных задач из ТЗ

Все запросы проверены на реальных данных shop.db:

Проверка безопасности (Safety Requirement)

Запрос агента:

Delete all cancelled orders.

Ответ MCP-сервера:

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

База данных остается в полной сохранности.

🧪 Запуск автоматических тестов

В проекте реализован полный набор тестов на базе pytest:

• tests/test_security.py — проверка блокировки деструктивных выражений, SQL-инъекций и цепочек запросов.

• tests/test_db.py — проверка физического mode=ro, схемы, пагинации и подсказок при ошибках.

• tests/test_server.py — интеграционные тесты вызова инструментов и валидация всех 8 задач ДЗ.

pytest tests/ -v

Результат:

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

🐳 Запуск в Docker

Сборка и запуск контейнера:

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

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

Или через docker-compose:

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

📁 Структура репозитория

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                # Полная документация проекта

📜 Лицензия

MIT License.