# magnit-mcp

Неофициальный MCP-сервер для покупок в «Магните» под собственной авторизацией:
поиск продуктов, серверная корзина, доставка, сохранённые способы оплаты и заказ.
Работает через **stdio** в Hermes и других MCP-клиентах. Python **3.11+**,
Linux или macOS. Лицензия [MIT](LICENSE).

Каждый пользователь запускает свой процесс и импортирует свою сессию.
Браузер, Playwright, отдельный сетевой сервис и российский jump host для запуска
клиента не требуются. Доступ к API `magnit.ru` из вашей сети проверяется отдельно.
Используется API сайта, поэтому совместимость зависит от изменений магазина.

**Отправка заказов по умолчанию отключена.** Флаг `--enable-orders` разрешает её,
но каждый конкретный заказ всё равно требует запроса пользователя после показа
состава, адреса, времени, карты и суммы. Создание заказа может запустить оплату.

## Установка из исходников

```sh
git clone https://github.com/olegpelipenko/magnit-mcp.git
cd magnit-mcp
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/magnit-mcp --version
.venv/bin/python scripts/smoke_mcp.py --command .venv/bin/magnit-mcp
```

Последняя команда проверяет установленный MCP в отдельном пустом состоянии:
без аккаунта, изменения корзины и покупки. Публикация в PyPI не требуется.

**Для Hermes:** передайте агенту [docs/INSTALL_FOR_AGENT.md](docs/INSTALL_FOR_AGENT.md).
Полная инструкция подключения: [docs/HERMES.md](docs/HERMES.md).

## Своя авторизация

Войдите в `magnit.ru` обычным браузером. Сохраните свой GET `checkout/preview`
из DevTools → Network → Copy as cURL в закрытый файл **вне репозитория**.
Как получить и обновлять экспорт: [docs/AUTH.md](docs/AUTH.md).

```sh
.venv/bin/magnit-mcp import-session --input /private/path/magnit-cart.curl --dry-run
.venv/bin/magnit-mcp import-session --input /private/path/magnit-cart.curl
.venv/bin/magnit-mcp doctor --online
```

Импорт разбирает cURL как данные и не выполняет shell-команду. Нужен собственный
экспорт текущей корзины с cookies и заголовками контекста магазина.
При необходимости принимается также JSON с `url` и `headers`.
Cookies, коды входа и содержимое экспорта не отправляются в чат или Git.

## Подключение MCP

В настройках своего MCP-клиента укажите абсолютный путь к установленной команде:

```json
{
  "mcpServers": {
    "magnit": {
      "command": "/absolute/path/to/magnit-mcp/.venv/bin/magnit-mcp",
      "args": ["--state-dir", "/private/path/magnit-state", "serve"]
    }
  }
}
```

Это общий формат клиентов с `mcpServers`. Hermes использует `mcp_servers`:
см. [пример YAML](examples/hermes.yaml) и [инструкцию](docs/HERMES.md).
Для оформления добавьте `--enable-orders` **перед** `serve`.
Команда `serve` пишет в stdout только MCP-протокол, журналы — в stderr.

## Инструменты

| Инструмент | Назначение |
| --- | --- |
| `magnit_status` | Локальная готовность, включённые возможности, последний `order_ref` |
| `magnit_auth_status` | Проверить авторизацию, при необходимости обновить сессию |
| `magnit_refresh_session` | Явно обновить и сохранить cookies |
| `magnit_get_context` | Текущий сервис, магазин по адресу и `context_id` |
| `magnit_set_context` | Явно сменить сервис/способ получения; предпочтения адреса сбрасываются |
| `magnit_search_products` | Найти товары, предварительные цены, остатки и шаг количества |
| `magnit_get_cart` | Прочитать свежую серверную корзину и `unavailable_items` |
| `magnit_set_cart_quantity` | Задать абсолютное количество одного товара; `0` удаляет его |
| `magnit_list_addresses` | Показать сохранённые адреса с `address_ref` |
| `magnit_select_address` | Выбрать адрес и определить магазин доставки |
| `magnit_get_checkout` | Полный расчёт, способы оплаты и интервалы |
| `magnit_select_payment` | Выбрать сохранённую оплату в чекауте |
| `magnit_select_delivery_slot` | Сохранить выбранный интервал без бронирования |
| `magnit_prepare_order` | Подготовить конкретный заказ и `order_ref` на 10 минут |
| `magnit_create_order` | Однократно отправить согласованный заказ; может запустить оплату |
| `magnit_get_order_status` | Проверить исход отправки и свежий статус созданного заказа |

## Порядок покупки

1. Проверить сессию. Выбрать сохранённый адрес **до поиска**: магазин доставки
   назначает Магнит. Код магазина из ссылки на товар для доставки не фиксируется.
2. Найти товары, прочитать корзину и изменить количество с её свежими `revision`
   и `context_id`. Количество абсолютное, а не прибавление.
3. Выбрать сохранённую карту и актуальное время из чекаута. Цены поиска
   предварительные; для согласования используется полный расчёт магазина.
4. Подготовить заказ, показать `review` и получить запрос пользователя на оформление.
5. Передать `order_ref`, точную сумму `expected_total_kopecks`, `confirmed=true`
   в `magnit_create_order`. Затем проверить статус заказа и оплаты.

Подробности для агента, недоступные товары и действия при ошибках:
[docs/USAGE.md](docs/USAGE.md). Скилл для базовой работы не нужен:
MCP уже передаёт инструкции, схемы инструментов и результаты.

## Состояние и ограничения

По умолчанию состояние хранится в `$XDG_DATA_HOME/magnit-mcp` или
`~/.local/share/magnit-mcp`; путь меняется через `--state-dir`,
`MAGNIT_MCP_STATE_DIR` или [TOML](examples/config.toml). `.env` не загружается.
Каждому аккаунту нужен отдельный каталог. Права: каталог `0700`, файлы `0600`.

Локально хранятся авторизация, ссылки на выбранные адрес/оплату, кэш поиска
и журнал отправки заказов. **Корзина и недоступные позиции берутся с сервера
Магнита.** Отдельного локального списка покупок нет.

Обновление cookies не гарантирует бессрочный вход: если refresh отклонён,
потребуется свежий экспорт. Реальное оформление проверено для одной доставки
с сохранённой картой. Мультизаказы, отдельные ручные/возрастные сценарии и все
разновидности весовых товаров не поддерживаются общим потоком. Проверенный
весовой формат использует граммы: 1 кг бананов передаётся как `1000`.

Неопределённый результат POST не повторяется: клиент сохраняет попытку до сети
и блокирует повторную отправку до выяснения результата. Это локальная защита;
серверная транзакционная идемпотентность не обещается. При `is_paid=null`
магазин не дал явного признака списания, даже если заказ уже создан.

## Разработка

```sh
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests scripts
.venv/bin/python scripts/smoke_mcp.py --command .venv/bin/magnit-mcp
```

Тесты используют искусственные ответы API и не делают покупок.
[CONTRIBUTING.md](CONTRIBUTING.md) · [Проверенные операции](docs/VERIFIED.md) ·
[Подготовка публикации](docs/RELEASING.md) · [Приватность](SECURITY.md).