feat: get product operation for catalog.lookup

[igrigorik]

search_catalog and lookup_catalog are discovery operations — they return multiple products with featured variant(s). But once a user picks a product, the agent needs a different interaction: full product detail with all options, real-time availability as the user selects options (Color, Size), and the exact variant to purchase. This is the product detail page (PDP) flow, which is best modelled as a distinct operation — this pattern conforms to common API shapes in the wild.

get_product is a single-resource operation (part of dev.ucp.shopping.catalog.lookup) for servicing purchase flow decisions. It returns one product with a relevant subset of variants, option-level availability signals, and support for interactive variant narrowing.

REST: POST /catalog/product
MCP: get_product tool

Example request

{
  "id": "prod_abc123",
  "selected": [
    { "name": "Color", "label": "Blue" }
  ],
  "preferences": ["Color", "Size"],
  "context": { "country": "US" }
}

Only id is required. selected and preferences are for interactive narrowing.

Example (redacted) response

{
  "product": {
    "id": "prod_abc123",
    "title": "Runner Pro",
    "price_range": {
      "min": { "amount": 12000, "currency": "USD" },
      "max": { "amount": 15000, "currency": "USD" }
    },
    "options": [
      {
        "name": "Color",
        "values": [
          { "label": "Blue",  "available": true,  "exists": true },
          { "label": "Green", "available": false, "exists": true }
        ]
      },
      {
        "name": "Size",
        "values": [
          { "label": "10", "available": true,  "exists": true },
          { "label": "11", "available": false, "exists": false }
        ]
      }
    ],
    "selected": [{ "name": "Color", "label": "Blue" }],
    "variants": [
      {
        "id": "var_abc123_blue_10",
        "sku": "RP-BLU-10",
        "title": "Blue / Size 10",
        "price": { "amount": 12000, "currency": "USD" },
        "availability": { "available": true },
        "options": [
          { "name": "Color", "label": "Blue" },
          { "name": "Size", "label": "10" }
        ],
        "media": [{ "type": "image", "url": "https://cdn.example.com/runner-pro-blue.jpg" }]
      }
    ]
  }
}

Iterative Flow

1. Agent calls get_product(id: "prod_abc123") — no selections. Server returns the product with featured variant and option map.
2. User picks Color=Blue. Agent calls get_product(id: "prod_abc123", selected: [{name: "Color", label: "Blue"}]). Response narrows: product.selected confirms Blue, variants are all Blue, availability on Size values updates to reflect Blue inventory.
3. User picks Size=10. Agent adds to selections. Response returns the exact Blue/10 variant — price, SKU, availability — ready for checkout.
4. User picks an impossible combination. Agent sends selected: [{Color: Red}, {Size: 15}] with preferences: ["Color", "Size"]. No Red/15 exists. Server relaxes from the end of preferences — drops Size, keeps Color. Response product.selected is [{Color: Red}]. Agent diffs request vs response selected, sees Size was dropped, and can surface that to the user.

Each round-trip is stateless. The agent sends the full selection state, the server returns the full product state.

Key Design Decisions

• product.selected is the response anchor. It determines the featured variant, the variant subset, and all availability signals. One concept, not three.
• All returned variants match product.selected. No "adjacent" or "contextually relevant" variants outside the selection. Availability context for non-matching options is carried by options[].values[].available/exists, not the variant array.
• selected_options → options on variants. Separates variant identity (what a variant is) from user selection state (what the user chose). These were previously conflated under the same name.
• input correlation moved to lookup_variant. Correlation is a batch-lookup concern, not intrinsic to variants. Base variant type stays clean; operation-specific extensions via allOf.
• Singular response (product) not array. Single-resource semantics — not found is an error (404 / -32602), not an empty result.

---

Checklist

• New feature (non-breaking change which adds functionality)
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

[maximenajim]

REST docs specify POST /catalog/product returns HTTP 404 for not found, but rest.openapi.json only declares a 200 response for this operation (no 404, no 400 for invalid selections/preferences, no 401/403).
Suggested fix: update OpenAPI responses for /catalog/product to include at least 400, 401, 403, 404, and reference the standard error schema.

[maximenajim]

The “Both operations accept product and variant identifiers” table implies get_product supports the same identifier surface as lookup_catalog (SKU, URL, handle, etc.), but the later Get Product → Supported Identifiers section says “The id parameter accepts a single product ID or variant ID.” These are materially different guarantees.

Suggested fix: explicitly state:
“MUST support product ID + variant ID”
“MAY support SKU/URL/handle/etc.” (list optional identifiers)
and add a normative note: identifiers are opaque strings and MUST NOT be dereferenced or fetched as URLs.

[maximenajim]

detail_product.selected is optional and the description says “Present when the request includes selected options,” but the docs in lookup.md say the response MUST include product.selected and that it determines featured variant + availability anchor.

[amithanda]

Should we add Shipping speed, price & options (e.g pickup in store, delivery etc) to the response, if location related buyer user context is provided?
Should we add return policy for the product?

Why:

• In addition to Product price, variants and availablity (which we are addressing currently), shipping and returns are the other important signals for user's purchase considerations which are useful to be shown on the PDP.

[alex-jansen]

Note that #222 is also relevant in the context of catalog lookups as part of important regulatory product information that should be returned in product lookups.

[gsmith85]

Nit: "variant option selection"? Or maybe just drop the terminating fragment altogether, I think the API is self explanatory.

[gsmith85]

Question for the TC: As we think about the long-term scalability of get_product, how do we envision this relaxation logic behaving in multi-seller or marketplace scenarios?

Currently, since seller is metadata on a variant and not a first-class option, it cannot participate in the preferences stack. This forces the server to guess when inventory conflicts arise:

• Does it relax the attribute (show the wrong color to keep a preferred seller) or
• Relax the merchant (keep the color but switch to a non-Prime, higher-priced seller)?

To support heterogeneous inventory environments (where multiple sellers offer the same SKU with varying fulfillment terms), we should consider if 'Seller' or 'Fulfillment' needs to be a dimension the Agent can actually prioritize. Otherwise, the relaxation logic remains 'merchant-blind,' potentially dropping a user's primary intent (e.g., Prime eligibility, a specific vendor in B2B procurement) to satisfy a secondary one (e.g., color).

Should 'Seller' somehow be elevated to participate in the preferences stack, or should we handle marketplace-ranking logic through a more robust context object?

[gsmith85]

Suggestion: Split out separate IDs for product and variant. Using a single id for both may be brittle. As proposed, if an agent provides a variant id that is stale or purged, the server loses the anchor to the parent product and is forced to return a 404, even if the product itself is still active.

With both product_id and variant_id available you have an option for "soft recovery": If the server doesn't recognize the variant_id it can anchor on the product and still respect preferences to find the next best match.

Lower priority, but decoupling provides a clear signal to the server on the ID type being received, reducing lookups to determine if an identifier is a product or a variant.

[gsmith85]

Suggestion: Document how a conflict between a specific variant and selected is handled if the options aren't aligned. I.e. if variant has option Color:Red but selected is Color:Blue.