MCP-сервер для SQLite-базы данных интернет-магазина (только для чтения)

Официальный Model Context Protocol (MCP)-сервер, обеспечивающий безопасный доступ только для чтения к SQLite-базе данных интернет-магазина (shop.db) для AI-агентов.

🌟 Ключевые особенности

• Стандартный транспорт stdio: Бесшовно работает с любым MCP-клиентом (Claude Desktop, Cursor, Gemini CLI, Antigravity и т. д.).

• Многоуровневая защита только для чтения:

  • Режим только для чтения через SQLite URI (?mode=ro).

  • Строгий PRAGMA query_only = ON; во время выполнения.

  • Предварительный SQL-парсер, отклоняющий все мутирующие DDL/DML-запросы (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE и т. д.).

  • Блокирует цепочки SQL-инъекций и выполнение нескольких операторов.

• Инструменты, оптимизированные для LLM: Понятные описания, надёжная обработка ошибок без сырых трассировок стека и автоматическая пагинация (limit/offset).

• Гибкое разрешение путей: Работает из коробки с относительными путями, переменной окружения DB_PATH или флагом CLI --db-path.

Related MCP server: node-sqlite-mcp

🗄️ Схема базы данных

База данных SQLite (shop.db) содержит следующие сущности:

customers
    │
    └──< orders
             │
             └──< order_items >── products

• customers: id, first_name, last_name, email, phone, created_at

• products: id, name, category, price, stock_quantity, created_at

• orders: id, customer_id, order_date, status (new, processing, shipped, completed, cancelled), total_amount

• order_items: id, order_id, product_id, quantity, unit_price

🛠️ Инструменты MCP

🚀 Начало работы

1. Установка

Создайте виртуальное окружение и установите необходимые зависимости:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Локальный запуск

Запустите MCP-сервер через стандартный ввод/вывод:

python server.py

Или укажите пользовательский путь к базе данных:

# Using CLI argument
python server.py --db-path /path/to/shop.db

# Or using Environment Variable
DB_PATH=/path/to/shop.db python server.py

3. Запуск тестов

Запустите тестовый набор для проверки функциональности инструментов и ограничений безопасности:

python -m unittest discover -s tests -v

🔌 Подключение к AI-агентам

Claude Desktop

Добавьте этот сервер в ваш claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows):

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

Cursor IDE

В Cursor Settings → Features → MCP:

• Тип: command

• Команда: /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Antigravity / Gemini CLI

Добавьте в файл конфигурации MCP:

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

🔒 Примеры безопасности и валидации

Если AI-агент или подсказка попытается выполнить деструктивную операцию, сервер немедленно корректно отклоняет запрос:

• Запрос: «Удалить все отменённые заказы.»

• Ответ сервера:

  {
    "error": "Operation rejected: Statement type 'DELETE' is not allowed. Only read-only queries (SELECT, WITH ... SELECT, EXPLAIN) are permitted."
  }

📊 Проверочные запросы

Сервер позволяет AI-агентам решать аналитические запросы, например:

1. Обнаружение таблиц: list_tables() и describe_table(table_name="customers")

2. Демография клиентов:

   SELECT count(*) FROM customers WHERE phone LIKE '+7%';

3. Клиент, потративший больше всего денег:

   SELECT c.first_name, c.last_name, c.email, SUM(o.total_amount) AS total_spent
   FROM customers c
   JOIN orders o ON c.id = o.customer_id
   WHERE o.status != 'cancelled'
   GROUP BY c.id
   ORDER BY total_spent DESC
   LIMIT 1;

4. Топ-5 самых продаваемых товаров:

   SELECT p.name, SUM(oi.quantity) AS units_sold, SUM(oi.quantity * oi.unit_price) AS revenue
   FROM products p
   JOIN order_items oi ON p.id = oi.product_id
   JOIN orders o ON oi.order_id = o.id
   WHERE o.status != 'cancelled'
   GROUP BY p.id
   ORDER BY units_sold DESC
   LIMIT 5;

5. Топ-3 категории товаров по выручке:

   SELECT p.category, SUM(oi.quantity * oi.unit_price) AS revenue
   FROM products p
   JOIN order_items oi ON p.id = oi.product_id
   JOIN orders o ON oi.order_id = o.id
   WHERE o.status != 'cancelled'
   GROUP BY p.category
   ORDER BY revenue DESC
   LIMIT 3;

6. Клиент с наибольшим количеством заказов:

   SELECT c.first_name, c.last_name, COUNT(o.id) AS order_count
   FROM customers c
   JOIN orders o ON c.id = o.customer_id
   GROUP BY c.id
   ORDER BY order_count DESC
   LIMIT 1;