# ProductLens MCP 🔍
 
A **Product Intelligence MCP server** — exposes product comparison and analysis tools that any MCP-compatible AI assistant (Claude Desktop, ChatGPT, Cursor, VS Code) can discover and use.
 
Built with [FastMCP](https://gofastmcp.com). Demo dataset: Indian compact SUVs.
 
## Demo
 
▶️ **[Watch the 90-second demo](https://youtu.be/0IpLRQrL4cw)** — Claude Desktop autonomously chaining `compare_products` → `swot_analysis` → `recommend_product` to answer:
*"Compare the Brezza and Nexon, give me a SWOT of the winner, and tell me what to buy under ₹9 lakh if safety matters most."*
 
## Why MCP?
 
Instead of building a chatbot locked into one AI platform, ProductLens is a *service*. Build the logic once; every MCP client can call it:
 
```
Claude ─┐
ChatGPT ─┼──► ProductLens MCP ──► data / logic
Cursor ─┘
```
 
The server describes its own tools (names, arguments, docs), so AI clients discover them automatically — no custom integration per assistant.
 
## Tools
 
| Tool | What it does |
|------|--------------|
| `compare_products(product1, product2)` | Head-to-head comparison on price, mileage, power, safety, boot space — with per-metric winners and an overall edge |
| `swot_analysis(product)` | SWOT for one product, **computed** against the segment average (beats average → strength, trails → weakness) plus rule-based opportunities/threats |
| `recommend_product(budget_lakh, priority)` | Top-3 picks within budget, ranked by one priority (`safety`, `mileage`, `power`, `boot_space`, or `price`), each with a reason |
| `list_products()` | Lists the product catalog |
 
Roadmap: `summarize_reviews`, `generate_prd`, a second product category (phones) to prove the server is category-agnostic.
 
## Quick start
 
```bash
git clone https://github.com/<you>/ProductLens-MCP.git
cd ProductLens-MCP
pip install -r requirements.txt
python server.py          # runs over stdio for MCP clients
python test_client.py     # smoke-test via a real MCP client
```
 
Requires Python 3.10+ (FastMCP does not support older versions).
 
## Connect to Claude Desktop
 
Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
```json
{
  "mcpServers": {
    "productlens": {
      "command": "/full/path/to/your/python",
      "args": ["/full/path/to/ProductLens-MCP/server.py"]
    }
  }
}
```
 
> **Note:** use the full path to the Python that has fastmcp installed (find it with `which python`). Claude Desktop launches the server itself, so a bare `"python"` may resolve to a different interpreter — especially with conda environments.
 
Restart Claude Desktop fully (Cmd+Q), then ask: *"Compare Brezza and Nexon."*
 
## Project structure
 
```
ProductLens-MCP/
├── server.py          # MCP layer — thin, just registers tools
├── tools/
│   ├── compare.py     # head-to-head comparison logic
│   ├── swot.py        # SWOT vs segment average
│   └── recommend.py   # budget + priority recommendations
├── data/
│   └── cars.csv       # demo dataset (swap for any product CSV)
├── test_client.py     # end-to-end MCP protocol test
├── demo.mp4           # Claude Desktop demo recording
└── requirements.txt
```
 
**Design principle:** logic and protocol are separated. Everything in `tools/` is plain Python that knows nothing about MCP — it could power a web app or CLI unchanged. `server.py` is just the MCP "waiter."
 
## Sample output
 
`compare_products("Brezza", "Nexon")` returns structured JSON — per-metric winners, each product's advantages, and an overall edge — which the AI client turns into a natural-language answer. Errors are AI-friendly too: an unknown product returns the list of available products, so the assistant can recover in conversation instead of dead-ending.
 
## Challenges & learnings
 
- **numpy vs JSON:** pandas returns numpy `int64`/`float64`, which fail MCP's structured-output validation. Fixed by converting to native Python types before returning.
- **Docstrings are the interface:** the AI selects tools purely from their descriptions, so writing them as "what + when to use" directly improved tool selection (e.g., disambiguating SWOT-of-one vs compare-two).
- **stdio means the client launches you:** Claude Desktop starts the server itself as a subprocess, so the config must point to the conda environment's Python — a bare `python` resolved to an old 3.8 interpreter without fastmcp.