fetch_reviews

Instructions

Implementation Reference

• mcp_server/tools.py:92-116 (handler)

  The core implementation of fetch_reviews: validates the ASIN, runs fetch.sh via _run_script, parses the JSON output, and returns the {reviews, meta} envelope.

  def fetch_reviews(asin: str, market: str = "US", limit: int = 100) -> dict[str, Any]:
      """Fetch raw Amazon reviews via the Shulex VOC API, no analysis."""
      asin = _validate_asin(asin)
      if limit < 1 or limit > 1000:
          raise ValueError(f"limit must be 1-1000, got {limit}")
  
      with tempfile.NamedTemporaryFile(
          prefix="mcp_fetch_", suffix=".json", delete=False, mode="w"
      ) as tmp:
          out_path = tmp.name
      try:
          _run_script(
              "fetch.sh",
              [asin, "--limit", str(limit), "--market", market, "--output", out_path],
          )
          with open(out_path, "r", encoding="utf-8") as f:
              data = json.load(f)
          # fetch.sh's output shape is already `{reviews: [...], meta: {...}}` —
          # pass through unchanged.
          return data
      finally:
          try:
              os.unlink(out_path)
          except OSError:
              pass

• mcp_server/server.py:27-48 (registration)

  Registers fetch_reviews as an MCP tool via @mcp.tool() decorator; delegates to tools.fetch_reviews.

  @mcp.tool()
  def fetch_reviews(asin: str, market: str = "US", limit: int = 100) -> dict:
      """Fetch raw Amazon reviews for an ASIN via the Shulex VOC API.
  
      No analysis — returns the raw review array plus metadata. Use this when
      you want to plug reviews into your own analysis pipeline, or when you
      plan to call `analyze_reviews` later (avoids paying the Shulex API
      twice).
  
      Args:
          asin: 10-character Amazon product ID (e.g. "B08N5WRWNW").
          market: Market code (US, GB, DE, FR, IT, ES, JP, AU, CA, MX) or
              amazon.* domain ("amazon.co.uk"). Default: US.
          limit: Number of reviews to fetch (1-1000). Default: 100.
  
      Returns:
          {
            "reviews": [{rating, title, body, date, verified, ...}, ...],
            "meta": {asin, market, total_available, fetched}
          }
      """
      return tools.fetch_reviews(asin=asin, market=market, limit=limit)

• mcp_server/schemas.py:33-35 (schema)

  FetchResult Pydantic model defining the output schema (reviews list + meta).

  class FetchResult(BaseModel):
      reviews: list[Review]
      meta: FetchMeta

• mcp_server/schemas.py:26-30 (schema)

  FetchMeta Pydantic model for the meta field in the fetch result.

  class FetchMeta(BaseModel):
      asin: str
      market: str
      total_available: int = 0
      fetched: int = 0

• mcp_server/tools.py:37-47 (helper)

  Helper _validate_asin used by fetch_reviews to normalize and validate ASIN input.

  def _validate_asin(asin: str) -> str:
      """Validate ASIN shape. We accept lowercase from MCP clients but normalize
      to upper before passing to the shell scripts (which warn but proceed on
      lowercase) — this keeps our error messages clearer.
      """
      asin = asin.strip().upper()
      if not VALID_ASIN_RE.match(asin):
          raise ValueError(
              f"invalid ASIN {asin!r}: must be 10 alphanumeric characters (e.g. B08N5WRWNW)"
          )
      return asin