Metadata-Version: 2.5
Name: amazon-india-seller-mcp
Version: 0.2.1
Summary: Amazon India product research MCP server for beginner sellers (stdio transport, Claude Desktop ready)
Project-URL: Homepage, https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp
Project-URL: Repository, https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp
Project-URL: Issues, https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp/issues
Project-URL: Documentation, https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp/tree/main/docs
Author: Suriya Ravichandran
License-Expression: MIT
License-File: LICENSE
Keywords: amazon,amazon-india,claude,ecommerce,mcp,model-context-protocol,product-research,seller-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: sqlalchemy>=2.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Requires-Dist: selectolax>=0.3.21; extra == 'browser'
Provides-Extra: realtime
Requires-Dist: ddgs>=9.15.0; extra == 'realtime'
Requires-Dist: pytrends>=4.9; extra == 'realtime'
Description-Content-Type: text/markdown

# Amazon India Product Research MCP

[![CI](https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp/actions/workflows/ci.yml)
[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/amazon-india-seller-mcp.svg)](https://pypi.org/project/amazon-india-seller-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-stdio-purple.svg)](https://modelcontextprotocol.io)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Security policy](https://img.shields.io/badge/security-policy-red.svg)](SECURITY.md)
[![Release](https://img.shields.io/github/v/release/Suriya-Ravichandran/amazon-india-seller-mcp?sort=semver)](https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp/releases)

An MCP (Model Context Protocol) server that turns Claude Desktop into a product research
assistant for **beginner Amazon India sellers**. It scores product opportunities, estimates
demand, sizes up competition, calculates real Amazon India profitability, plans sourcing,
mines customer complaints, researches keywords and drafts a full listing.

Runs over **stdio**, so it plugs straight into Claude Desktop.

> **New here? Start with the [Setup & Run Guide](docs/SETUP.md)** — step-by-step installation,
> verification and Claude Desktop configuration, with a troubleshooting section.
> For live data, see the [Live Data & Scraping Guide](docs/SCRAPING.md).

**24 tools. Works with zero API keys** — in demo mode offline, or on real live data
from free sources (Google Trends, DuckDuckGo, public amazon.in pages).

---

## Project Overview

The server is built around one seller profile:

| Criterion | Target |
|---|---|
| Investment | ₹5,000 – ₹20,000 |
| Selling price | ₹199 – ₹699 |
| Weight | under 500 g |
| Profit margin | 30% minimum |
| Demand | daily use, non-seasonal |
| Returns | low return rate |
| Sourcing | easy Indian sourcing |
| Risk | no obvious gating or brand-approval problems |

Every tool scores products against these criteria and penalises the things that sink new
sellers: branded goods, counterfeit risk, fragile items, batteries, complex electronics,
perishables, seasonal products, apparel sizing, heavy items and categories dominated by
strong brands.

### Data integrity comes first

This project refuses to make up marketplace facts. Every meaningful output carries
`source`, `data_type`, `confidence` and `last_updated`, where `data_type` is one of
**Live**, **Verified**, **Estimated**, **Historical** or **Demo**.

- Demo data is always labelled `Demo` and never presented as live Amazon data.
- Demand and monthly sales figures are **modelled estimates**, never measured Amazon sales.
- Amazon fees come from a configurable schedule; the bundled one is labelled `Estimated`.
- **Suppliers are never invented.** Without a supplier API, `search_suppliers` returns an
  empty supplier list plus real, publicly known sourcing channels you can verify yourself.
- No tool ever claims guaranteed profit or guaranteed sales.

---

## Features

- **20 MCP tools** covering the full seller workflow: discovery, demand, competition,
  money, listing, sourcing and live data
- **Free live data, no API keys**: Google Trends search interest, DuckDuckGo web
  search, and public amazon.in pages including "bought in past month" badges
- **Revenue and sales estimation** from BSR curves or Amazon's own purchase badges,
  always as a range with the method stated
- **New-seller detection**: which competitors have low review counts, and which of
  those are already clearing 300+ units/month — the strongest signal a page is winnable
- **Evergreen scoring** from up to 5 years of real search interest, so you avoid
  seasonal dead stock
- **Amazon Ads planning**: break-even ACOS, bid ladders by match type, keyword match
  assignment, campaign structure and negative keywords — all derived from your own
  unit economics rather than generic advice
- 0–100 weighted opportunity scoring, plus batch screening of up to 15 ideas at once
- Amazon India fee maths: referral, closing, FBA / Easy Ship / Self Ship, GST on fees,
  return reserve, break-even and recommended price
- Launch planning: order quantity, budget split, ad budget, reorder point, payback
- Review complaint clustering with concrete supplier-level fixes
- Keyword research, listing draft and a seven-slot image plan
- Compliance-first scraping: robots.txt, allowlist, crawl delay, page budget, and a
  hard stop on bot challenges — **no bot-protection bypass**
- Research history stored in SQLite or PostgreSQL
- Full demo mode: everything works offline, deterministically

---

## Architecture

```text
amazon-india-seller-mcp/
│
├── amazon_india_seller_mcp/      # the installable package
│   ├── __init__.py
│   ├── __main__.py               # python -m amazon_india_seller_mcp
│   └── server.py                 # MCP entry point (stdio transport) - wiring only
│
├── server.py                     # compatibility shim: python server.py still works
│
├── amazon_india_seller_mcp/tools/                        # MCP tool definitions - thin: validate, call service, shape result
│   ├── __init__.py               # ServiceBundle + error-handling decorator
│   ├── product_research.py       # research_product
│   ├── demand_analysis.py        # analyze_product_demand
│   ├── competition.py            # analyze_competition
│   ├── profit_calculator.py      # calculate_profitability
│   ├── supplier_search.py        # search_suppliers
│   ├── review_analysis.py        # analyze_reviews
│   ├── keyword_research.py       # research_keywords
│   ├── listing_generator.py      # generate_listing
│   ├── revenue_calculator.py     # calculate_revenue
│   ├── competitor_analysis.py    # analyze_competitors
│   ├── purchase_signals.py       # analyze_purchase_signals
│   ├── review_metrics.py         # analyze_review_metrics
│   ├── evergreen_analysis.py     # analyze_evergreen
│   ├── product_images.py         # analyze_product_images
│   ├── opportunity_finder.py     # find_product_opportunities
│   ├── launch_planner.py         # plan_product_launch
│   ├── ppc_keywords.py           # suggest_ppc_keywords
│   ├── ppc_bidding.py            # calculate_ppc_bids / plan_ppc_campaign
│   ├── web_search.py             # search_web
│   ├── amazon_scraper.py         # scrape_amazon_search / scrape_amazon_product / scraper_status
│   └── listing_scraper.py        # scrape_listing_details
│
├── amazon_india_seller_mcp/services/                     # All business logic
│   ├── __init__.py               # Data envelopes, errors, cache, opportunity scoring
│   ├── amazon_service.py         # Provider abstraction (demo / scraper / API), snapshots, risk, reviews, listings
│   ├── trends_service.py         # Demand, trend direction, seasonality, keywords, live Google Trends
│   ├── supplier_service.py       # Sourcing research (never fabricates suppliers)
│   ├── pricing_service.py        # Fees, profit, margin, ROI, break-even, recommended price
│   ├── revenue_service.py        # Units from BSR/badges, revenue, competitor stage, evergreen scoring
│   ├── search_service.py         # Web search (DuckDuckGo free, Brave/Serper/Tavily/Google CSE)
│   ├── browser_service.py        # Guardrailed fetching: allowlist, robots.txt, delay, budget, block detection
│   ├── scraper_service.py        # Amazon India page parsing (search, product, listing detail, reviews, bestsellers)
│   ├── ads_service.py            # Sponsored Products bid maths, keyword match types, campaign structure
│   └── security.py               # SSRF guards, log redaction, prompt-injection scanning, size caps
│
├── amazon_india_seller_mcp/database/                     # Research history
│   ├── __init__.py
│   └── models.py                 # SQLAlchemy models + session handling
│
├── amazon_india_seller_mcp/config/                       # Centralised settings
│   ├── __init__.py
│   └── settings.py               # Env-driven settings + configurable fee schedule
│
├── tests/
│   ├── __init__.py
│   ├── test_product_research.py
│   ├── test_demand_analysis.py
│   ├── test_competition.py
│   └── test_profit_calculator.py
│
├── docs/
│   ├── SETUP.md                  # full setup, run and troubleshooting guide
│   ├── SCRAPING.md               # live data sources, guardrails and compliance
│   ├── PROMPTS.md                # copy-paste prompt library for all 20 tools
│   └── check_connection.py       # MCP connection self-test
│
├── .env.example
├── mcp.json.example
├── LICENSE                       # MIT
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md                   # threat model and controls
├── CHANGELOG.md
├── .github/workflows/ci.yml      # tests on Python 3.11-3.13
├── pyproject.toml                # Dependencies, managed by uv
└── uv.lock
```

Rules the code follows: `server.py` holds no business logic, tools hold no business logic,
services hold all of it.

---

## Installation

**Requirements:** Python 3.11+ and [uv](https://docs.astral.sh/uv/). The
[Setup & Run Guide](docs/SETUP.md) covers every step in detail.

### Use it without cloning anything

```bash
uvx amazon-india-seller-mcp
```

That is the whole install. Point Claude Desktop at it:

```json
{
  "mcpServers": {
    "amazon-india-seller": {
      "command": "uvx",
      "args": ["amazon-india-seller-mcp"],
      "env": { "DEMO_MODE": "true" }
    }
  }
}
```

### Or install it into an environment

```bash
uv tool install amazon-india-seller-mcp     # then run: amazon-india-seller-mcp
pip install amazon-india-seller-mcp         # works too
```

### Or work from a source checkout (for development)

```bash
git clone https://github.com/Suriya-Ravichandran/amazon-india-seller-mcp.git
cd amazon-india-seller-mcp
uv sync --all-extras
uv run python -m amazon_india_seller_mcp
```

Free live data needs the extras: `uv sync --extra realtime --extra browser`.

<details>
<summary>Installing uv</summary>

```bash
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or via pip
python -m pip install uv
```
</details>

### Virtual environment

`uv sync` manages the virtual environment for you; run commands with `uv run`. If you
prefer to activate it manually:

```bash
# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate
```

### Dependencies

Declared in `pyproject.toml` and pinned in `uv.lock`:

`mcp`, `pydantic`, `pydantic-settings`, `httpx`, `sqlalchemy`, `python-dotenv`; `pytest` in
the dev group.

Add or change a dependency with `uv add <package>` / `uv remove <package>` — never edit the
lockfile by hand.

---

## Environment Configuration

```bash
cp .env.example .env      # Windows: copy .env.example .env
```

| Variable | Default | Purpose |
|---|---|---|
| `APP_ENV` | `development` | Environment label |
| `DEBUG` | `false` | Verbose logging |
| `DATABASE_URL` | `sqlite:///./amazon_product_mcp.db` | SQLite or PostgreSQL URL |
| `PERSIST_RESEARCH` | `true` | Store research history |
| `AMAZON_API_KEY` / `AMAZON_API_SECRET` | empty | SP-API / PA-API credentials |
| `PRODUCT_DATA_PROVIDER` | `demo` | `demo`, `sp-api`, `pa-api` or a third-party API name |
| `PRODUCT_DATA_API_KEY` / `PRODUCT_DATA_BASE_URL` | empty | Third-party provider access |
| `GOOGLE_TRENDS_ENABLED` | `false` | Enable a trends provider (none ships with the project) |
| `SUPPLIER_API_KEY` / `SUPPLIER_API_BASE_URL` | empty | Supplier data provider |
| `DEMO_MODE` | `true` | Deterministic demo data, clearly labelled |
| `CACHE_ENABLED` / `CACHE_TTL_SECONDS` | `true` / `900` | In-process caching |
| `AMAZON_FEE_CONFIG_PATH` | empty | JSON file with your real Seller Central rate card |

Secrets live only in `.env`, which is gitignored. Nothing is hardcoded in the source.

---

## Database Setup

Tables are created automatically at startup. Nothing to run by hand.

**Development (default):** SQLite at `./amazon_product_mcp.db`.

**PostgreSQL:**

```bash
DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/amazon_mcp
```

JSON payload columns map to `JSONB` on PostgreSQL and `JSON` on SQLite automatically.
Install the driver alongside it: `uv add psycopg[binary]`.

Stored models: `ProductResearch`, `DemandAnalysis`, `CompetitionAnalysis`,
`ProfitCalculation`, `SupplierResearch` — each keeping `product_name`, `marketplace`,
`research_data`, `data_source`, `data_type`, `confidence`, `created_at`, `updated_at`.

History storage is best-effort: if the database is unreachable, tools still work and the
failure is logged rather than surfaced.

---

## Running the MCP

```bash
uvx amazon-india-seller-mcp              # installed
uv run python -m amazon_india_seller_mcp # from a checkout
uv run server.py                         # legacy path, still supported
```

The process speaks the MCP protocol over stdio, so it will sit there silently waiting for a
client — that is correct behaviour. Logs go to stderr, keeping stdout clean for protocol
traffic. Stop it with `Ctrl+C`.

---

## Claude Desktop Configuration

1. Open the Claude Desktop config file:
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Copy the `mcpServers` block from [`mcp.json.example`](mcp.json.example) into it,
   replacing the paths with your own **absolute** paths:

```json
{
  "mcpServers": {
    "amazon-product-research": {
      "command": "/ABSOLUTE/PATH/TO/amazon-india-seller-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/amazon-india-seller-mcp/server.py"],
      "env": { "DEMO_MODE": "true" }
    }
  }
}
```

On Windows use `.venv\\Scripts\\python.exe` and escape backslashes. A `uv --directory ... run
server.py` variant is also included in the example file.

3. **Fully quit and restart Claude Desktop** (close it from the tray/menu bar — reloading the
   window is not enough).
4. Test the connection: the tools appear in Claude Desktop's tool menu, and asking
   *"Calculate the profit for a ₹399 product that costs ₹120"* should trigger
   `calculate_profitability`.

---

## Available MCP Tools

### Discovery

| Tool | What it does |
|---|---|
| `find_product_opportunities` | Screen up to 15 product ideas at once against the beginner criteria and rank them. Start here. |
| `research_product` | Full opportunity report for one idea: category, price band, BSR, weight, rating, reviews, demand, competition, return / gating / brand risk, beginner fit, 0–100 score and recommendation |

### Demand

| Tool | What it does |
|---|---|
| `analyze_product_demand` | Monthly demand, demand level, trend direction, seasonality, confidence and a launch decision |
| `analyze_evergreen` | Evergreen score 0–100 from up to 5 years of real search interest: stability, flatness, demand floor, growth, plus inventory guidance |
| `analyze_purchase_signals` | Aggregates Amazon's own "X bought in past month" badges — the most reliable free sales signal there is |

### Competition

| Tool | What it does |
|---|---|
| `analyze_competition` | Competition level, price and rating averages, review barrier, brand dominance, listing and image quality, weak listings and differentiation openings |
| `analyze_competitors` | Per-competitor units, revenue, market share, market size and concentration. Flags **new sellers** (low reviews) and who clears **300+ units/month**, then gives an entry verdict |
| `analyze_review_metrics` | The review barrier: median and quartile review counts, months to catch up, and which listings are beatable |

### Money

| Tool | What it does |
|---|---|
| `calculate_profitability` | Referral, closing, fulfilment and GST fees, return reserve, total cost, profit, margin, ROI, break-even and recommended price, plus a plain-English explanation |
| `calculate_revenue` | Monthly and annual revenue from units, BSR or a purchase badge — as a range, with the method stated. Add `product_cost` for profit |
| `plan_product_launch` | Order quantity, budget split (inventory / samples / photography / ads / buffer), days of cover, reorder point, affordable ad cost, payback, week-by-week timeline and warnings |

### Listing

| Tool | What it does |
|---|---|
| `research_keywords` | Primary, secondary, long-tail and related keywords, search intent, priority, backend search terms and placement guidance |
| `generate_listing` | SEO title and alternatives, five bullets, description, backend terms, image direction, packaging advice and a compliance checklist |
| `analyze_product_images` | Competitor gallery coverage, thin galleries you can beat, Amazon's image requirements and a seven-slot image plan |
| `analyze_reviews` | Complaints grouped by theme with mention counts and concrete product fixes, plus appreciated features and differentiation angles |
| `scrape_listing_details` | Full teardown of a live listing — title, images, bullets, description, A+, video, specs, badges, variations — graded 0–100 with how to beat it |

### Advertising

| Tool | What it does |
|---|---|
| `suggest_ppc_keywords` | Ad keywords with match type (exact / phrase / broad), suggested bid from your unit profit, priority, campaign placement, plus negative keywords |
| `calculate_ppc_bids` | Break-even ACOS (= your margin), target ACOS, break-even and target CPC, a bid ladder per match type, clicks and ad cost per order. Checks a bid you already run |
| `plan_ppc_campaign` | Three-campaign structure (Auto discovery, Manual Exact core, Phrase/Broad expansion) with budget split, projected orders and a weekly optimisation routine |

### Sourcing

| Tool | What it does |
|---|---|
| `search_suppliers` | Sourcing research for Parrys / Chennai / Tamil Nadu / India with verification status and a vetting checklist. Never invents suppliers |

### Live data

| Tool | What it does |
|---|---|
| `search_web` | Web search via DuckDuckGo (free, no key) or Brave / Serper / Tavily / Google CSE |
| `scrape_amazon_search` | Live amazon.in search results: ASIN, price, rating, review count, purchase badge, sponsored flag |
| `scrape_amazon_product` | Live product page: BSR, weight, seller, bullets, full image gallery, plus a sales estimate |
| `scraper_status` | What the live-data layer is configured to do, and anything blocking it |

### Opportunity scoring

| Component | Weight |
|---|---|
| Demand | 25% |
| Profitability | 25% |
| Competition | 20% |
| Return risk | 10% |
| Sourcing ease | 10% |
| Beginner friendliness | 10% |

| Score | Recommendation |
|---|---|
| 80–100 | Strong Opportunity |
| 65–79 | Good Opportunity |
| 50–64 | Moderate Opportunity |
| 30–49 | High Risk |
| 0–29 | Avoid |

---

## Example Prompts

```text
Find beginner-friendly Amazon India products under ₹20,000 investment.

Screen these ideas and rank them: sink strainer, cable organizer, spice rack.

Analyze the demand for silicone sink strainers on Amazon India.

Is a silicone sink strainer an evergreen product or seasonal?

How many units are competitors selling for "cable organizer"?

Are any new sellers succeeding in the kitchen drawer organizer market?

What revenue would a ₹399 product at BSR 3,500 make per month?

Calculate the profit for a ₹399 product that costs ₹120.

Plan a ₹20,000 launch for a ₹399 sink strainer that costs ₹120.

Find suppliers for cable organizers in Chennai or Tamil Nadu.

Find customer complaints about manual soap dispensers.

Generate an Amazon India listing for a reusable silicone food storage bag.

Scrape live Amazon India results for "silicone sink strainer".

Tear down ASIN B0XXXXXXXX and tell me how to beat that listing.

What should I bid on Amazon Ads for a ₹399 product that costs ₹120?

Plan a ₹6,000/month PPC campaign for my sink strainer launch.

Check the scraper status.
```

A natural workflow: *screen ideas → check demand and evergreen → check competitors and
new sellers → calculate profit → plan the launch → research keywords → generate the listing.*

**[docs/PROMPTS.md](docs/PROMPTS.md) is the full prompt library** — 56 copy-paste prompts
grouped by task, chained multi-tool workflows, and prompts that make Claude show which
numbers are live versus estimated.

---

## Demo Mode

With `DEMO_MODE=true` (the default) every tool works without a single paid API key.

- Sample data is **deterministic** — the same query always returns the same numbers, so
  results are reproducible and testable.
- Every value is labelled `"data_type": "Demo"`, `"confidence": "Low"`,
  `"source": "Local Demo Provider"`.
- The server logs a warning on startup so nobody forgets which mode they are in.

Demo mode is for learning the workflow and testing the integration. **Never make a purchase
decision on demo numbers.**

---

## Live Data on Free Sources (no API keys)

Everything below is free and needs no API key:

```bash
uv sync --extra realtime --extra browser
uv run playwright install chromium     # only for render=true
```

```ini
APP_ENV=production
DEMO_MODE=false
PRODUCT_DATA_PROVIDER=scraper
GOOGLE_TRENDS_ENABLED=true
WEB_SEARCH_PROVIDER=duckduckgo
BROWSER_ENABLED=true
BROWSER_ALLOWED_DOMAINS=amazon.in
BROWSER_MIN_DELAY_SECONDS=8
```

| Source | Gives you | Reliability |
|---|---|---|
| Google Trends | Real India search interest, seasonality, evergreen scoring | High |
| DuckDuckGo | Live web search for competitors, suppliers, prices | High |
| amazon.in pages | Prices, ASINs, ratings, review counts, purchase badges | Intermittent |

Amazon serves bot challenges to automated traffic. This server **detects and stops**
on them rather than bypassing them, so scraping works opportunistically. Read
[docs/SCRAPING.md](docs/SCRAPING.md) before enabling it — it covers robots.txt vs
Terms of Service, the guardrails, and how to fix selectors without touching code.

---

## Production API Integration

1. **Product data.** Implement a `ProductDataProvider` subclass in
   `services/amazon_service.py` (`search_listings` and `fetch_reviews`), or point
   `PRODUCT_DATA_BASE_URL` / `PRODUCT_DATA_API_KEY` at an approved third-party API and
   adapt `HttpProductDataProvider`'s payload mapping. Then set `DEMO_MODE=false`.
2. **Amazon SP-API / PA-API.** Register as a developer, obtain credentials, and add a
   provider that signs requests with `AMAZON_API_KEY` / `AMAZON_API_SECRET`.
   `build_provider()` already routes `sp-api` and `pa-api` and currently raises a clear
   "not implemented" error rather than silently faking data.
3. **Fees.** Export your Seller Central rate card to JSON matching the `FeeSchedule` model,
   point `AMAZON_FEE_CONFIG_PATH` at it, and set `data_type` to `Verified`.
4. **Suppliers.** Set `SUPPLIER_API_KEY` and `SUPPLIER_API_BASE_URL`; verification status is
   passed through from the provider rather than assumed.

Respect each provider's terms of service. Scraping Amazon directly violates their terms and
is not implemented here.

---

## Testing

```bash
uv run pytest                      # whole suite (193 tests)
uv run pytest -v                   # verbose
uv run pytest tests/test_profit_calculator.py
uv run docs/check_connection.py    # end-to-end MCP connection self-test
```

Coverage includes product research, opportunity scoring bands and weights, demand analysis
and seasonality, competition analysis, the full profit maths (break-even and recommended
price are verified by recomputation), fee-schedule configurability, revenue and BSR-curve
estimation, new-seller and volume-target classification, evergreen scoring, every scraping
guardrail (allowlist, robots, page budget, bot-challenge detection), HTML parsing helpers,
invalid input handling for every tool, and demo-mode determinism.

The suite is fully offline: live Google Trends, web search and page fetching are forced
off so results stay deterministic.

The suite forces demo mode, disables caching and disables history persistence, so it never
touches your research database.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| Server missing in Claude Desktop | Use absolute paths in the config, then fully quit and restart Claude Desktop |
| `spawn python ENOENT` | Point `command` at the interpreter inside `.venv` |
| `ModuleNotFoundError` | Run `uv sync`; make sure the config uses the `.venv` interpreter |
| Server "hangs" when run manually | Correct — it is waiting for a client on stdio |
| `provider_not_configured` error | Set `PRODUCT_DATA_API_KEY` / `PRODUCT_DATA_BASE_URL`, or `DEMO_MODE=true` |
| `rate_limit_exceeded` | Wait for the provider window to reset; caching is on by default |
| Everything says "Demo" | Expected in demo mode; set `DEMO_MODE=false` and configure a provider |
| Database errors | Check `DATABASE_URL`; tools keep working without history storage |

Logs go to stderr. Set `DEBUG=true` or `LOG_LEVEL=DEBUG` for detail; in Claude Desktop, use
the MCP log files (`%APPDATA%\Claude\logs` on Windows, `~/Library/Logs/Claude` on macOS).

---

## Security

Three risks come with what this server does, and each has an explicit control. Full
detail in [SECURITY.md](SECURITY.md); the controls are tested in
[`tests/test_security.py`](tests/test_security.py).

**SSRF.** Scheme, port and resolved IP are checked before any request, and every
redirect hop is revalidated — so an allowlisted host cannot redirect the fetch onto
loopback, a private range or the cloud metadata endpoint. Playwright requests go
through the same gate.

**Credentials.** A redacting log filter scrubs API keys, bearer tokens and
secret-bearing query parameters from every log record, including library logging such
as httpx's request URLs. No tool output ever contains a key.

**Prompt injection.** Scraped listings, reviews and search results are third-party text
landing in an LLM's context. Every field is sanitised (control, zero-width and
bidirectional characters stripped), scanned for instruction-shaped content, and
returned with a `content_safety` block. The server's MCP instructions tell the model
to treat it as data, never instructions.

Also enforced: an 8 MB response cap, 5-hop redirect limit, validated config file paths,
parameterised SQL, and no stack traces reaching the MCP client.

---

## Security Notes

- Credentials come from environment variables only; `.env` is gitignored and nothing is
  hardcoded.
- Stack traces never reach the MCP client — errors are logged server-side and returned as
  structured, user-safe payloads.
- The database stores research payloads only, no credentials.
- Fee and marketplace figures are configuration, not code, so they can be corrected without
  a code change.
- Nothing in this project scrapes Amazon or bypasses any provider's terms.

---

## Roadmap

- Real SP-API and Product Advertising API providers with request signing
- Historical tracking: price, BSR and rating trends from stored research
- MCP resources exposing saved research history back to Claude
- FBA storage and advertising cost modelling (ACOS-aware break-even)
- Category-level gating and certification (BIS / FSSAI) reference data
- Calibrating the BSR-to-units curves against real seller sales data
- Bestseller-list mining for proven-demand product discovery

---

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

The rule that matters most: **never invent data, and never let an estimate look like a
measurement.** People spend real money on this output, so every value carries its
source, data type and confidence.

Particularly valuable right now:

- Selector fixes when Amazon changes its markup
- Calibrating the BSR-to-units curves against real sales data
- GST, category compliance and import-cost tooling for Indian sellers
- Real SP-API / Product Advertising API providers

Pull requests adding bot-protection bypass (proxy rotation, fingerprint spoofing,
CAPTCHA solving) will be declined — see [docs/SCRAPING.md](docs/SCRAPING.md).

Also see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and [SECURITY.md](SECURITY.md).

---

## Licence

[MIT](LICENSE) — free to use, modify and distribute, including commercially. The
software is provided as is, without warranty.

---

## Disclaimer

This tool supports research; it does not replace it. Demand, sales and profitability figures
are estimates based on the inputs and the configured fee schedule — not guarantees. Verify
fees in Seller Central, verify every supplier yourself, and confirm category and brand
requirements with Amazon before investing.
