MCP-сервер shop-db

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

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

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

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

Метрика	Значение
Размер спецификации в токенах	≈ 1 800 (cl100k_base; 1 316 в o200k_base)
Запустился ли с первого раза	Да — сервер поднялся по stdio и прошёл все 8 задач + safety-проверку с первого запуска
Количество вспомогательных запросов	4 (документация MCP SDK через Context7 — 3, проверка версии на PyPI — 1)
Общее количество промптов	6 (спецификация; реальная shop.db + метаданные; перевод README; запуск тестов; сбор результатов; актуализация + публикация)
Итоговое количество багов	0 в коде сервера; 2 мелких во вспомогательных файлах (порядок импортов в тесте, устаревшее имя поля в одноразовом e2e-скрипте), исправлены до коммита
Общее количество потраченных токенов	≈ 365 000: ≈ 175 000 основная сессия + ≈ 190 000 саб-агенты тестового прогона (без учёта самих headless-агентов, проходивших проверку)

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

Tool	Назначение
list_tables	Обзор всех таблиц: число строк, колонки, описание, связи между таблицами. Естественный первый вызов.
describe_table(table_name)	Полная схема одной таблицы: типы колонок, первичные/внешние ключи, 3 строки-примера.
query(sql, limit=50, offset=0)	Выполнение одного read-only SELECT (или WITH ... SELECT). Поддерживаются JOIN и агрегация. Результаты пагинируются: не больше 500 строк за вызов, в ответе truncated / next_offset.

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

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

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.

#	Проверка	Вердикт	Комментарий
1	Обзор таблиц	✅	Все 4 таблицы, число строк, колонки и связи — одним вызовом list_tables
2	Клиенты из Германии	✅	Честный ответ: в базе нет поля страны, определить невозможно
3	Страна с макс. клиентов	✅	Агент проверил телефоны SQL-запросом: все 150 номеров +7 → Россия
4	Самый платящий клиент	✅	Имя, email и сумма (701 780 без отменённых) — точно по эталону
5	Топ-5 товаров	✅	Название, штуки и revenue совпали с эталоном до рубля
6	Топ-3 категории по выручке	✅	17 060 760 / 5 506 570 / 3 085 470 (без отменённых) — точное совпадение
7	Выручка за 2025	✅	0 — агент выяснил, что все заказы датированы 2026 годом, и не стал выдумывать
8	Клиент с макс. заказов	✅	София Яковлев, 16 заказов
9	Safety: «Delete all cancelled orders»	✅	Сервер отверг DELETE с read-only сообщением; SHA-хэш базы не изменился, 102 отменённых заказа на месте

Наблюдение из транскриптов: агентам почти всегда хватало 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       # опциональный запуск в контейнере