shop-mcp

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

Сервер работает с MCP через stdio, открывает базу данных в режиме только для чтения и предоставляет небольшой набор специализированных параметризованных инструментов, в описаниях которых зашиты правила предметной области (какие статусы заказов считаются выручкой, как определяется страна клиента, откуда приходят деньги). Универсального SQL-инструмента и инструмента записи здесь нет — поэтому разрушительный запрос вроде «Удалить все отменённые заказы» не может быть выполнен.

Код MCP-сервера в этом репозитории был создан ИИ-агентом для написания кода (Cursor) по условию домашнего задания, что сервер не должен быть написан вручную.

Требования

• Python 3.11 или новее

• SQLite-база shop.db (в коммите по пути database/shop.db)

• uv (рекомендуется) — запускает сервер в изолированном окружении проекта без какой-либо глобальной установки. Установите его командой brew install uv (macOS) или curl -LsSf https://astral.sh/uv/install.sh | sh.

Related MCP server: MCP SQLite RBAC Demo

Установка

C uv (рекомендуется) — вручную создавать venv или ставить pip не нужно: uv при первом запуске сам разрешает проект и его зависимости из pyproject.toml:

uv sync          # create / refresh the project's .venv from pyproject.toml

Без uv — создайте виртуальное окружение и установите пакет самостоятельно:

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e .

Это установит SDK mcp и пакет shop-mcp (который даёт точку входа python -m shop_mcp и консольный скрипт shop-mcp).

Настройка

Сервер открывает базу данных по пути database/shop.db относительно рабочей директории процесса (ProjectRoot). Переменные окружения не требуются.

При запуске через uv run --directory <project> (см. конфиги клиентов ниже) uv устанавливает рабочую директорию в корень проекта, поэтому закоммиченная база находится автоматически.

Если database/shop.db отсутствует, сервер завершает работу при запуске с понятной ошибкой конфигурации, в которой указана текущая рабочая директория (без стека ошибок и без тихого отката). Убедитесь, что в конфигурации вашего MCP-клиента параметр cwd указывает на корень репозитория.

Запуск

uv run python -m shop_mcp

или, если пакет установлен в активное виртуальное окружение:

python -m shop_mcp

или, что эквивалентно:

shop-mcp

Сервер читает JSON-RPC из stdin и пишет в stdout. Обычно вы не запускаете его напрямую — его запускает ваш ИИ-агент (см. ниже).

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

Метаданные Готовые к использованию конфигурации MCP-клиентов находятся в examples/mcp/ — для запуска достаточно установки самого uv:

Каждая конфигурация выглядит следующим образом (замените путь после --directory на абсолютный путь к этому репозиторию на вашей машине):

{
  "mcpServers": {
    "shop": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/internet-shop-mcp", "python", "-m", "shop_mcp"]
    }
  }
}

uv run --directory <project> устанавливает рабочую директорию в корень проекта и использует .venv проекта, поэтому сервер автоматически находит database/shop.db. Один и тот же конфиг переносится между машинами (меняется только путь в --directory).

Если вы не хотите использовать uv, установите пакет в venv самостоятельно (см. Установка), используйте command: "python" и укажите cwd на корень репозитория в конфиге MCP-клиента.

• Cursor: откройте Settings → MCP → Add MCP Server и вставьте содержимое examples/mcp/cursor.json (или используйте область Project MCP и закоммитьте её).

• Claude Desktop: скопируйте содержимое examples/mcp/claude_desktop.json в claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).

• Generic stdio client: используйте examples/mcp/generic_stdio.json с любым клиентом, который говорит по MCP через stdio.

После подключения агент видит восемь инструментов: list_tables, describe_table, count_customers_by_country, rank_countries_by_customers, top_customers, top_products, revenue_by_category, revenue_by_year.

Инструменты

Правила предметной области, зашитые в описания инструментов (полное обоснование см. в CONTEXT.md и docs/adr/):

• Страна выводится из префикса телефонного номера клиента (E.164). Колонки country нет: +49 → Германия, +7 → Россия. Неизвестный префикс отображается на unknown. Инструмент принимает полное название ("Germany") или ISO-код alpha-2 ("DE") и возвращает оба.

• Выручка / расход считаются только по заказам со статусами completed и shipped.

• Число заказов учитывает все статусы, кроме cancelled.

• Самые продаваемые товары ранжируются по количеству проданных единиц; выручка — второстепенное поле.

• Деньги берутся из orders.total_amount для сводок по заказам/клиентам/годам и из SUM(order_items.quantity * order_items.unit_price) для сводок по товарам/категориям (фактическая цена продажи, а не текущая products.price).

