amazon-lyr

Сессия агента от начала до конца

Это один реальный разговор с агентом, работающим с amazon-lyr — без скрытых шагов:

1. search_products("noise cancelling headphones", max_price=300, min_rating=4)
2. review_insights("B0X1234567")            # star spread + keyword themes
3. search_in_reviews("B0X1234567", query="broke")     # what actually breaks?
4. add_to_cart("B0X1234567", quantity=1)
5. checkout_preview()                        # totals + address + payment, nothing bought
6. place_order(confirm="PLACE_ORDER")       # only after the user said "buy it"
   ✓ order placed · #111-2223334-5556667
7. track_shipment("111-2223334-5556667")
8. initiate_return("111-2223334-5556667", reason="defective", asin_hint="…")
9. list_returns()                           # refund status confirmed

Каждый шаг — это типизированный вызов MCP-инструмента. Шаг покупки намеренно сложно активировать случайно — см. Модель безопасности.

Related MCP server: Amazon MCP Server

В чём отличие

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

browser cookies ──▶ AmazonClient (curl_cffi, captcha-aware)
                        │
                        ▼
              bs4 parsers ──▶ normalized dicts ──▶ 21 FastMCP tools
                                                   (readOnly / destructive annotations)

Авторизация — это ваша собственная сессия: amazon-lyr login импортирует куки из Chrome, Brave, Firefox, Edge или Zen через obscura-core или из явного JSON-экспорта. Для чтения нужен токен входа; для корзины, заказов, возвратов и оформления также нужны куки контекста сессии.

Установка

# Persistent install — uv tool (isolated; bootstraps uv on clean systems)
curl -sSL https://raw.githubusercontent.com/ishan-parihar/amazon-lyr/main/install.sh | bash

# Zero-install run without persistence:
uvx --from git+https://github.com/ishan-parihar/amazon-lyr amazon-lyr --version

Затем выполните аутентификацию один раз и запустите сервер:

amazon-lyr login --browser chrome            # or: --cookies-file cookies.json
amazon-lyr search "mechanical keyboard"      # shell works immediately
amazon-lyr serve                             # MCP server (stdio)

{
  "mcpServers": {
    "amazon": {
      "command": "amazon-lyr",
      "args": ["serve"]
    }
  }
}

Инструменты (21)

Модель безопасности

Денежные операции проходят ровно через два шлюза:

1. Шлюз сессии — каждая мутация требует полных куки входа (at-main + session-id/ubid-main). Сессии только для чтения отклоняются до выполнения любого запроса.

2. Шлюз согласия — place_order отказывается выполняться, если не передана точная литеральная строка confirm="PLACE_ORDER". Предполагаемый поток: предпросмотр для пользователя → пользователь одобряет → затем передаётся литерал. cancel_order и initiate_return аналогично помечены как деструктивные/неидемпотентные, чтобы агентные фреймворки обрабатывали их соответствующим образом.

Проверка карты (OTP / 3-D Secure) обнаруживается в процессе оформления заказа и сообщается как needs_verification с инструкциями для браузера — никогда не обходится угадыванием.

Ограничения

Честные пределы, все отображаются как типизированные ошибки вместо неверных данных:

• CAPTCHA-стены — страницы в личном кабинете строже, чем каталог; повторно импортируйте свежие куки или подождите (CaptchaError содержит подсказки)

• Мягкие ограничения — при интервалах менее 3 секунд возвращаются пустые сетки без ошибок; ответы содержат possibly_throttled: true при подозрении

• Гео-варианты цен — некоторые варианты отображают цены на стороне клиента; поиск переключается на сканирование текста, get_product остаётся авторитетным

• Нет автопокупки без согласия — по дизайну; оформление требует явного литерала подтверждения и одобрения пользователя

Разработка

git clone https://github.com/ishan-parihar/amazon-lyr && cd amazon-lyr
uv sync --extra dev
uv run ruff check . && uv run pytest -q

Заметки по архитектуре, инварианты и процесс релиза находятся в AGENTS.md.

Лицензия

MIT © Ishan Parihar