Arya-Ankit03/Minecraft-MCP

Amazon-MCP

A Model-Context Protocol (MCP) server design for Amazon product discovery and comparison. This project helps an intelligent agent retrieve, compare, and rank Amazon products (price, ratings, descriptions) to answer user queries like "best dog food for my labrador".

Goals

• Provide an MCP server that accepts natural-language product queries.
• Retrieve product data from Amazon (via python-amazon-product-api or Amazon Product Advertising API v5).
• Compare and rank products by price, rating, review count, description relevance, and configurable weights.
• Return structured results with explanation (why a product was chosen).

Contract (inputs / outputs)

• Input: HTTP POST or GET with fields:

  • query (string, required) — natural language query (e.g. "best dog food for my labrador").
  • category (string, optional) — e.g. pet-supplies.
  • max_results (int, optional) — default 10.
  • filters (object, optional) — e.g. max_price, min_rating.
  • weights (object, optional) — custom weighting for price/rating/reviews/relevance.

• Output: JSON list of ranked products. Each item:

  • asin, title, price (normalized), currency, rating, review_count, url, thumbnail, score, explanation (why it's recommended)

Error modes:

• 400 for missing query.
• 502/503 for third-party API failures, with graceful fallback and retry hints.

High-level architecture

• MCP Agent (user-facing LLM context) -> MCP Server (this repo) -> Amazon data layer
• Components:
  • API server (FastAPI / Flask) that exposes endpoints for search and compare.
  • Amazon integration module that queries Amazon Product APIs (search, lookup).
  • Ranking module that scores products using normalized metrics.
  • Cache layer (Redis or in-memory LRU) to reduce API calls and respect rate limits.
  • Optional: embeddings/cosine-similarity service for description relevance.

Data sources & libraries

• Primary: Amazon Product Advertising API (PA-API v5). Many Python wrappers exist; python-amazon-product-api can be used if it suits your region and credentials.
• Alternative: scraping (not recommended; violates ToS) or partner APIs.
• Suggested Python libraries:
  • FastAPI (server)
  • requests or httpx
  • python-amazon-product-api or PA-API wrapper
  • pydantic for schemas
  • redis (optional caching)
  • pytest for tests

Search & comparison strategy

1. Query parsing: extract keywords, optional constraints (e.g., "for my labrador", "grain-free").
2. Multi-method retrieval:
   • Keyword search (PA-API search by keywords + category)
   • Category + attribute filters
   • Lookup by top candidate ASINs for full details
3. Normalize numeric fields:
   • Price: normalized into a 0-1 score (lower price -> higher score, or invert depending on preference)
   • Rating: normalized (0-5 -> 0-1)
   • Review count: log-normalize then scale to 0-1
4. Relevance: compute text-similarity between product title/description and query (optional embeddings or simple token overlap)
5. Composite scoring: score = w_priceP + w_ratingR + w_reviewsV + w_relevanceRel
   • Provide default weights but allow overrides.
6. Return top-N with explanation (which factors contributed most).

Example flow: "best dog food for my labrador"

1. Server receives query.
2. Parse "dog food" + "labrador" (large-breed, adult?)
3. Run search on Amazon with keywords and category pet-supplies.
4. For top 50 candidates, fetch full details and pricing.
5. Compute normalized scores and rank products.
6. Return top 5 results with explanation, e.g.:

{ "results": [ { "asin": "B012345678", "title": "Premium Large Breed Adult Dog Food - Chicken", "price": 29.99, "currency": "USD", "rating": 4.7, "review_count": 12500, "score": 0.92, "explanation": "High rating (4.7) and many reviews; price is competitive; tailored to large breeds" } ] }

Quick setup (developer)

1. Clone the repo into D:\Coding\MCP_Project (already your workspace).
2. Create a virtualenv and install dependencies.

On Windows PowerShell:

python -m venv .venv; .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install fastapi uvicorn httpx pydantic python-amazon-product-api redis pytest

3. Create a config/.env (or use environment variables) with Amazon credentials:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• PAAPI_ASSOCIATE_TAG
• PAAPI_REGION (e.g., us-east-1)

4. Start the dev server:

uvicorn src.server:app --reload --port 8000

API endpoints (suggested)

• GET /health
• GET /search?query=best+dog+food+for+labrador&max_results=5&category=pet-supplies
• POST /search (JSON body for more options)
• GET /product/{asin}

Example request:

GET /search?query=best+dog+food+for+labrador&max_results=5

Example successful response: JSON list described earlier.

Implementation notes & best practices

• Respect Amazon PA-API rate limits: add retries with exponential backoff and caching.
• Use batching: retrieve details for multiple ASINs in fewer calls if API supports it.
• Cache search results for short TTL (e.g., 10–60 minutes) to avoid hitting rate limits.
• Normalize currencies if supporting multiple locales.
• For description relevance, start with lightweight token overlap and upgrade to embeddings later.
• Be transparent about data freshness and price variance.

Edge cases

• No results: return an empty results list and suggestions (loosen filters).
• Partial failures: return best-effort results and a warnings field explaining failures.
• Very large item sets: paginate and limit number of detail fetches (configurable).

Tests & quality gates

• Unit tests for:
  • Search parameter parsing
  • Price/rating normalization
  • Scoring function (happy path + edge cases: equal scores, missing data)
• Integration tests (mock Amazon API) for the retrieval pipeline.
• CI: run tests and lint on PRs.

Security & credentials

• Never commit your Amazon keys. Use environment variables or a secrets manager.
• Limit logs that contain PII or secret tokens.

Future improvements

• Multi-source price comparison (Walmart, Chewy, eBay) to find best overall value.
• Price history and deal detection.
• UI or chat frontend for real-time conversation with the MCP.
• Embedding-based semantic matching for better relevance.

Next steps (recommended MVP implementation order)

1. Scaffold FastAPI server and config.
2. Implement Amazon PA-API integration and an adapter layer.
3. Implement ranking/scoring module with default weights.
4. Add caching and rate-limit handling.
5. Add tests and docs.