# UCP MCP Storefront

A UCP-compliant MCP storefront server that exposes a product catalog as MCP tools. Each tool maps to a real UCP capability (Catalog Search & Lookup, Cart Building, Checkout, Order Management), and every tool's output matches the corresponding UCP schema (version `2026-04-08`).

UCP is transport-agnostic and explicitly supports MCP as a transport alongside REST and A2A — so "a UCP storefront exposed over MCP" is on-spec.

## Key Principles

- **All prices are integers in cents** (e.g. `1999` = $19.99). Never floats for money.
- **UCP version `2026-04-08`** — date-based versioning per the UCP spec.
- **Payment is always mocked** — no real credentials, ever.

## Quick Start

```bash
# Install dependencies
uv sync

# Run tests
uv run pytest

# Start the server (stdio transport)
uv run python -m ucp_mcp_storefront.server
```

## MCP Tools

| Tool | UCP Capability | Description |
|---|---|---|
| `search` | `dev.ucp.shopping.catalog.search` | Search products by query, max price (cents), and/or category |
| `get_product` | `dev.ucp.shopping.catalog.lookup` | Get full product details by ID |

### `search(query, max_price?, category?)`

- `query` (string, required): Free-text search matching title, description, and tags.
- `max_price` (int, optional): Maximum price in cents (e.g. `10000` = $100.00).
- `category` (string, optional): Filter by tag/category.

Returns a UCP `search_response` with matching products.

### `get_product(product_id)`

- `product_id` (string, required): Product identifier (e.g. `"prod_001"`).

Returns a UCP `get_product_response` with full product detail including variants and pricing.

## Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ucp-storefront": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/ucp-mcp-storefront", "python", "-m", "ucp_mcp_storefront.server"]
    }
  }
}
```

### MCP Inspector

```bash
# Install and run the MCP inspector
npx @modelcontextprotocol/inspector uv run python -m ucp_mcp_storefront.server
```

### Example Interaction

Prompt: *"Find running shoes under $100"*

The agent calls `search(query="running shoes", max_price=10000)` and gets back UCP-shaped results with products, price ranges, variants, and availability status.

## Project Structure

```
├── src/ucp_mcp_storefront/   # Server source code
│   ├── server.py              # FastMCP app; registers all tools
│   ├── catalog.py             # Load + query the fake catalog
│   ├── cart.py                # In-memory cart store
│   ├── checkout.py            # UCP checkout object (mocked payment)
│   ├── ucp_mapping.py         # Internal objects → UCP-shaped dicts
│   └── models.py              # Pydantic models mirroring UCP fields
├── data/products.json         # Fake catalog (25 items, prices in cents)
├── schemas/resolved/          # Resolved UCP JSON Schemas (for tests)
├── tests/                     # pytest test suite
├── scripts/                   # Schema resolution and utilities
└── docs/                      # Architecture and UCP mapping docs
```

## Milestones

- [x] **M0** — Scaffold + fake catalog
- [x] **M1** — Read tools (`search`, `get_product`)
- [x] **M2** — Cart tools (`create_cart`, `add_to_cart`, `view_cart`)
- [ ] **M3** — UCP conformance for cart/line-item shapes
- [ ] **M4** — Checkout tool (UCP checkout object + mock payment)
- [ ] **M5** — Polish & proof