amazon-lyr: Instructions file for Codex

AGENTS.md — Agent Developer Guide for amazon-lyr

Project Overview

• Project: amazon-lyr — Amazon research & shopping MCP server + CLI (search, product details, reviews, cart, orders)
• Language: Python 3.11+
• Package Manager: uv
• Repository: https://github.com/ishan-parihar/amazon-lyr
• Family: part of the -lyr series (reddit-lyr, twitter-lyr, threads-lyr…) — browser-cookie auth, no official API keys

Build, Lint, and Test Commands

uv sync --extra dev          # install deps
uv run ruff check .          # lint
uv run ruff format --check . # format check
uv run pytest -q             # tests (no live Amazon calls; fixtures only)
uv run amazon-lyr            # CLI home view
uv run amazon-lyr serve      # MCP server (stdio)

Run one test: uv run pytest tests/test_parsers.py::test_parse_search -v

(Commands reviewed 2026-10-19: the section above still holds the commands that build and test this repo.)

Code Style

• Line length 100; ruff rules E/F/I/B/UP (see pyproject)
• from __future__ import annotations at top of all modules
• snake_case functions, PascalCase classes, UPPER_SNAKE constants
• Custom exceptions in exceptions.py, base AmazonError(RuntimeError)
• Tools wrap client calls in try/except → handle_api_error(e) (returns NoReturn)
• Read tools annotated {"readOnlyHint": True}; destructive ones set destructiveHint

Architecture

amazon_lyr/
├── cli_main.py        # argparse entry; subcommands; TOON default output
├── cli_actions.py     # command dispatch + TOON/JSON formatting
├── server.py          # create_mcp_server() — FastMCP assembly
├── dependencies.py    # singleton AmazonClient accessor
├── authentication.py  # validate_session / get_auth_status
├── cookie_import.py   # obscura-core extractor (optional extra) / JSON file
├── session_state.py   # cookie persistence (~/.config/amazon-lyr/cookies.json)
├── constants.py       # endpoints, captcha markers, retry policy
├── exceptions.py, error_handler.py, ratelimit.py, logging_config.py
├── scraping/
│   ├── api_client.py  # curl_cffi chrome impersonation; captcha/signin detection;
│   │                  #   ASIN/order-id validation; return/cancel wizards
│   └── parsers.py     # HTML → normalized dicts (bs4, defensive) + review insights
└── tools/
    ├── search.py, product.py               # reads (readOnlyHint=True)
    ├── reviews.py                           # get_reviews / insights / keyword scan
    ├── shopping.py                          # cart (incl. qty updates)/wishlist/get_orders
    ├── order_mgmt.py                        # details/tracking/returns/cancellation
    └── session.py                           # auth status tool