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

[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.

[igrigorik]

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?

@amithanda I think all of those deserve further exploration and some can be modelled as extensions (e.g. pickup-in-store) while others may make sense in core schema. That said, all of them are not specific to get-product operation but catalog as a whole, and I don't think we need to hold this PR; let's tackle these as followup PRs.

---

I've rebased and addressed all the outstanding feedback. I believe this should be good to merge.