Read-only MCP-сервер магазина

Python MCP-сервер по stdio для существующей SQLite-базы интернет-магазина (data/shop.db). Файл открывается только на чтение; изменяющий SQL отклоняется и не выполняется.

Установка

Python 3.11+:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Запуск

Из корня проекта (путь к БД по умолчанию — ./data/shop.db):

python -m shop_mcp
# или
shop-mcp

Другой путь к базе:

SHOP_DB_PATH=~/my/test-mcp-db/data/shop.db python -m shop_mcp

Процесс общается по MCP через stdin/stdout. Не вводите команды в этот терминал, пока к нему не подключён MCP-клиент.

Конфиг MCP в Cursor

Добавьте запись mcpServers (Cursor Settings → MCP или .cursor/mcp.json в проекте). Транспорт — stdio.

В примерах путь ~/my/test-mcp-db — этот репозиторий. SHOP_DB_PATH сервер раскрывает сам (~ → домашний каталог). Если Cursor не раскрывает ~ в command / cwd, укажите там /Users/<вы>/my/test-mcp-db/....

Локально (venv)

{
  "mcpServers": {
    "shop": {
      "command": "~/my/test-mcp-db/.venv/bin/python",
      "args": ["-m", "shop_mcp"],
      "cwd": "~/my/test-mcp-db",
      "env": {
        "SHOP_DB_PATH": "~/my/test-mcp-db/data/shop.db"
      }
    }
  }
}

Если после pip install -e . удобнее консольный скрипт:

{
  "mcpServers": {
    "shop": {
      "command": "~/my/test-mcp-db/.venv/bin/shop-mcp",
      "cwd": "~/my/test-mcp-db",
      "env": {
        "SHOP_DB_PATH": "~/my/test-mcp-db/data/shop.db"
      }
    }
  }
}

Docker

Собрать образ один раз:

docker build -t shop-mcp .

{
  "mcpServers": {
    "shop": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "~/my/test-mcp-db/data/shop.db:/data/shop.db:ro",
        "-e",
        "SHOP_DB_PATH=/data/shop.db",
        "shop-mcp"
      ]
    }
  }
}

Флаг -i обязателен, чтобы stdio оставался подключённым. Монтируйте только shop.db; контейнер не должен перезаписывать файл на хосте.

Инструменты

Tool	Назначение
list_tables	Пользовательские таблицы и краткое описание роли (sqlite_sequence не показывается)
describe_table	Реальные колонки, типы, PK/FK
execute_readonly_sql	Один SELECT / WITH / EXPLAIN; limit (по умолчанию 100, максимум 1000) и offset
shop_analytics	Рейтинги и выручка за год без ручного SQL

Суммы, штуки и выручка считаются как order_items.quantity * order_items.unit_price; заказы со статусом cancelled исключаются. Календарный год берётся из strftime('%Y', orders.order_date).

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

• SQLite URI file:<abs>?mode=ro
• Комментарии вырезаются; цепочки запросов (SELECT 1; DELETE ...) отклоняются
• INSERT / UPDATE / DELETE / DROP / ALTER / CREATE / ATTACH / PRAGMA / … → явная ошибка «не разрешено»
• Синтаксические ошибки SQLite и неизвестные колонки возвращаются структурированно; процесс не завершается

Замечания для оценки

• У customers нет колонки country. Это видно через describe_table; географию выдумывать нельзя. SELECT country FROM customers вернёт ошибку SQLite.
• Даты заказов в текущем дампе — 2026 год. Выручка за 2025 может быть 0. Это корректный ответ, а не сломанный фильтр.

Тесты

pytest

Тесты копируют data/shop.db во временный файл и проверяют, что хеш копии не меняется после отклонённых записей.

Пример отработанного запроса