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

# Install dependencies
uv sync

# Run tests
uv run pytest

# Start the server (M1+)
uv run python -m ucp_mcp_storefront.server

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
• [ ] M1 — Read tools (search, get_product)
• [ ] 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