# yandex-eda-mcp

MCP-сервер для **Яндекс Еды** на базе [Playwright](https://playwright.dev) (headless).
Позволяет из любого MCP-клиента (Claude Desktop, Claude Code и т.п.):

- проверять статус авторизации;
- задавать адрес доставки;
- искать рестораны и смотреть меню;
- собирать корзину;
- оформлять заказ (с защитой от случайного подтверждения).

Работает через **персистентный профиль Chromium**: вы логинитесь один раз в
видимом браузере, дальше сервер ходит на сайт headless в том же профиле.

Профиль хранится **вне папки с кодом** — в `~/.yandex-eda-mcp/profile`, поэтому
переживает обновления кода и работает даже при запуске через `npx`.

---

## Установка

### Вариант A — через npx (без клонирования, рекомендуется)

Клонировать и собирать ничего не нужно. Нужен только **Node.js ≥ 20**.
Пропишите сервер в конфиг MCP-клиента:

```json
{
  "mcpServers": {
    "yandex-eda": {
      "command": "npx",
      "args": ["-y", "yandex-eda-mcp"]
    }
  }
}
```

Или одной командой через CLI Claude Code (сразу в user-scope — сервер доступен
в любой сессии, а не только в текущей папке):

```bash
claude mcp add -s user yandex-eda -- npx -y yandex-eda-mcp
```

При первом запуске `npx` сам скачает пакет и Chromium (~150 МБ, разово).
Вход в аккаунт Яндекса — автоматически при первом обращении к сайту (см. ниже).
Это единственная настройка: раздел «Подключение к MCP-клиенту» ниже нужен
только при установке из исходников (Вариант B).

### Вариант B — из исходников

```bash
git clone <repo> && cd yandex-eda-mcp
npm install          # ставит зависимости, Chromium и собирает dist/ (скрипт prepare)
```

Отдельный `npm run build` больше не нужен — сборка идёт автоматически при
`npm install` (скрипт `prepare`).

## Авторизация — автоматически при первом использовании

Как только вы впервые обратитесь к
сайту (например, `search_restaurants`), сервер сам увидит, что профиль не
авторизован, и **откроет видимое окно браузера** для входа. Войдите в свой
аккаунт Яндекса (логин/пароль/SMS/капча), окно закроется само, дальше всё
работает headless. Вход нужен один раз на компьютере.

Можно и явно — вызвав MCP-инструмент `login` (или из терминала `npm run login`).

> Профиль и авторизация индивидуальны для каждого пользователя: чужую сессию
> шарить нельзя, каждый входит в свой аккаунт.

## Подключение к MCP-клиенту (только для установки из исходников, Вариант B)

Если вы поставили сервер через `npx` (Вариант A) — этот раздел пропустите,
настройка уже готова. При установке из исходников укажите путь к собранному
`dist/index.js`:

```json
{
  "mcpServers": {
    "yandex-eda": {
      "command": "node",
      "args": ["/абсолютный/путь/к/yandex-eda-mcp/dist/index.js"]
    }
  }
}
```

Через CLI:

```bash
claude mcp add yandex-eda -- node /абсолютный/путь/к/yandex-eda-mcp/dist/index.js
```

---

## Инструменты (MCP tools)

| Инструмент | Назначение |
|---|---|
| `login_status` | Проверить, авторизован ли профиль |
| `login` | Открыть окно входа в Яндекс (обычно вызывается сам) |
| `get_address` | Текущий адрес доставки (метка «Дом» или улица) |
| `list_saved_addresses` | Сохранённые в аккаунте адреса (с подъездом/квартирой) |
| `set_address` | Задать адрес: сперва ищет среди сохранённых, иначе новый по карте |
| `search_restaurants` | Поиск ресторанов / каталог |
| `get_menu` | Меню ресторана по URL или slug |
| `add_to_cart` | Добавить блюдо в корзину (навигация по категории → карточка → модалка) |
| `view_cart` | Показать корзину и сумму |
| `list_payment_methods` | Способы оплаты (карты/Карта Пэй/СБП) и текущий выбранный |
| `place_order` | Оформить заказ (по умолчанию dry-run; выбор оплаты через `payment`) |
| `navigate` | Перейти по пути/URL внутри сайта |
| `debug_snapshot` | URL + текст + скриншот страницы для отладки |

### Сохранённые адреса

`set_address` по умолчанию сначала ищет совпадение среди адресов, уже
сохранённых в аккаунте Яндекс Еды (по метке или улице), и выбирает его
**мгновенно, сохраняя квартиру/подъезд/этаж** — без повторного тыканья по карте.

```
set_address «домой»        → выбирает сохранённый «Дом» со всеми деталями
set_address «на работу»    → выбирает сохранённый «На работу»
set_address «Казань, Баумана 10» → нет в сохранённых → вводит новый по карте
```

Посмотреть список — `list_saved_addresses`. Форсировать ввод нового адреса
(минуя сохранённые) — `set_address` с `preferSaved: false`.

### Безопасность оформления заказа

`place_order` по умолчанию работает в режиме **dry-run**: доходит до кнопки
«Оформить заказ», но НЕ нажимает её и не списывает деньги. Чтобы реально
оформить заказ, нужно явно передать `confirm: true`.

Типичный сценарий:

1. `set_address` → «домой» (или «Москва, Тверская 1»)
2. `search_restaurants` → «пицца»
3. `get_menu` → выбранный ресторан
4. `add_to_cart` → нужные блюда
5. `view_cart` → проверить состав и сумму
6. `place_order` (dry-run) → убедиться, что всё готово
7. `place_order` с `confirm: true` → оформить

### Оплата и выбор карты

`list_payment_methods` показывает доступные способы (карты, «Карта Пэй», СБП) и
текущий выбранный. Выбрать способ на оформлении можно параметром `payment` у
`place_order` (напр. `payment: "Карта Пэй"`).

> **Важно:** оплата через **СБП** требует ручного подтверждения в приложении
> банка, поэтому автоматически заказ по ней НЕ оформится (Яндекс создаёт заказ и
> отменяет его без оплаты). Для автоматического оформления выбирайте **карту**
> (`payment: "Карта Пэй"` или добавьте карту в аккаунте).

---

## Переменные окружения

| Переменная | По умолчанию | Описание |
|---|---|---|
| `YANDEX_EDA_HEADLESS` | `1` | `0`/`false` — показывать браузер |
| `YANDEX_EDA_AUTO_LOGIN` | `1` | `0` — не открывать окно входа автоматически |
| `YANDEX_EDA_LOGIN_TIMEOUT` | `180000` | Сколько ждать входа в окне, мс |
| `YANDEX_EDA_DATA_DIR` | `~/.yandex-eda-mcp` | Каталог данных (профиль + скриншоты) |
| `YANDEX_EDA_PROFILE` | `<DATA_DIR>/profile` | Каталог профиля с авторизацией |
| `YANDEX_EDA_SCREENSHOT_DIR` | `<DATA_DIR>/screenshots` | Куда сохранять скриншоты |
| `YANDEX_EDA_BASE_URL` | `https://eda.yandex.ru` | Базовый URL |
| `YANDEX_EDA_TIMEOUT` | `30000` | Таймаут ожиданий, мс |
| `YANDEX_EDA_USER_AGENT` | Chrome 131 | User-Agent |

---

## Обслуживание селекторов

Яндекс использует хешированные CSS-классы, поэтому данные читаются в первую
очередь из **внутреннего JSON-API** сайта (перехват сетевых ответов) — это
устойчиво к смене вёрстки. Действия (адрес, корзина, кнопки) выполняются по
DOM-селекторам, собранным в `src/eda.ts` → `SELECTORS` и `API`.

Если что-то перестало работать:

1. Вызовите `debug_snapshot` — получите текст и скриншот текущей страницы.
2. Подправьте нужные селекторы/паттерны в `src/eda.ts`.
3. `npm run build`.

---

## Дисклеймер

Проект автоматизирует **ваш собственный** аккаунт для личного использования.
Соблюдайте условия использования Яндекс Еды. Автор не несёт ответственности за
списания и заказы, совершённые автоматизацией.