pyaterochka-mcp

Неофициальный локальный MCP-сервер для поиска товаров, сборки корзины и защищённого оформления доставки из «Пятёрочки».

Проект не связан с X5 Group или «Пятёрочкой». Публичного API оформления заказов нет. Приватные интерфейсы могут измениться, быть заблокированы или запрещены пользовательским соглашением. Используйте только со своим аккаунтом.

Что умеет MCP

Инструмент	Побочный эффект	Назначение
pyaterochka_status	нет	Проверяет локальную настройку, сессию, магазин и готовность checkout
set_store	локальный конфиг	Выбирает магазин по SAP-коду
find_nearest_store	только при select=true	Находит магазин по уже выбранным пользователем координатам
list_categories	нет	Показывает категории выбранного магазина
search_products	нет	Ищет доступные товары и актуальные цены
list_category_products	нет	Показывает товары категории
get_product	нет	Читает карточку, наличие, состав и атрибуты товара
view_cart	нет	Читает общую live-корзину аккаунта
add_to_cart	меняет корзину	Добавляет товар; денег не списывает
update_cart_item	меняет корзину	Задаёт точное количество; 0 удаляет позицию
clear_cart	меняет корзину	Очищает корзину
list_delivery_intervals	нет	Читает доступные виды и интервалы доставки
select_delivery_interval	меняет корзину	Выбирает express/auto или точный интервал
list_payment_methods	нет	Показывает только маскированные способы оплаты
select_payment_method	меняет checkout	Выбирает способ и при необходимости запоминает linked ID
clear_preferred_payment_method	локальный конфиг	Забывает локальное предпочтение, не удаляя карту
set_order_details	меняет корзину	Записывает квартиру, подъезд, этаж и комментарии
checkout_preview	пересчитывает корзину	Делает revise, показывает точный итог; заказ не создаёт
confirm_order	может списать деньги	После отдельного подтверждения один раз отправляет реальный заказ
active_orders	нет	Читает активные заказы
order_history	нет	Читает историю с редактированием личных полей
get_order_status	нет	Читает текущий статус одного заказа
list_cancel_reasons	нет	Получает актуальные причины отмены
cancel_order	отменяет заказ	Отменяет только явно указанный пользователем заказ

Все изменения корзины аннулируют предыдущий checkout preview. Единственный инструмент, создающий реальный заказ, — confirm_order; по умолчанию он выключен в конфиге.

Текущее состояние

Версия 0.6.0a3 содержит 24 MCP-инструмента:

• MCP-инструменты каталога, поиска, карточки товара и выбора магазина;
• импорт заголовков и cookies из локального HAR без вывода секретов в терминал;
• локальный Chrome transport для запросов через открытую вкладку 5ka.ru;
• автоматический локальный capture через отдельное окно Chrome без ручного HAR;
• текущий протокол корзины 5ka.ru: корзина как заказ со статусом CART;
• создание/чтение корзины, добавление, точное изменение количества и очистку;
• выбор доставки «как можно скорее» или точного доступного интервала;
• сохранение квартиры, подъезда, этажа и комментариев к заказу;
• чтение и выбор способов оплаты с маскированием карты;
• безопасное запоминание ID уже привязанного способа оплаты;
• обязательный пересчёт доступности и минимальной суммы перед оформлением;
• однократную отправку заказа через linked card, новую карту, СБП или SberPay;
• чтение активного заказа, истории и точного статуса;
• список причин отмены и отмену только по явному запросу;
• возможность переопределить версию любого endpoint-а через локальный конфиг;
• двухшаговый checkout с TTL, одноразовым токеном, суммой в копейках и fingerprint корзины;
• максимальный лимит заказа;
• запрет реального submit по умолчанию;
• отсутствие автоматического повтора submit при любом неоднозначном ответе;
• сверку корзины после неоднозначной ошибки мутации без повторной записи;
• маскирование адреса, контактов, карты и комментариев в ответах статуса;
• общий строгий редактирующий фильтр для MCP-ответов и HAR-отчётов;
• санитизацию и ограничение длины недоверенного текста от API;
• лимит количества одного товара от 0 до 100 и отказ для NaN/Infinity;
• потоковый лимит тела ответа до разбора JSON;
• запрет редиректов, доменно-привязанные cookies и проверку каждого URL;
• валидацию всех идентификаторов, подставляемых в URL;
• MCP-схемы с границами аргументов и аннотациями побочных эффектов;
• только локальный stdio transport.

