# Universal Shopping Agent MCP Server

A Model Context Protocol (MCP) server that acts as an intelligent shopping assistant, using Google Gemini AI to analyze shopping intent and automate product searches across multiple e-commerce platforms.

## Features

- **AI-Powered Intent Analysis**: Uses Google Gemini to extract structured shopping intent from natural language queries
- **Multi-Platform Support**: Searches across Amazon, Flipkart, and Myntra with country-specific domains
- **Smart Search Optimization**: Generates optimized search terms based on analyzed requirements
- **Automated Browsing**: Uses Playwright to automatically open browsers and perform searches
- **Budget & Feature Filtering**: Extracts and applies budget constraints and specific features

## Supported Platforms & Countries

- **Amazon**: IN (India)
- **Myntra**: IN (India)

## Prerequisites

- Python 3.9+
- `uv` (The ultra-fast Python package and project manager)
- Claude Desktop App
- Google Gemini API Key

## Installation & Setup

1. **Navigate to the project directory:**
   ```bash
   cd /path/to/this/folder
   ```

2. **Initialize the project and create a virtual environment:**
   ```bash
   uv init universal-shopping-agent
   uv venv
   ```

3. **Create a `.env` file with your Gemini API key:**
   ```
   GEMINI_API_KEY=your_gemini_api_key_here
   ```

4. **Install the dependencies from the provided `requirements.txt`:**
    ```bash
    uv add -r requirements.txt
    ```

5. **Install the Playwright browser:**
   ```bash
   playwright install chromium
   ```

## Running the Server

To test and run the MCP server locally, use:

```bash
uv run --with "mcp[cli]" mcp run main.py
```

If it runs without errors, you are ready to connect it to Claude.

## Connecting to Claude Desktop

1. **Open Claude Desktop.**
2. **Go to Settings -> Developer -> Edit MCP Server Configuration.**
   *This will open the `claude_desktop_config.json` file.*
3. **Add a new configuration for this server.** Replace the paths with the absolute paths on your system.

```json
{
  "mcpServers": {
    "universal-shopping-agent": {
      "command": "/path/to/your/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/universal-shopping-agent",
        "python",
        "main.py"
      ]
    }
  }
}
```

- **`command`**: The absolute path to your `uv` installation. Find it by running `which uv` in your terminal.
- **`args[3]` (`--directory`)**: The absolute path to this project folder.

4. **Save the file and restart Claude Desktop.**

## Usage Examples

Once configured, you can ask Claude shopping-related questions like:

- *"My father needs a new smartphone under ₹20,000 with good battery life and clear video calls. Can you find recommendations on Amazon India?"*
- *"I need a college laptop under 40k that can handle online classes and light coding. Search across Indian e-commerce sites."*
- *"Find wireless earbuds under ₹5,000 with good sound quality and 20+ hours battery on Amazon."*

Claude will:
1. Use Gemini AI to analyze your shopping intent
2. Ask for permission to connect to the shopping agent
3. Open a Chromium browser to perform the search on the appropriate platform
4. Return the search results and intent analysis

## How It Works

1. **Intent Analysis**: Gemini AI extracts structured information from your query (category, budget, features, etc.)
2. **Search Optimization**: Generates the best search terms for e-commerce platforms
4. **Automated Browsing**: Opens amazon platform and performs the search automatically

## Troubleshooting

- **Gemini API Errors**: Ensure your `GEMINI_API_KEY` is set correctly in the `.env` file
- **Browser Issues**: Make sure Playwright Chromium is installed: `playwright install chromium`
- **Platform Errors**: E-commerce websites frequently change their HTML structure; selectors may need updating
- **Connection Issues**: Verify all paths in your Claude MCP configuration are absolute paths

## Important Notes

- The server opens a visible browser window (`headless=False`) to show you the search results
- Some platforms may show login popups; the code handles common ones like Flipkart's
- For clothing items, the agent automatically prefers Myntra over Amazon in India
- Always check the actual search results on the platform for the most current prices and availability

## Example Output

When you ask about smartphones under ₹20,000, Claude will return:
- Structured intent analysis from Gemini
- Optimized search terms used
- Platform where the search was performed
- Confirmation that the browser was opened with your search

---

**Note**: This tool is for educational and personal use. Always verify product details and prices on the actual e-commerce platforms before making purchases.