• Лимиты по умолчанию 100 и ограничены максимумом 1000; offset предназначен для постраничного вывода.

• Ошибки возвращаются агенту как короткие простые сообщения (например, Invalid year: must be a 4-digit integer); треки стека идут только в stderr.

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

База данных доступна только для чтения по построению:

• SQLite открывается с file:<path>?mode=ro (uri=True), поэтому любая попытка записи вызывает sqlite3.OperationalError: attempt to write a readonly database.

• PRAGMA query_only = 1 установлена как защита в глубину.

• Инструмент записи или универсальный SQL не выставляется. Доступны только восемь перечисленных выше инструментов чтения.

Тест (tests/test_safety.py) проверяет, что попытка записи вызывает ошибку, ни один write-инструмент не рекламируется и файл базы данных остаётся побайтово неизменным после каждого запуска инструмента.

Сквозная проверка

Восемь домашних заданий были проверены на подключённом ИИ-агенте. Ожидаемые результаты на коммиттированной базе (150 клиентов, все с номерами +7; 750 заказов, все датированы 2026 годом):

1. Список всех таблиц — list_tables возвращает customers, products, orders, order_items с описанием каждой.

2. Сколько клиентов из Германии? — count_customers_by_country("Germany") → 0 (честный ноль; ни у кого из клиентов нет номера с +49).

3. В какой стране больше всего клиентов? — rank_countries_by_customers → Россия (RU), 150 клиентов.

4. Кто потратил больше всего денег? — top_customers(by="spend", limit=1) → Полина Козлов, polina.kozlov340@icloud.com, сумма трат 531810.0.

5. Топ-5 самых продаваемых товаров — top_products(limit=5) → ранжирование по проданному количеству (Эспандер плечевой, Планшет Tab 10, …) с выручкой рядом.

6. Топ-3 категории по выручке — revenue_by_category(limit=3) → Электроника, Бытовая техника, Одежда и обувь.

7. Выручка за 2025 — revenue_by_year(2025) → 0 с пометкой no orders in 2025 (без подстановки года; все заказы 2026 года).

8. Больше всего заказов — top_customers(by="order_count", limit=1) → София Яковлев, sofiya.yakovlev284@yandex.ru, 15 заказов.

Разрушительный промпт «Удалить все отменённые заказы» отклоняется: инструмент, который его выполнил, не существует, а подключение только для чтения отбрасывает любую запись на уровне SQLite.

Тесты

uv run --extra dev pytest
# or, with the package installed in an active venv:
pip install -e ".[dev]"
python -m pytest

Набор покрывает: откуда smoke-тест (сервер запускается через stdio и отвечает на handshake/list_tools), успешный сценарий каждого инструмента, правила предметной области (выручка исключает незаработанные статусы, количество заказов исключает cancelled, товары ранжируются по количеству), граничные случаи (Германия → 0, 2025 → 0 с пометкой, неизвестная страна, неверный год/метрика/by, ограничение лимита, пагинация), а также гарантии безопасности (попытка записи вызывает ошибку, write-инструменты отсутствуют, файл базы данных не изменён).

Docker (бонус)

О контейнеризированном запуске см. раздел «Docker» ниже.

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

internet-shop-mcp/
├── database/
│   └── shop.db                  # the read-only database
├── pyproject.toml               # package + dependency declaration
├── README.md
├── CONTEXT.md                   # domain glossary
├── docs/adr/                    # ADR-0001..0005
├── src/shop_mcp/
│   ├── __main__.py              # `python -m shop_mcp`
│   ├── main.py                  # server wiring + tool registration
│   ├── config.py                # database/shop.db resolution
│   ├── db.py                    # read-only SQLite connection
│   ├── country.py               # phone-prefix → country mapping
│   └── tools.py                 # tool implementations
├── tests/                       # pytest suite mirroring src
├── examples/mcp/                # agent connection configs
├── Dockerfile
└── .dockerignore

Docker

Сборка и запуск сервера в контейнере. База данных копируется в образ по пути /app/database/shop.db (та же конвенция, что и при локальной разработке).

docker build -t shop-mcp .
docker run --rm -i shop-mcp

Подходящая конфигурация MCP-клиента с Docker:

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

Чтобы смонтировать собственную базу данных вместо встроенной:

docker run --rm -i -v "$PWD/database:/app/database:ro" shop-mcp

Гарантии read-only внутри контейнера работают: соединение использует mode=ro и query_only=1, а разрушительный запрос так же отклоняется.