Маршруты сверены с актуальным публичным JavaScript-клиентом 5ka.ru:

• GET /api/orders/v3/orders/?in_action=true — поиск черновика CART;
• /api/orders/v4|v8/orders/... — создание корзины;
• /api/orders/v5|v8/orders/... — изменение корзины;
• GET /api/orders/v6|v10/orders/{id}/ — чтение корзины;
• /api/orders/v1|v3/orders/{id}/intervals — интервалы доставки;
• PATCH /api/orders/v7|v12/orders/{id}/ — доставка и детали заказа;
• POST /api/orders/v1|v2/orders/{id}/revise — финальный пересчёт;
• /api/orders/v1/payment-methods — способы оплаты;
• /api/orders/v1/orders/{id}/pay-by-* — однократная отправка/оплата;
• /api/ordering/public/v1/orders/... — активный заказ и отмена.

API версионируется и включается feature-флагами, поэтому все стандартные маршруты остаются переопределяемыми.

Прямой HTTP-клиент с импортированными заголовками может получить 403. Поэтому рекомендуемый режим выполняет запросы непосредственно внутри уже авторизованной пользовательской вкладки Chrome. MCP не переключает вкладку, разрешает запросы только по HTTPS к 5ka.ru и его поддоменам и не следует редиректам. HTTP-режим применяет ту же доменную проверку; его cookies привязаны к 5ka.ru.

Проект ничего не кэширует: каталог, цены, наличие, корзина и заказ каждый раз читаются из upstream для выбранного store_id. Это снижает риск показать устаревшую цену, но не превращает приватный API в стабильный контракт.

Реальный submit не включён в стандартную конфигурацию. При уже привязанной карте MCP может отправить заказ одним защищённым вызовом. Для новой карты, СБП или SberPay «Пятёрочка» возвращает официальный платёжный переход: подтверждение в форме или банковском приложении остаётся обязательным. 3-D Secure и антифрод-проверки банка также нельзя гарантированно автоматизировать.

Подробная архитектура, маршруты, safety guard и проверенный end-to-end сценарий описаны в docs/PAYMENTS.md. Результаты внешних аудитов и статус финальных исправлений находятся в docs/SECURITY_AUDIT_FOLLOWUP_RESOLUTION_2026-07-28.md. Правила сообщения об уязвимостях описаны в SECURITY.md.

Установка

cd pyaterochka-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[dev,capture]'

Подключение к MCP-клиенту

Codex:

codex mcp add pyaterochka -- /absolute/path/to/pyaterochka-mcp/.venv/bin/pyaterochka-mcp
codex mcp list

Для клиента с JSON-конфигурацией MCP:

{
  "mcpServers": {
    "pyaterochka": {
      "command": "/absolute/path/to/pyaterochka-mcp/.venv/bin/pyaterochka-mcp"
    }
  }
}

После подключения перезапустите MCP-клиент или откройте новую задачу и первым вызовите pyaterochka_status.

Автоматический безопасный capture

Запустите:

.venv/bin/pyaterochka-capture

Команда открывает отдельное окно Google Chrome с закрытым локальным профилем. В этом окне:

1. Войдите через X5ID. Если аккаунта ещё нет, выберите регистрацию, укажите свой номер телефона и самостоятельно введите SMS-код.
2. Выберите адрес доставки.
3. Добавьте один товар.
4. Откройте корзину и удалите товар.
5. Не переходите к оплате.
6. Закройте окно Chrome.

Сессионные заголовки, cookies, магазин и координаты сохраняются напрямую в owner-only конфиг. Они не печатаются в терминал и не передаются в чат. MCP не просит номер телефона или SMS-код и не регистрирует аккаунт от имени пользователя: согласия и одноразовый код остаются в официальном окне X5ID.

Если сессия ещё не настроена, pyaterochka_status возвращает пошаговый authentication_onboarding с предложением войти или зарегистрироваться. Различить «нет аккаунта» и «аккаунт есть, но сессия ещё не захвачена» до официальной авторизации MCP не может.

Альтернатива: импорт HAR

