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 (stdio transport)
uv run python -m ucp_mcp_storefront.server

MCP Tools

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:

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

MCP Inspector

# 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