amazon-lyr

Una sesión de agente, de principio a fin

Esta es una conversación real con un agente ejecutando amazon-lyr — sin pasos ocultos:

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

Cada paso es una llamada de herramienta MCP tipada. El paso de compra es deliberadamente difícil de activar por accidente — ver Modelo de seguridad.

Related MCP server: Amazon Cart MCP Server

Por qué es diferente

Cómo funciona

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

La autenticación es tu propia sesión: amazon-lyr login importa cookies de Chrome, Brave, Firefox, Edge o Zen a través de obscura-core, o de una exportación JSON explícita. Las lecturas necesitan el token de inicio de sesión; el carrito, los pedidos, las devoluciones y el checkout también necesitan las cookies de contexto de sesión.

Instalación

# 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

Luego autentícate una vez y sirve:

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"]
    }
  }
}

Herramientas (21)

Modelo de seguridad

El dinero pasa por exactamente dos puertas:

1. Puerta de sesión — cada mutación requiere cookies de inicio de sesión completas (at-main + session-id/ubid-main). Las sesiones de solo lectura se rechazan antes de realizar cualquier solicitud.

2. Puerta de consentimiento — place_order se niega a ejecutarse a menos que se le pase el literal exacto confirm="PLACE_ORDER". El flujo previsto es: vista previa para el usuario → el usuario aprueba → luego pasar el literal. cancel_order e initiate_return están igualmente anotados como destructivos/no idempotentes para que los marcos de agentes los traten en consecuencia.

La verificación de tarjeta (OTP / 3-D Secure) se detecta a mitad del checkout y se informa como needs_verification con instrucciones del navegador — nunca se adivina.

Límites

Límites honestos, todos aparecen como errores tipados en lugar de datos incorrectos:

• Muros CAPTCHA — las páginas del área de cuenta son más estrictas que el catálogo; vuelve a importar cookies frescas o espera (CaptchaError incluye pistas)

• Limitaciones suaves — las cadencias de menos de 3 segundos obtienen cuadrículas vacías silenciosas; las respuestas llevan possibly_throttled: true cuando se sospecha

• Variantes de precio geográficas — algunas variantes renderizan los precios en el cliente; la búsqueda recurre al escaneo de texto, get_product sigue siendo autoritativo

• Sin compra automática sin consentimiento — por diseño; el checkout exige el literal de confirmación explícito y la aprobación del usuario

Desarrollo

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

Las notas de arquitectura, los invariantes y el proceso de lanzamiento viven en AGENTS.md.

Licencia

MIT © Ishan Parihar