Metadata-Version: 2.4
Name: mcp-india-retail-intelligence
Version: 0.1.0
Summary: Open-source MCP server for real-time product search and price comparison across Amazon India and Flipkart.
Home-page: https://github.com/username/mcp-india-retail-intelligence
Author: Open Source Developer
Author-email: Open Source Developer <developer@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/balaadityaai/mcp-india-retail-intelligence
Project-URL: Repository, https://github.com/balaadityaai/mcp-india-retail-intelligence
Project-URL: Issues, https://github.com/balaadityaai/mcp-india-retail-intelligence/issues
Keywords: mcp,model-context-protocol,india,ecommerce,amazon,flipkart,price-comparison,scraper,ai-tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mcp>=0.1.0
Requires-Dist: httpx[http2]>=0.20.0
Requires-Dist: beautifulsoup4>=4.9.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# MCP India Retail Intelligence Server

An open-source Model Context Protocol (MCP) server that provides clean, real-time product search, price comparison, and market intelligence for Indian e-commerce platforms (**Amazon India** and **Flipkart**). 

This server acts as a standardized protocol bridge, feeding clean product titles, pricing arrays, discounts, review counts, and URLs directly into an LLM's prompt context (for tools like Cursor, Claude Desktop, or Cline).

---

## Features

- **Side-by-Side Comparison:** Unified search across Amazon.in and Flipkart, automatically deduplicated and sorted by price (lowest first).
- **Resilient Grouped Scraper:** Custom CSS-selector-free parser for Flipkart that safely handles dynamic layouts (List & Grid views) by grouping matching product links.
- **Proxy/WAF Bypass Ready:** Built-in support for proxy configurations (`RETAIL_INTEL_PROXY`) to route requests through scraping networks or captcha solvers.
- **Ultra-Lightweight:** Written with `httpx` (HTTP/2 enabled) and `BeautifulSoup4`. No heavy headless browser binaries required in default mode.

---

## Installation

Install the package via `pip` from your localized environment:

```bash
pip install mcp-india-retail-intelligence
```

If you are developing or running the package locally:
```bash
# Clone the repository
git clone https://github.com/balaadityaai/mcp-india-retail-intelligence.git
cd mcp-india-retail-intelligence

# Install in editable mode
pip install -e .
```

---

## MCP Configuration

To link this server into your AI agent host environment, add the server details to the respective configuration files.

### 1. Claude Desktop
Add this block to your `%APPDATA%\Claude\claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "india-retail-intel": {
      "command": "python",
      "args": [
        "-m",
        "mcp_retail_intel.server"
      ],
      "env": {
        "RETAIL_INTEL_PROXY": "" 
      }
    }
  }
}
```
*(Note: If you have a captcha-solving proxy or proxy list, input it into the `RETAIL_INTEL_PROXY` environment variable, e.g., `http://username:password@proxy.example.com:8080`)*

### 2. Cursor or Cline
In your Editor's MCP settings panel, select **command-type: command** and configure:
* **Command:** `python -m mcp_retail_intel.server`
* **Env Variable:** Key: `RETAIL_INTEL_PROXY`, Value: `<your_proxy_url>`

---

## Available Tools

### 1. `search_flipkart`
Searches Flipkart for the given keywords.
- **Arguments:**
  - `query` (string, required): E-commerce product name.
  - `limit` (integer, optional, default: 5): Maximum items to return.
- **Returns:** Array of products with titles, prices, MRP, discount percentage, rating, review counts, URLs, and image links.

### 2. `search_amazon`
Searches Amazon India for the given keywords.
- **Arguments:**
  - `query` (string, required): Product search terms.
  - `limit` (integer, optional, default: 5): Maximum items to return.

### 3. `compare_prices`
Runs queries concurrently on both platforms, merges the listings, filters out invalid values, and returns a unified list sorted from lowest to highest price.
- **Arguments:**
  - `query` (string, required): Product name.
  - `limit` (integer, optional, default: 5): Top items to fetch from each platform.

---

## Bypassing E-Commerce Bot Blocks
Because Amazon India and Flipkart utilize Web Application Firewalls (WAFs), cloud hosting IPs and intensive desktop queries may receive CAPTCHA blocks. 

To ensure high availability in production setups:
1. Obtain an API key or proxy address from a rotating proxy service (e.g., ZenRows, Webshare, ScraperAPI).
2. Set the `RETAIL_INTEL_PROXY` environment variable to your proxy URL. The server's HTTP engine will automatically route requests through the proxy.

---

## License

Distributed under the MIT License. See `LICENSE` for details.
