# hermes-marketplace-tools

Тулы поиска/сравнения товаров на **Wildberries** (и **Ozon** — в планах) для агента
[Hermes](https://hermes-agent.nousresearch.com). Подключаются как MCP-сервер.
Сравнение и рекомендации делает сам LLM — тулы только отдают нормализованные данные.

Статус: **Wildberries и Ozon — готовы оба** (search/card/reviews на каждом).
Один запрос `marketplace="all"` ищет на обоих. См. `SPEC.md`.

## Тулы

| Тул | Что делает |
|---|---|
| `marketplace_search` | поиск товаров → нормализованная выдача (цена, рейтинг, отзывы, ссылка, превью) |
| `get_product_card` | полная карточка: характеристики, описание, URL картинок |
| `get_reviews` | отзывы (сортировка по полезности/свежести) |

## Установка

```bash
git clone <repo> hermes-marketplace-tools
cd hermes-marketplace-tools
uv venv && uv pip install -e .
uv run python -m camoufox fetch   # бинарь Firefox для Ozon (~300 МБ, разово)
```

> Ozon ходит через headless-браузер (camoufox). WB работает по HTTP и браузера не требует.
> `playwright` запинен на 1.50.0 — новее ломает протокол с firefox-сборкой camoufox.

## Конфигурация

Прокси (SOCKS5, RU-IP) задаётся переменной окружения `PROXY_URL`. **Не коммить креды.**

```bash
export PROXY_URL="socks5h://USER:PASS@pool.proxy.market:10000"
```

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

В `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  marketplace:
    command: "/path/to/hermes-marketplace-tools/.venv/bin/python"
    args: ["-m", "mcp_server.server"]
    env:
      PROXY_URL: "socks5h://USER:PASS@pool.proxy.market:10000"
```

После правки конфига **перезапусти Hermes** — MCP-серверы загружаются на старте.
Тулы появятся как `mcp_marketplace_marketplace_search` и т.д.

## Локальный прогон (без Hermes)

```bash
PROXY_URL="socks5h://..." .venv/bin/python -m mcp_server.server   # запустит MCP по stdio
```

Для проверки логики ядра — см. `marketplace_core` (можно импортировать `MarketplaceService`
напрямую; так же его будет использовать будущий Telegram-бот).

## Заметки по WB (важно при поломках)

- Весь трафик идёт через прокси (RU-IP); цены приходят в копейках.
- `card.wb.ru/v4` отдаёт 403 на TLS-профиль Chrome — клиент использует `impersonate="safari"`.
- URL картинок собираются по схеме `basket-{NN}.wbbasket.ru/...`; номер `NN` подбирается
  self-healing и кэшируется в `~/.hermes/marketplace_cache.sqlite`.
- Эндпоинты WB неофициальные и иногда меняют версии — см. `SPEC.md` (Приложение A).