1. Откройте https://5ka.ru в Chrome и войдите через X5ID.
2. Выберите адрес доставки и нужный магазин.
3. Откройте DevTools → Network, включите Preserve log и очистите список.
4. Выполните только безопасный сценарий:
   • найдите «молоко»;
   • откройте карточку товара;
   • добавьте один товар;
   • откройте корзину и экран итоговой суммы;
   • удалите добавленный товар.
5. Не нажимайте кнопку оплаты.
6. В Network выберите Save all as HAR with content.
7. Импортируйте HAR локально:

.venv/bin/pyaterochka-import-har ~/Downloads/5ka-session.har --transport chrome

Для Chrome transport:

1. Оставьте в обычном Google Chrome открытую вкладку https://5ka.ru/.
2. В меню Chrome включите View → Developer → Allow JavaScript from Apple Events.
3. При первом запуске разрешите вашему MCP-клиенту или терминалу управлять Google Chrome, если macOS покажет системный запрос.

Запросы выполняются в фоне именно в этой вкладке, используя её действующую сессию. MCP не читает историю браузера и не отправляет запросы на другие домены.

Секреты сохраняются в:

~/.config/pyaterochka-mcp/config.json

Файл создаётся с правами 0600. В терминал значения cookies и токенов не печатаются. Рядом создаётся capture-report.json — редактированный отчёт о распознанных маршрутах. Импортёр понимает и старую пару API v5/v6, и текущую v8/v10. Для ответов сохраняется только структура полей и типов, без значений. HAR содержит секреты: после проверки импорта удалите его вручную безопасным способом.

Проверка

.venv/bin/pytest
.venv/bin/pyaterochka-capture --help
.venv/bin/pyaterochka-probe "молоко"
.venv/bin/pyaterochka-mcp

pyaterochka-probe выполняет только чтение: проверяет категории и поиск, не меняя корзину. В выводе нет cookies, токенов и сырых ответов upstream. В режиме chrome обычный Chrome должен быть открыт на 5ka.ru.

При запуске MCP первым вызовите:

pyaterochka_status

Затем:

search_products("молоко")
get_product("<id>")
add_to_cart("<id>", 1)
view_cart()

Полный checkout выполняется строго по этапам:

list_delivery_intervals()
select_delivery_interval("INTERVAL", "<uuid>")   # необязательно для auto/express
set_order_details(flat="12", entrance="1", floor="4")
list_payment_methods()
select_payment_method(<id>)
checkout_preview()

checkout_preview ничего не покупает, но это не read-only-вызов: он может выбрать сохранённый способ оплаты, пересчитать loyalty и выполнить revise общей корзины. Он возвращает точную итоговую сумму, недостающую сумму до минимума, выбранную доставку, маскированный способ оплаты и missing_requirements. Только если ready_for_submit=true, сумму нужно показать пользователю и получить отдельное явное подтверждение. Готовый preview также возвращает короткоживущий confirmation_token.

После подтверждения exact total:

confirm_order(<точная сумма>, "<confirmation_token из этого preview>")

Для уже привязанной карты успешный ответ может сразу содержать созданный заказ. Для новой карты/СБП/SberPay ответ содержит requires_external_payment=true и официальный payment_url. После попытки используйте:

active_orders()
order_history()
get_order_status("<order_id>")

При сетевой ошибке confirm_order не повторяйте: сначала проверьте активный заказ и историю.

Полный жизненный цикл — от первой авторизации до отмены и восстановления после ошибок — описан в docs/ARCHITECTURE_AND_FLOWS.md.

Сохранённая карта

MCP сам не принимает и не хранит номер карты, срок действия или CVV. Первый платёж новой картой проходит на официальной платёжной странице «Пятёрочки». Если после этого API показывает карту как привязанную, её можно выбрать один раз с локальным предпочтением:

list_payment_methods()
select_payment_method(<id привязанной карты>, remember_for_future_orders=true)

В конфиг записывается только непрозрачный payment_method_id. При следующих checkout_preview MCP автоматически выбирает этот метод до финального пересчёта, поэтому пользователь всегда подтверждает уже актуальную сумму. Удалить локальное предпочтение можно вызовом clear_preferred_payment_method(): это не удаляет карту в аккаунте «Пятёрочки».

