feat(mcp): redesign variant_details card with parent-derived context

Variants don't carry uom, default supplier, or batch-tracking on their
attrs model — those live on the parent product/material. The previous
card forced agents to guess UoM (e.g., "250 = 250ml presumably"). Now
the impl bulk-fetches parents + suppliers from the cache and the card
surfaces UoM, default supplier, batch-tracked status, and config
attributes inline. Raw IDs are deprioritized to a footer-style row.

- Add uom, default_supplier_id, default_supplier_name, is_batch_tracked
  to VariantDetailsResponse
- Add _enrich_variants_with_parent helper: 3 bulk cache queries
  (products, materials, suppliers) per get_variant_details call,
  regardless of variant count
- Rewrite build_variant_details_ui as 4-tier layout (identity → metrics
  → reference → actions); price formatter shows "\$X / uom" suffix when
  uom isn't pcs/ea
- Add 5 behavior tests covering UoM render/omit, config-attr badges,
  supplier name, and graceful fallback when parent lookup is empty

Closes #538.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dougborg

katana_mcp_server/src/katana_mcp/tools/foundation/items.py

@@ -1236,6 +1236,12 @@ class VariantDetailsResponse(BaseModel):
     """Full variant details. Exhaustive — every field Katana exposes on the
     ``Variant`` attrs model is surfaced, including nested configuration
     attributes and custom fields, so callers don't need follow-up lookups.
+
+    A handful of fields (``uom``, ``default_supplier_*``, ``is_batch_tracked``)
+    live on the parent product/material rather than on the variant attrs
+    model. The impl resolves the parent from the cache and lifts these
+    fields onto the variant response so a single ``get_variant_details``
+    call surfaces every fact a caller typically needs to act on.
     """
 
     # Core fields
@@ -1253,6 +1259,13 @@ class VariantDetailsResponse(BaseModel):
     material_id: int | None = None
     product_or_material_name: str | None = None
 
+    # Parent-item context (lifted from the parent product/material —
+    # variants don't carry these on the attrs model directly)
+    uom: str | None = None
+    default_supplier_id: int | None = None
+    default_supplier_name: str | None = None
+    is_batch_tracked: bool | None = None
+
     # Deep-link to the parent product or material — variants don't have
     # their own page in Katana's web app, so callers click through to the
     # parent record.
@@ -1302,11 +1315,19 @@ def _iso_or_none(value: Any) -> str | None:
     return str(value)
 
 
-def _dict_to_variant_details(v: dict[str, Any]) -> VariantDetailsResponse:
+def _dict_to_variant_details(
+    v: dict[str, Any],
+    *,
+    parent: dict[str, Any] | None = None,
+    supplier: dict[str, Any] | None = None,
+) -> VariantDetailsResponse:
     """Build a VariantDetailsResponse from a cache/API variant dict.
 
-    Surfaces every field the generated ``Variant`` attrs model exposes, so
-    callers get the full shape in a single call.
+    Surfaces every field the generated ``Variant`` attrs model exposes
+    plus the parent-derived context (``uom``, ``default_supplier_*``,
+    ``is_batch_tracked``) when ``parent`` and/or ``supplier`` dicts are
+    supplied. Both are optional; missing parents/suppliers (cold cache,
+    miss) gracefully degrade to ``None`` for those fields.
     """
     product_id = v.get("product_id")
     material_id = v.get("material_id")
@@ -1317,6 +1338,7 @@ def _dict_to_variant_details(v: dict[str, Any]) -> VariantDetailsResponse:
     parent_url = katana_web_url("product", product_id) or katana_web_url(
         "material", material_id
     )
