hermes-marketplace-tools

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

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

Тулы

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

Установка

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. Не коммить креды.

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

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

В ~/.hermes/config.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)

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).