Если «Пятёрочка» не сохранила карту, скрыла её или банк требует 3-D Secure, MCP не может обойти официальный платёжный шаг. Сохранение карты выполняет только сама платёжная система/«Пятёрочка», а не этот проект.

Переопределение endpoint-а

Если feature-флаг аккаунта использует другую версию API, endpoint описывается методом, URL/path и шаблоном JSON. Значения в фигурных скобках подставляются в момент вызова:

{
  "endpoints": {
    "cart_set": {
      "method": "PUT",
      "base": "orders",
      "path": "/v5/orders/{cart_id}/item/{product_id}/",
      "json": {
        "qty": "{quantity}"
      }
    }
  }
}

Поддерживаемые имена:

• cart_list
• cart_create
• cart_get
• cart_add
• cart_set
• cart_delete
• cart_clear
• delivery_intervals
• order_update
• cart_revise
• payment_methods
• payment_method_select
• pay_linked_card
• pay_unlinked_card
• pay_linked_sbp
• pay_unlinked_sbp
• pay_linked_sberpay
• pay_unlinked_sberpay
• active_orders
• order_history
• order_get
• cancel_reasons
• order_cancel

Не копируйте в публичный issue или чат config.json и исходный HAR.

Защита денег

confirm_order не работает, пока одновременно не выполнены все условия:

• checkout.submit_enabled явно установлен в true;
• только что выполнен checkout_preview;
• передан одноразовый токен именно этого preview;
• подтверждённая пользователем сумма совпадает с preview;
• live-корзина имеет ту же сумму и fingerprint;
• прямо перед платёжным POST повторно совпали сумма, версия и fingerprint;
• набран минимум, выбраны доставка, квартира и способ оплаты;
• сумма не превышает checkout.max_total.

Submit выполняется ровно один раз и не повторяется автоматически при сетевой ошибке. Preview расходуется до сетевого запроса. Оставляйте submit_enabled: false, пока не готовы провести первый контролируемый заказ. Для активации вручную измените owner-only ~/.config/pyaterochka-mcp/config.json, одновременно задав разумный max_total. Это включает возможность, но само по себе ничего не заказывает.

Осознанно принятый риск полной автоматизации

Чтобы сохранить сценарий уровня «показать итог → пользователь отвечает “ок” → оформить привязанной картой», одноразовый confirmation_token намеренно остаётся в ответе MCP, а confirm_order доступен модели после явного подтверждения только что показанной точной суммы.

Санитизация внешних строк, ограниченные схемы, аннотации инструментов, одноразовый token, TTL, fingerprint и повторная live-проверка существенно снижают риск, но не являются криптографическим доказательством того, что человек прочитал preview. Prompt injection из данных upstream остаётся остаточным риском, который владелец проекта осознанно принимает ради полной автоматизации. Для более строгого режима оставьте submit_enabled=false и оформляйте заказ в официальном интерфейсе.

Автоматизация не может отменить требование 3-D Secure, антифрод-проверку, подтверждение СБП или другой challenge, который запросит банк либо X5.

Один аккаунт — одна общая корзина

Корзина хранится на стороне «Пятёрочки», а не внутри MCP. Официальный сайт, приложение и все MCP-процессы с одной X5ID-сессией видят и меняют одну корзину. Не собирайте её одновременно из нескольких клиентов: чужое изменение аннулирует preview, а live-проверка перед оплатой остановит submit. После неоднозначной ошибки сначала вызовите view_cart, active_orders и order_history, не повторяя финансовый запрос.

Источники

Каталожные маршруты и формы ответов сверены с MIT-проектами:

• Open-Inflation/pyaterochka_api
• zavorateam/pyatorochka-min-api

Архитектура и safety-паттерны частично адаптированы из Dudude-bit/yandex-lavka-mcp. Копирайты и полные уведомления MIT сохранены в NOTICE.

Лицензия

Собственный код проекта распространяется по MIT License. Уведомления об использованных MIT-проектах и их авторские строки сохранены в NOTICE. Техническая проверка совместимости лицензий, перечень зависимостей и обязанности при распространении описаны в docs/LICENSING.md.

Название «Пятёрочка» и связанные товарные знаки принадлежат их правообладателям. MIT-лицензия относится к коду этого репозитория и не даёт разрешения на товарные знаки, приватный API или нарушение условий сервиса.