amazon-lyr

Eine Agenten-Sitzung, von Anfang bis Ende

Dies ist ein echtes Gespräch mit einem Agenten, der amazon-lyr ausführt — keine Schritte verborgen:

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

Jeder Schritt ist ein typisierter MCP-Tool-Aufruf. Der Kaufs-Schritt ist absichtlich schwer versehentlich auszulösen — siehe Sicherheitsmodell.

Related MCP server: Amazon Cart MCP Server

Warum es anders ist

So funktioniert es

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

Die Authentifizierung ist deine eigene Sitzung: amazon-lyr login importiert Cookies aus Chrome, Brave, Firefox, Edge oder Zen über obscura-core, oder aus einem expliziten JSON-Export. Lesezugriffe benötigen das Login-Token; Warenkorb, Bestellungen, Retouren und Checkout benötigen zusätzlich die Sitzungskontext-Cookies.

Installation

# 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

Dann einmal authentifizieren und bereitstellen:

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

Werkzeuge (21)

Sicherheitsmodell

Geld bewegt sich durch genau zwei Tore:

1. Sitzungs-Gate — jede Änderung erfordert vollständige Login-Cookies (at-main + session-id/ubid-main). Nur-Lese-Sitzungen werden abgelehnt, bevor eine Anfrage gestellt wird.

2. Zustimmungs-Gate — place_order weigert sich auszuführen, es sei denn, das exakte Literal confirm="PLACE_ORDER" wird übergeben. Der vorgesehene Ablauf ist: Vorschau für den Benutzer → Benutzer genehmigt → dann das Literal übergeben. cancel_order und initiate_return sind ähnlich als destruktiv/nicht-idempotent annotiert, damit Agenten-Frameworks sie entsprechend behandeln.

Kartenverifizierung (OTP / 3-D Secure) wird während des Checkouts erkannt und als needs_verification mit Browser-Anweisungen gemeldet — niemals durchgeraten.

Grenzen

Ehrliche Obergrenzen, alle als typisierte Fehler statt falscher Daten gemeldet:

• CAPTCHA-Wände — Seiten im Kontobereich sind strenger als der Katalog; importiere frische Cookies erneut oder warte ab (CaptchaError enthält Hinweise)

• Sanfte Drosselungen — Rhythmen unter 3 Sekunden führen zu stillen leeren Rastern; Antworten tragen possibly_throttled: true, wenn dies vermutet wird

• Geo-Preisvarianten — einige Varianten rendern Preise clientseitig; die Suche fällt auf Text-Scanning zurück, get_product bleibt maßgeblich

• Kein automatischer Kauf ohne Zustimmung — von Design her; der Checkout verlangt das explizite Bestätigungs-Literal und die Zustimmung des Benutzers

Entwicklung

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

Architekturnotizen, Invarianten und der Release-Prozess befinden sich in AGENTS.md.

Lizenz

MIT © Ishan Parihar