+    parent_dict = parent or {}
     return VariantDetailsResponse(
         id=v["id"],
         sku=v.get("sku") or "",
@@ -1327,6 +1349,10 @@ def _dict_to_variant_details(v: dict[str, Any]) -> VariantDetailsResponse:
         product_id=product_id,
         material_id=material_id,
         product_or_material_name=v.get("parent_name"),
+        uom=parent_dict.get("uom"),
+        default_supplier_id=parent_dict.get("default_supplier_id"),
+        default_supplier_name=(supplier or {}).get("name"),
+        is_batch_tracked=parent_dict.get("batch_tracked"),
         katana_url=parent_url,
         internal_barcode=v.get("internal_barcode"),
         registered_barcode=v.get("registered_barcode"),
@@ -1341,6 +1367,47 @@ def _dict_to_variant_details(v: dict[str, Any]) -> VariantDetailsResponse:
     )
 
 
+async def _enrich_variants_with_parent(
+    services: Any, variants: list[dict[str, Any]]
+) -> tuple[
+    dict[int, dict[str, Any]],
+    dict[int, dict[str, Any]],
+    dict[int, dict[str, Any]],
+]:
+    """Bulk-fetch parent products/materials and default suppliers for a
+    set of variants. Returns ``(products_by_id, materials_by_id,
+    supplier_by_id)`` — separate maps per entity type so callers can
+    select the correct parent based on whether the variant carries
+    ``product_id`` or ``material_id``.
+
+    Product and material IDs are NOT guaranteed disjoint (the cache
+    keys rows by ``(entity_type, id)``), so merging into a single map
+    keyed only by numeric ID would mis-associate parents on collision.
+
+    Splits parent IDs by entity type and uses ``get_many_by_ids`` per
+    type so we make at most three cache queries total
+    (parents-product, parents-material, suppliers) regardless of how
+    many variants are in the input.
+    """
+    product_ids = {v.get("product_id") for v in variants if v.get("product_id")}
+    material_ids = {v.get("material_id") for v in variants if v.get("material_id")}
+    products, materials = await asyncio.gather(
+        services.cache.get_many_by_ids(EntityType.PRODUCT, product_ids),
+        services.cache.get_many_by_ids(EntityType.MATERIAL, material_ids),
+    )
+    # Pull supplier IDs from both parent dicts, then bulk-resolve
+    # supplier names — usually a small unique set even for big variant lists.
+    supplier_ids = {
+        p.get("default_supplier_id")
+        for p in (*products.values(), *materials.values())
+        if p.get("default_supplier_id")
+    }
+    supplier_by_id = await services.cache.get_many_by_ids(
+        EntityType.SUPPLIER, supplier_ids
+    )
+    return products, materials, supplier_by_id
+
+
 async def _fetch_variant_by_id(services: Any, variant_id: int) -> dict[str, Any] | None:
     """Look up a variant by ID — cache first, then API fallback.
 
@@ -1404,15 +1471,35 @@ async def _get_variant_details_impl(
         asyncio.gather(*(_fetch_variant_by_id(services, v) for v in variant_ids)),
     )
 
-    results: list[VariantDetailsResponse] = []
+    found: list[dict[str, Any]] = []
     for sku, v in zip(sku_cleaned, sku_variants, strict=True):
         if not v:
             raise ValueError(f"Variant with SKU '{sku}' not found")
-        results.append(_dict_to_variant_details(v))
+        found.append(v)
     for variant_id, v in zip(variant_ids, id_variants, strict=True):
         if v is None:
             raise ValueError(f"Variant ID {variant_id} not found")
-        results.append(_dict_to_variant_details(v))
+        found.append(v)
+
+    # Bulk-fetch parents + suppliers once for the whole batch so the
+    # response includes UoM, default supplier name, and batch-tracked
+    # status without a per-variant follow-up call (#538).
+    products, materials, supplier_by_id = await _enrich_variants_with_parent(
+        services, found
+    )
+    results: list[VariantDetailsResponse] = []
+    for v in found:
+        # Pick the parent map by which ID the variant carries — product
+        # and material IDs may collide, so a merged map would mis-attach.
+        if v.get("product_id"):
+            parent = products.get(v["product_id"])
+        elif v.get("material_id"):
+            parent = materials.get(v["material_id"])
+        else:
+            parent = None
+        sup_id = (parent or {}).get("default_supplier_id")
+        supplier = supplier_by_id.get(sup_id) if sup_id else None
+        results.append(_dict_to_variant_details(v, parent=parent, supplier=supplier))
 
     return results
 

katana_mcp_server/src/katana_mcp/tools/prefab_ui.py

@@ -232,66 +232,152 @@ def build_search_results_ui(
     return app
 
 
+def _variant_header_section(variant: dict[str, Any]) -> None:
+    """Render variant card header: title, badges, parent, config-attribute pills."""
+    with Row(gap=2):
+        CardTitle(content=variant.get("name", "Unknown"))
+        Badge(label=variant.get("sku", ""), variant="outline")
+        if variant.get("type"):
+            Badge(label=variant["type"], variant="secondary")
+        if variant.get("is_batch_tracked"):
+            Badge(label="Batch tracked", variant="secondary")
+    parent_name = variant.get("product_or_material_name")
+    if parent_name:
+        Muted(content=f"Part of: {parent_name}")
+    # Config-attribute pills (size / color / volume) inline so the
+    # variant's distinguishing axes are visible without scrolling.
+    config_attrs = variant.get("config_attributes") or []
+    if config_attrs:
+        with Row(gap=2):
+            for attr in config_attrs:
+                if not isinstance(attr, dict):
+                    continue
+                label = attr.get("config_name") or ""
+                value = attr.get("config_value") or ""
+                if label and value:
+                    Badge(label=f"{label}: {value}", variant="outline")
+
+
+def _variant_supplier_line(variant: dict[str, Any]) -> None:
+    """Render the default-supplier text row when name and/or id is set."""
+    name = variant.get("default_supplier_name")
+    sid = variant.get("default_supplier_id")
+    if name and sid:
+        Text(content=f"Default Supplier: {name} ({sid})")
+    elif name:
+        Text(content=f"Default Supplier: {name}")
+    elif sid:
+        Text(content=f"Default Supplier ID: {sid}")
+
+
+def _variant_barcode_line(variant: dict[str, Any]) -> None:
+    """Render the barcode text row when at least one barcode is set."""
+    parts = []
+    if variant.get("internal_barcode"):
+        parts.append(f"internal={variant['internal_barcode']}")
+    if variant.get("registered_barcode"):
+        parts.append(f"registered={variant['registered_barcode']}")
+    if parts:
+        Text(content=f"Barcodes: {', '.join(parts)}")
+
+
+def _variant_id_line(variant: dict[str, Any]) -> None:
+    """IDs deprioritized to a single Muted row at the bottom — they're
+    useful for follow-up tool calls but not the primary signal a human
+    reader needs.
+    """
+    id_parts = [f"variant_id={variant.get('id', 'N/A')}"]
+    if variant.get("product_id"):
+        id_parts.append(f"product_id={variant['product_id']}")
+    if variant.get("material_id"):
+        id_parts.append(f"material_id={variant['material_id']}")
+    Muted(content=" · ".join(id_parts))
+
+
+def _variant_reference_section(variant: dict[str, Any]) -> None:
+    """Render the reference data block (UoM, supplier, lead time, codes, IDs)."""
+    if variant.get("uom"):
+        Text(content=f"UoM: {variant['uom']}")
+    _variant_supplier_line(variant)
+    if variant.get("lead_time") is not None:
+        Text(content=f"Lead Time: {variant['lead_time']} days")
+    if variant.get("minimum_order_quantity") is not None:
+        Text(content=f"Min Order Qty: {variant['minimum_order_quantity']}")
+    _variant_barcode_line(variant)
+    if variant.get("supplier_item_codes"):
+        Muted(content="Supplier Codes:")
+        with ForEach("variant.supplier_item_codes"):
+            Text(content="{{ $item }}")
+    _variant_id_line(variant)
+
+
+def _variant_footer_section(variant: dict[str, Any]) -> None:
+    """Render footer action buttons."""
+    sku = variant.get("sku", "")
+    if variant.get("katana_url"):
+        Button(
+            label="View in Katana",
+            variant="outline",
+            on_click=SendMessage(f"Open the Katana URL: {variant['katana_url']}"),
+        )
+    Button(
+        label="Check Inventory",
+        variant="outline",
+        on_click=SendMessage(f"Check inventory for SKU {sku}"),
+    )
+    Button(
+        label="Create Purchase Order",
+        variant="outline",
+        on_click=SendMessage(f"Draft a purchase order for SKU {sku}"),
+    )
+    if variant.get("type") == "material" and variant.get("id"):
+        Button(
+            label="List MOs Using This",
+            variant="outline",
+            on_click=SendMessage(
+                f"List manufacturing orders that use variant_id {variant['id']}"
+            ),
+        )
+
+
 def build_variant_details_ui(
     variant: dict[str, Any],
 ) -> PrefabApp:
-    """Build a detail card for a variant."""
+    """Build a detail card for a variant.
+
+    Designed for the "should I order more / where is this used / how is
+    it tracked" decisions. Surfaces the facts an inventory-aware agent
+    needs first (UoM, default supplier, batch tracking, config
+    attributes), with raw IDs deprioritized to a footer-style row. See
+    #538 for the design rationale.
+    """
+    uom = variant.get("uom")
+
+    def _price_display(p: float | None) -> str:
+        if p is None:
+            return "N/A"
+        suffix = f" / {uom}" if uom and uom not in ("pcs", "ea") else ""
+        return f"${p:,.2f}{suffix}"
+
     with PrefabApp(state={"variant": variant}, css_class="p-4") as app, Card():
-        with CardHeader(), Row(gap=2):
-            CardTitle(content=variant.get("name", "Unknown"))
-            Badge(label=variant.get("sku", ""), variant="outline")
-            if variant.get("type"):
-                Badge(
-                    label=variant["type"],
-                    variant="secondary",
-                )
+        with CardHeader(), Column(gap=1):
+            _variant_header_section(variant)
 
         with CardContent(), Column(gap=3):
             with Row(gap=4):
                 Metric(
                     label="Sales Price",
-                    value=f"${variant.get('sales_price', 0):,.2f}"
-                    if variant.get("sales_price") is not None
-                    else "N/A",
+                    value=_price_display(variant.get("sales_price")),
                 )
                 Metric(
                     label="Purchase Price",
-                    value=f"${variant.get('purchase_price', 0):,.2f}"
-                    if variant.get("purchase_price") is not None
-                    else "N/A",
+                    value=_price_display(variant.get("purchase_price")),
                 )
-
             Separator()
-
-            with Row(gap=4):
-                Text(content=f"ID: {variant.get('id', 'N/A')}")
-                if variant.get("product_id"):
-                    Text(content=f"Product ID: {variant['product_id']}")
-                if variant.get("material_id"):
-                    Text(content=f"Material ID: {variant['material_id']}")
-                if variant.get("lead_time") is not None:
-                    Text(content=f"Lead Time: {variant['lead_time']} days")
-
-            if variant.get("supplier_item_codes"):
-                Muted(content="Supplier Codes:")
-                with ForEach("variant.supplier_item_codes"):
-                    Text(content="{{ $item }}")
+            _variant_reference_section(variant)
 
         with CardFooter(), Row(gap=2):
-            Button(
-                label="Check Inventory",
-                variant="outline",
-                on_click=SendMessage(
-                    f"Check inventory for SKU {variant.get('sku', '')}"
-                ),
-            )
-            Button(
-                label="Create Purchase Order",
-                variant="outline",
-                on_click=SendMessage(
-                    f"Draft a purchase order for SKU {variant.get('sku', '')}"
-                ),
-            )
+            _variant_footer_section(variant)
     return app