<p align="center">
  <img src="https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge" alt="MCP Server"/>
  <img src="https://img.shields.io/badge/Python-3.10+-green?style=for-the-badge&logo=python" alt="Python"/>
  <img src="https://img.shields.io/badge/Playwright-Browser-orange?style=for-the-badge&logo=playwright" alt="Playwright"/>
  <img src="https://img.shields.io/badge/Sites-Amazon.in%20%7C%20Flipkart-purple?style=for-the-badge" alt="Sites"/>
</p>

<h1 align="center">shop-mcp</h1>

<p align="center">
  <b>A local MCP server for personal shopping automation on Amazon.in & Flipkart</b><br/>
  Search products, compare prices, manage cart, and place orders — all through your AI assistant with safety guards built in.
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-architecture">Architecture</a> •
  <a href="#-tools">Tools</a> •
  <a href="#-safety-guards">Safety Guards</a> •
  <a href="#-mcp-client-config">Client Config</a>
</p>

---

## How It Works

```mermaid
graph LR
    A[AI Assistant<br/>Claude / Open AI / Kiro / Any AI Chat or LLM Model] -->|MCP Protocol<br/>stdio| B[shop-mcp<br/>Server]
    B -->|Playwright<br/>Browser Automation| C[Amazon.in]
    B -->|Playwright<br/>Browser Automation| D[Flipkart]

    B --- E[Saved Sessions<br/>cookies only<br/>no passwords]

    style A fill:#4A90D9,color:#fff
    style B fill:#2ECC71,color:#fff
    style C fill:#FF9900,color:#fff
    style D fill:#F7D02C,color:#000
    style E fill:#95A5A6,color:#fff
```

```mermaid
flowchart LR
    AI["🤖 YOUR AI ASSISTANT\nClaude Desktop · Kiro · Any MCP Client"]

    subgraph SERVER["🖥️ shop-mcp SERVER"]
        direction TB
        RO["📖 Read-Only\nsearch_product\nview_cart\nget_product_details\nget_order_status"]
        MU["✏️ Mutations\nadd_to_cart"]
        GC["🔐 Guarded Checkout\ncheckout_dry_run\nplace_order\nToken + ₹3000 cap\n5 min expiry"]
    end

    subgraph SITES["🌐 Shopping Platforms"]
        direction TB
        AMZ["🟠 Amazon.in\nSession cookies\nManual login once"]
        FK["🔵 Flipkart\nSession cookies\nManual login once"]
    end

    AI -->|"MCP Protocol\nstdio"| SERVER
    SERVER -->|"Playwright\nChromium"| SITES

    style AI fill:#1a73e8,stroke:#0d47a1,stroke-width:3px,color:#fff
    style SERVER fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#2e7d32
    style RO fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    style MU fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#e65100
    style GC fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#b71c1c
    style SITES fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#6a1b9a
    style AMZ fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    style FK fill:#e8eaf6,stroke:#283593,stroke-width:2px,color:#1a237e
```

---

## Key Features

| Feature | Description |
|---------|-------------|
| **Price Comparison** | Search the same product on both platforms and compare prices instantly |
| **Cart Management** | View, add to cart across Amazon.in and Flipkart |
| **Guarded Checkout** | Orders require a dry-run summary + confirmation token + price cap |
| **No Password Storage** | You log in manually once; only session cookies are saved |
| **Headed Browser** | Visible Chromium window — no stealth, no detection issues |
| **MCP Standard** | Works with any MCP-compatible AI client via stdio transport |

---

## Quick Start

```bash
# 1. Clone & setup
git clone https://github.com/detushar/shop-mcp.git
cd shop-mcp
python -m venv .venv
.venv\Scripts\activate              # or source .venv/bin/activate on Linux/macOS

# 2. Install dependencies
pip install -r requirements.txt
playwright install chromium          # downloads browser binary (~180MB)

# 3. Login to sites (one-time, manual)
python -m browser.login amazon
python -m browser.login flipkart

# 4. Run the MCP server
python server.py
```

> **Note:** `playwright install chromium` downloads the Chromium binary that Playwright controls.
> This is separate from the Python package and required for the server to work.

---

## Tools

| Tool | Effect | Risk Level |
|------|--------|------------|
| `search_product` | Search a site for products | Read-only |
| `get_product_details` | Get price, title, availability for a product URL | Read-only |
| `view_cart` | List current cart contents | Read-only |
| `get_order_status` | Look up an existing order by ID | Read-only |
| `add_to_cart` | Add a product to the cart | Reversible |
| `checkout_dry_run` | Load checkout summary WITHOUT submitting | Read-only |
| `place_order` | Submit the order | **Irreversible** — guarded |

---

## Safety Guards

```
place_order() will REFUSE if:
  ✗ No checkout_dry_run() was called first
  ✗ confirm_token doesn't match the latest dry-run
  ✗ Token is older than 5 minutes (stale prices)
  ✗ Order total exceeds ₹3,000 (configurable cap)
```

Configure in `config.py`:

| Setting | Default | Purpose |
|---------|---------|---------|
| `MAX_ORDER_TOTAL_INR` | 3000 | Hard price ceiling per order |
| `REQUIRE_CONFIRM_TOKEN` | True | Forces dry-run before every purchase |
| `CONFIRM_TOKEN_TTL_SECONDS` | 300 | Token expiry (forces fresh price check) |

---

## MCP Client Config

Example config file: [`mcp-config-example.json`](mcp-config-example.json)

### Claude Desktop

`%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "shop-mcp": {
      "command": "C:\\path\\to\\shop-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\shop-mcp\\server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}
```

### Kiro IDE

Add to `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "shop-mcp": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "D:\\path\\to\\shop-mcp",
      "env": { "PYTHONUNBUFFERED": "1" },
      "disabled": false
    }
  }
}
```

### Linux / macOS

```json
{
  "mcpServers": {
    "shop-mcp": {
      "command": "/path/to/shop-mcp/.venv/bin/python",
      "args": ["/path/to/shop-mcp/server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}
```

> Always use the Python from your `.venv` so all dependencies are available.

---

## Project Structure

```
shop-mcp/
├── server.py               # MCP server — tool definitions & checkout guards
├── config.py               # Safety settings, timeouts, site URLs
├── requirements.txt        # Python dependencies
├── mcp-config-example.json # Client configuration template
├── browser/
│   ├── base.py             # Playwright session management (cookies, context)
│   ├── amazon.py           # Amazon.in browser actions (search, cart, checkout)
│   ├── flipkart.py         # Flipkart browser actions
│   └── login.py            # Manual login helper (opens browser for you)
└── sessions/               # Auto-created, .gitignored — stores login cookies
```

---

## Important Notes

| | |
|---|---|
| **Terms of Service** | Amazon.in and Flipkart restrict bot access. This is for *personal, low-volume* use of your own account only. |
| **Selectors Break** | Both sites change their DOM frequently. Expect to update CSS selectors in `browser/amazon.py` and `browser/flipkart.py` when things stop working. |
| **Headed Mode** | Both sites detect headless browsers. Everything runs with a visible Chromium window (`headless=False`). |
| **Session Expiry** | When cookies expire, re-run `python -m browser.login <site>` to refresh. |

---

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Server Framework | [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) via `fastmcp` |
| Browser Automation | [Playwright](https://playwright.dev/python/) (Chromium) |
| Language | Python 3.10+ |
| Transport | stdio (local server) |

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

<p align="center">
  <i>Built for personal use. Use responsibly. Your account, your risk.</i>
</p>