Skip to main content
Glama
UCP MCP Storefront

UCP MCP Storefront

by ZaynTawfik

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.

Related MCP server: MCP Merchant Scout

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

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:

{
  "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

  • 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

Available Tools

5 tools
add_to_cartA

Add a product to an existing cart.

Args: cart_id: The cart identifier (e.g. "crt_..."). product_id: The product identifier (e.g. "prod_001"). quantity: Number of units to add (default 1).

Validates that the product exists and has sufficient inventory. Returns the updated UCP cart, or an error message on failure.

Inputs: cart_id (required), product_id (required), quantity.

create_cartA

Create a new empty shopping cart.

Returns a UCP cart response with a unique cart ID (crt_...).

Inputs: no named parameters.

get_productA

Get full product details by ID.

Args: product_id: The product identifier (e.g. "prod_001").

Returns a UCP get_product response, or an error message if not found.

Inputs: product_id (required).

view_cartA

View the current contents of a cart.

Args: cart_id: The cart identifier (e.g. "crt_...").

Returns the UCP cart with line items and running totals (in cents).

Inputs: cart_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: cart creation, item addition, cart viewing, product retrieval, and catalog search. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (add_to_cart, create_cart, get_product, search, view_cart). The naming is predictable and easy for an agent to follow.

    Tool Count5/5

    With exactly 5 tools, the surface is well-scoped for a storefront domain. Each tool serves a necessary function without redundancy or bloat.

    Completeness4/5

    Core cart and product operations are covered. However, missing cart update (quantity change), remove item, or checkout functionality leaves minor gaps that agents might need to work around.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the Universal Commerce Protocol (UCP) Discovery and Catalog capabilities, letting you search and compare products across UCP merchants directly from Claude.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server for e-commerce storefronts that lets AI agents search and browse products, get quotes, and access back-office data (like sales and orders) with privilege separation, using public and authenticated tools.
      49 npm
      1
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      This MCP server bridges XiaoYi to Shopify's catalog search by translating SSE requests to Streamable HTTP and providing the required UCP agent profile, enabling the search_catalog tool.
      1
      -