# Agentic Commerce MCP Server

A custom [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that turns Claude into an agentic shopping assistant. Search products, compare options, manage a cart, and check out — with built-in guardrails for safe autonomous commerce.

Powered by the [DummyJSON Products API](https://dummyjson.com/docs/products) (194 products, 24 categories, no API key required).

## Architecture

```
Claude (agent brain)
    ↓
MCP Server (this project)
    ↓
DummyJSON API → product search, details, categories
    ↓
Cart + Guardrails → spending limits, confirmation gates
    ↓
Checkout → human-in-the-loop confirmation
```

## Tools

| Tool | Description |
|------|-------------|
| `search_products` | Search by keyword, category, price, sort by price/rating |
| `get_product_details` | Full product info with specs, price history |
| `compare_products` | Side-by-side comparison of multiple products |
| `add_to_cart` | Add items (enforces per-item price limit) |
| `view_cart` | Cart contents with subtotal, tax, total |
| `checkout` | Place order (requires explicit confirmation) |
| `clear_cart` | Empty the cart |
| `list_categories` | Discover all 24 product categories |

## Guardrails

Configurable safety limits in `config.json`:

```json
{
  "max_price_per_item": 200,
  "max_order_total": 500,
  "require_checkout_confirmation": true
}
```

- **Per-item price cap** — blocks expensive items (e.g. a $1,999 laptop)
- **Order total cap** — prevents runaway spending
- **Checkout confirmation** — forces the agent to ask the user before purchasing

## Setup

### Prerequisites
- Python 3.11+
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or Claude Desktop

### Install

```bash
git clone https://github.com/sunilvarun/agentic-commerce-mcp.git
cd agentic-commerce-mcp
pip install "mcp[cli]>=1.0.0"
```

### Configure Claude Code

Add to your project's `.mcp.json` (already included in this repo):

```json
{
  "mcpServers": {
    "agentic-commerce": {
      "command": "python3",
      "args": ["-m", "agentic_commerce"],
      "cwd": "/path/to/agentic-commerce-mcp/src"
    }
  }
}
```

### Run

Open Claude Code from the project directory and start shopping:

> "Search for laptops under $150"
> "Compare products 80 and 81"
> "Add product 80 to my cart and check out"

### Test

```bash
pip install pytest
pytest tests/ -v
```

## Project Structure

```
src/agentic_commerce/
├── server.py       # MCP server — registers all tools
├── catalog.py      # DummyJSON API client
├── cart.py         # In-memory shopping cart
├── guardrails.py   # Spending limits & confirmation gates
└── __main__.py     # Entry point
```

## Extending

The catalog module (`catalog.py`) exposes a clean interface (`search`, `get_product`, `get_products`). To swap in a real API (Amazon PA API, eBay, Shopify), just replace the implementation in that file — the server and cart don't need to change.