mcp-shop-server

MCP-сервер, который даёт AI-агенту read-only доступ к SQLite-базе интернет-магазина (customers, products, orders, order_items). Агент через него отвечает на аналитические вопросы по данным: структура базы, агрегаты по клиентам, товарам, категориям и выручке. Транспорт — stdio.

Запись в базу невозможна by design: три независимых слоя защиты — соединение mode=ro, валидация запроса до выполнения (только SELECT / WITH ... SELECT) и sqlite3-authorizer.

Замеры, доказательства и отклонения от ТЗ — REPORT.md.

Использование

1. Клонировать

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

В репозитории уже лежит shop.db (150 клиентов, 50 товаров, 750 заказов, 1900 позиций).

2. Установить зависимости

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

Без uv — то же самое штатными средствами:

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

Требуется Python 3.11+. Зависимости: mcp (официальный MCP SDK) и pytest для тестов; работа с базой — на sqlite3 из стандартной библиотеки.

3. Прописать в конфиг агента

Минимальная форма конфигурации:

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

Рабочий пример для клиента с блоком mcpServers (Claude Desktop, Cursor и совместимые):

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

Для Claude Code достаточно одной команды:

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DB необязателен: если переменная не задана, сервер берёт shop.db рядом с server.py. Указывайте её, если база лежит в другом месте. Интерпретатор лучше указывать из .venv — иначе системный python может не найти пакет mcp.

4. Запуск

Сервер запускает агент, руками это нужно редко:

.venv/bin/python server.py

Процесс молча ждёт JSON-RPC на stdin; диагностика идёт в stderr, stdout занят протоколом MCP.

5. Проверка и вопросы агенту

.venv/bin/python -m pytest -q

После подключения агент видит три инструмента. Вопросы задаются обычным языком.

Восемь задач из текста домашнего задания — их и стоит прогнать для проверки:

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ Задачи 2, 3 и 7 в поставляемой базе решения не имеют, и это ожидаемо. В customers нет колонки со страной — все 150 клиентов с российскими телефонами; все 750 заказов датированы 2026 годом, за 2025-й данных нет.

Сервер в этом случае не выдумывает данные: сообщает, что такого поля в схеме нет, и перечисляет существующие колонки. Ничего не зашито в код — схема читается из базы, поэтому на другой базе, где country есть, те же вопросы отработают штатно.

Дополнительно проверяются вопросы, которые база закрывает полностью: топ-5 клиентов по сумме заказов, выручка по категориям, распределение заказов по статусам, средний чек, остатки товаров.

Проверка защиты от записи. На «Delete all cancelled orders» агент получает понятный отказ, а не ошибку: сервер работает только на чтение, 102 отменённых заказа остаются на месте.

Инструменты

Выдача ограничена: по умолчанию 100 строк, максимум 1000. При обрезке ответ сообщает, сколько строк вернули, сколько всего нашлось и с каким offset читать дальше.

Если запрошенного поля в базе нет (например, страны клиента), сервер честно об этом говорит и перечисляет существующие колонки — несуществующие поля не додумываются.

Related MCP server: Shop Analytics MCP Server

Как сделано

Проект сгенерирован одним промптом — файл SPEC-mcp-shop.md, отправленный агенту целиком, без последующих уточнений.

Внутри агент работал циклом по скиллу repo-task-proof-loop (Денис Ширяев, Apache-2.0): заморозка спеки → сборка → упаковка доказательств → проверка свежей сессией → минимальная правка → проверка снова, до вердикта PASS.

Доказательства прогона лежат в репозитории, в .agent/tasks/mcp-shop-server/:

• spec.md — замороженная спека с критериями приёмки AC1…AC17;

• evidence.md / evidence.json — по каждому критерию вердикт и конкретное доказательство;

• verdict.json — результат независимой проверки свежей сессией;

• problems.md — расхождения, найденные проверяющим;

• raw/ — сырые логи прогонов: тесты, живая MCP-сессия, проверка чистоты stdout.

Проверяется не исходный код, а поведение сервера с живым агентом: harness raw/mcp_session_check.py поднимает server.py по stdio настоящим MCP-клиентом, вызывает все инструменты, прогоняет восемь аналитических задач, получает отказ на удаление и сверяет, что stdout содержит только кадры JSON-RPC.

Сам скилл разработки лежит локально в .claude/skills/ и в репозиторий не коммитится — это чужой код.

Принятые решения по неоднозначностям ТЗ