MCP-сервер shop-db

Read-only MCP-сервер (транспорт stdio), который даёт AI-агенту доступ к SQLite-базе интернет-магазина shop.db: клиенты, товары, заказы и позиции заказов.

Построен на официальном MCP Python SDK (v2).

Метаданные разработки

Проект полностью сгенерирован AI coding agent (Claude Code, модель Fable 5) по спецификации SPEC.md.

Related MCP server: db-mcp

Инструменты (tools)

Безопасность

Изменить базу через этот сервер невозможно. Три независимых уровня защиты:

1. Валидация запроса — всё, что не является одиночным SELECT/WITH (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, PRAGMA, ATTACH, несколько стейтментов подряд, запись, спрятанная за комментарием), отклоняется с понятным сообщением ещё до выполнения.

2. Read-only соединение — файл открывается через SQLite URI с mode=ro.

3. PRAGMA query_only = ON на каждом соединении.

Даже запись, прошедшая валидацию (например, WITH ... INSERT), упирается в read-only на уровне соединения.

Ошибки SQL возвращаются короткими понятными сообщениями с подсказками — без stack traces.

Установка

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

Через uv (рекомендуется — при первом запуске всё ставится автоматически):

uv sync

Или через pip:

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

Конфигурация

Сервер ищет базу в файле shop.db рядом с server.py — выданная в задании база включена в репозиторий. Чтобы использовать другой файл, задайте переменную окружения SHOP_DB_PATH:

export SHOP_DB_PATH=/path/to/shop.db

seed_db.py — вспомогательная утилита, генерирующая демо-базу с похожей схемой (нужна только для одноразовых данных; shop.db она не трогает, если явно не попросить):

python seed_db.py /tmp/demo.db

Запуск

Сервер общается по stdio — его запускает MCP-клиент, а не пользователь вручную. Проверить, что он стартует без ошибок:

uv run python server.py

(сервер будет ждать MCP-сообщения на stdin; выход — Ctrl+C)

Подключение к агенту

Claude Code

В репозитории лежит .mcp.json, поэтому из директории проекта сервер подхватывается автоматически. Зарегистрировать вручную:

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

Claude Desktop (или любой клиент с JSON-конфигом)

Добавьте в claude_desktop_config.json (см. examples/claude_desktop_config.example.json) — при установке через pip зависимости должны быть поставлены в тот интерпретатор, который указан в конфиге:

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

Или через uv (ручная установка не нужна):

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

Docker

docker build -t shop-db-mcp .

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

Примеры вопросов, на которые отвечает агент

• Show me all available tables and explain what information each table contains.

• How many customers are from Germany?

• Which country has the most customers?

• Who is the customer who spent the most money?

• What are the top 5 best-selling products?

• What are the top 3 product categories by revenue?

• How much revenue did we generate in 2025?

• Which customer placed the most orders?

Деструктивные запросы («Delete all cancelled orders») сервер отклоняет.

Примечание про выданные данные: в customers нет колонки страны (местоположение можно вывести только из телефонных кодов — все номера +7 — или доменов почты), а все заказы датированы февралём–августом 2026. Инструменты схемы дают агенту всё необходимое, чтобы это обнаружить и ответить честно.

Результаты проверки через реального агента

Все задачи спецификации прогнаны через реальных headless-агентов (claude -p "<вопрос>" --mcp-config .mcp.json, модель Sonnet), у которых были доступны только три MCP-инструмента сервера — без Bash и файлового доступа. Ответы сверялись с эталонами, посчитанными напрямую из SQLite. Итог: 9/9.

Наблюдение из транскриптов: агентам почти всегда хватало list_tables + одного агрегирующего SQL-запроса — описания таблиц в ответах инструментов (включая подсказку про отсутствие страны и формулу revenue) сработали как задумано.

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

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

• customers (150 строк) — id, first_name, last_name, email, phone, created_at

• products (50 строк) — id, name, category, price, stock_quantity, created_at

• orders (750 строк) — id, customer_id → customers, order_date, status (new/processing/shipped/completed/cancelled), total_amount

• order_items (1900 строк) — id, order_id → orders, product_id → products, quantity, unit_price

Тесты

uv run pytest

36 тестов покрывают все три инструмента, пагинацию, обработку ошибок, read-only гарантии (включая мульти-стейтменты и запись, замаскированную комментарием) и генератор демо-данных.

Структура проекта

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