# AuchanMCP

![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![Status: personal project](https://img.shields.io/badge/status-personal%20project-lightgrey)

MCP-коннектор к **auchan.ro** (румынский Ашан, платформа [VTEX IO](https://vtex.com))
для ИИ-ассистентов: поиск товаров, подбор доступного аналога, если нужного
товара нет на складе, и работа с корзиной.

Никакого браузера в рантайме — все операции идут через прямую эмуляцию
публичных REST-эндпоинтов VTEX, которые использует сам сайт. Подробности
разведки и мотивация архитектурных решений — в [`docs/API_NOTES.md`](docs/API_NOTES.md)
и [`docs/DECISIONS.md`](docs/DECISIONS.md).

> Неофициальный проект, не связан с Auchan и не одобрен им. Использует
> публичные эндпоинты их собственного сайта так же, как их использует
> браузер при обычном посещении auchan.ro.

## Возможности

| Инструмент MCP | Что делает |
|---|---|
| `search_products(query, limit)` | Полнотекстовый поиск по каталогу |
| `get_product_by_url_slug(slug)` | Точный товар по ссылке auchan.ro (`.../<slug>/p`) |
| `find_product_or_analog(description)` | Поиск под описание из списка покупок; если товара нет в наличии — отдаёт лучшие доступные аналоги |
| `create_cart()` | Создать анонимную корзину |
| `add_to_cart(order_form_id, sku_id, quantity)` | Добавить товар в корзину |
| `get_cart(order_form_id)` | Посмотреть содержимое корзины |

## Как это работает

```
AI-ассистент  ──MCP──▶  src/mcp_server.py  ──HTTP──▶  auchan.ro (VTEX REST API)
                              │
                              ├─ src/auchan_api.py   — клиент к VTEX Catalog/Checkout API
                              └─ src/matcher.py       — поиск товара под описание + аналоги
```

Поиск и анонимная корзина у VTEX не требуют авторизации — это подтверждено
прямыми HTTP-запросами без браузера, без cookies, без заголовков логина.
Авторизация (для истории заказов, My CLUB и т.п.) устроена сложнее — см.
раздел ниже и `docs/API_NOTES.md`.

## Установка

```bash
git clone <url-этого-репозитория>
cd AuchanMCP
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Запуск

```bash
source .venv/bin/activate
python src/mcp_server.py
```

### Подключение в Claude Code

В репозитории уже есть `.mcp.json` — после установки зависимостей сервер
`auchan-ro` должен подключиться автоматически при открытии проекта.

## Проверка на реальном списке покупок

```bash
source .venv/bin/activate
python scripts/test_shopping_list.py
```

Прогоняет ~34 позиции реального списка покупок через `find_product_or_analog`.
Текущий результат: **28 точных совпадений, 6 аналогов, 0 полных промахов**.
Разбор проблемных случаев (лексическая многозначность румынского, товары,
снятые с продажи) — в `docs/API_NOTES.md`.

## Авторизация (опционально)

Поиск и корзина работают без логина — для задачи "найти товар / собрать
корзину" авторизация не нужна вообще. Логин на auchan.ro идёт через
OAuth-мост на Salesforce Experience Cloud, а не через обычный VTEX ID,
поэтому для функций, которым всё же нужен аккаунт (история заказов, My CLUB,
кросс-девайсная корзина), используется разовый логин в браузере с
переиспользованием cookies, а не эмуляция логина запросами — подробности и
почему именно так в ADR-0002 (`docs/DECISIONS.md`):

```bash
pip install playwright && playwright install chromium
python scripts/login_helper.py
```

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

```
src/
  auchan_api.py   — HTTP-клиент к VTEX Catalog System + Checkout API
  matcher.py      — подбор товара под текстовое описание + поиск аналога
  mcp_server.py   — MCP-сервер (stdio), оборачивает клиент в инструменты
scripts/
  test_shopping_list.py — прогон по реальному списку покупок
  login_helper.py        — разовый логин в браузере -> storage_state.json
docs/
  API_NOTES.md    — разведка API, эндпоинты, авторизация, известные ограничения
  DECISIONS.md     — журнал архитектурных решений (ADR)
```

## Известные ограничения

- Румынский язык лексически многозначен ("roșii" — и "помидоры", и "красные")
  — однословные запросы без контекста могут промахнуться на похожем слове.
- Пара позиций из тестового списка покупок пропала из каталога между датой
  составления списка и разведкой API — это не баг подбора, товар реально
  снят с продажи.
- `login_helper.py` написан, но не прогонялся end-to-end — требует
  установки `playwright` отдельно от основных зависимостей.

Подробнее — в `docs/API_NOTES.md`.

## Лицензия

[MIT](LICENSE).