design(mcp): redesign Prefab UI cards across all entities for type-appropriate field hierarchy

[dougborg]

Summary

The Prefab UI cards we render today were built ad-hoc per tool and surface inconsistent (and often incomplete) information for each entity type. Real session 2026-05-05: agent looked at a get_variant_details card for tubeless tire sealant and had to guess the unit of measure ("250 = 250ml presumably") because UoM isn't on the variant card — even though it's a critical fact for any inventory decision.

Background

13 card builders today in katana_mcp_server/src/katana_mcp/tools/prefab_ui.py:

Builder	Tool entry point	Entity
build_search_results_ui	search_items	Search results
build_variant_details_ui	get_variant_details	Variant
build_item_detail_ui	get_item	Product/Material/Service
build_inventory_check_ui	check_inventory	Stock card
build_low_stock_ui	list_low_stock_items	Reorder list
build_order_preview_ui	create_purchase_order / create_sales_order / create_manufacturing_order previews	Order
build_order_created_ui	post-create	Order
build_fulfill_preview_ui / build_fulfill_success_ui	fulfill_order	Fulfillment
build_verification_ui	verify_order_document	Document
build_item_mutation_ui	create_item / modify_item	Item
build_receipt_ui	receive_purchase_order	Receipt
build_batch_recipe_update_ui	modify_manufacturing_order(update_recipe_rows=...)	MO recipe batch

Each was built when its tool shipped, with limited cross-pollination. The result is uneven information density, inconsistent visual hierarchy, and missing decision-critical fields.

Design proposal — per-entity field hierarchy

Every card should follow the same three-tier shape, but the specific fields in each tier vary by entity type:

Tier	Visual	Purpose	Field selection
Tier 1 — Identity	Header (title + badges)	"What is this?"	Name + SKU/order_no + type/status
Tier 2 — Decision metrics	Big number metrics	"What do I need to know to act?"	Per-entity: stock for variants, total + status for orders, totals + status for receipts, etc.
Tier 3 — Reference data	Small text grid	"Where is it / who supplies it / what are the IDs"	IDs, dates, supplier/customer name, location
Tier 4 — Actions	Footer buttons	"What's the most likely next step?"	Per-entity: most-likely follow-up (e.g., variant → check inventory; order → modify/fulfill)

The tiers stay constant; the field choices per tier are designed per entity type, not copied from a generic template.

Per-entity priority pass

Each builder should be redesigned with explicit answers to:

1. What's the agent trying to decide when looking at this card? (e.g., for variant: "should I order more / where is it / what does it consume in")
2. Which fields are tier 1 / 2 / 3 / 4? (with explicit cut-offs)
3. What's missing from the response model that the card needs? (e.g., UoM is on the parent item but not on VariantDetailsResponse; stock summary requires a separate fetch)
4. What actions are most likely next? (different per entity type)

Each builder gets its own focused issue tracking the answer to those four questions + the implementation. This umbrella tracks the rollup.

Sub-issues to file

Builder	Issue	Status
build_variant_details_ui	#TBD (filing alongside this umbrella)	filed first
build_item_detail_ui	TBD
build_inventory_check_ui	TBD (paired with #529)
build_low_stock_ui	TBD
build_order_preview_ui (PO / SO / MO)	TBD — may split per entity
build_order_created_ui	TBD
build_fulfill_preview_ui / build_fulfill_success_ui	TBD
build_verification_ui	TBD
build_item_mutation_ui	TBD
build_receipt_ui	TBD
build_batch_recipe_update_ui	TBD

(Sub-issues will be filed as the design work is done — this issue tracks the umbrella so subsequent work has context.)

Cross-cutting concerns to settle once

A few decisions affect every builder. Settle these on the variant-details starter first, then apply to the rest:

1. When to enrich with extra fetches — variant card should arguably show stock summary, but that's a separate API call. Threshold for "worth the round-trip": is the field so important to the typical decision that omitting it makes the card useless? (UoM yes / stock probably yes / config_attributes maybe / barcodes no)
2. How to render katana_url — currently a separate field; should it be a link button? An auto-attached button on every card?
3. Action button consistency — every entity card has 0-2 buttons today; should there be a standard action set per entity type?
4. Empty / N/A handling — when a field is None, do we omit it (current pattern, sometimes), show "N/A" (current pattern, other times), or use a small italic placeholder?

Out of scope

• Backend response model changes that aren't needed for cards (the response models are already exhaustive for most entities).
• Markdown rendering changes — this issue is specifically about the Prefab card UI shown in MCP-Apps-capable hosts.
• New entity tools — restructuring what already exists.

Discovered in

User session 2026-05-05 — agent had to guess unit-of-measure on a tubeless sealant variant because the variant card didn't show UoM, even though the parent item has it.

Related

• katana_mcp_server/src/katana_mcp/tools/prefab_ui.py — current builders
• katana_mcp_server/src/katana_mcp/tools/foundation/items.py — VariantDetailsResponse (the data the variant card reads)
• feat(mcp): check_inventory should expose per-location breakdown + location_id filter #529 — check_inventory per-location breakdown (relates to stock-card design)
• feat(mcp): make MCP reference resources discoverable to LLM agents (locations, tax_rates, etc.) #530 — resource discoverability (relates to what cross-references buttons should make)

[dougborg]

First sub-issue filed: #538 (build_variant_details_ui redesign)

[dougborg]

Lessons learned from #538 (variant_details — first card delivered)

PR #542 landed the first card redesign. Several cross-cutting decisions from the umbrella above got resolved by implementation; capturing them here so the rest of the rollout doesn't relitigate:

What worked well

• Four-tier framework holds up. Identity → metrics → reference → actions mapped cleanly onto the variant card without contortion. Recommend keeping the framework verbatim for sibling cards.
• Bulk parent enrichment via cache.get_many_by_ids is cheap. _enrich_variants_with_parent does at most 3 cache queries (products, materials, suppliers) regardless of variant count. The N+1 cost from "card needs parent context" is one well-placed bulk fetch, not a deal-breaker.
• Splitting fetch from render keeps the builder testable. _dict_to_variant_details(v, *, parent=None, supplier=None) stays synchronous and pure; the impl handles the async cache-fan-out separately. Future cards should follow the same shape.
• Per-entity helper functions inside prefab_ui.py keep complexity manageable. The variant builder grew over the ruff C901 complexity ceiling once the four tiers were filled in. Extracting _variant_header_section / _variant_reference_section / _variant_footer_section (and small helpers like _variant_supplier_line, _variant_barcode_line) brought it back under the limit and read better. Recommendation: any card with > ~15 conditional branches should extract per-section helpers from the start, not retroactively when ruff complains.

Cross-cutting decisions resolved

1. When to enrich with extra fetches — Yes, when the field is decision-critical AND lives on a related entity that's already in the cache. Variant → parent (uom, batch tracked, default supplier) qualified. Variant → live stock probably also qualifies and is the next call to make for that card.
2. How to render katana_url — Optional "View in Katana" button when the field is set, conditionally added to the footer. Don't auto-attach to every card — only ones where Katana has a useful destination page.
3. Action button consistency — Use entity-type as the discriminator. Material variants get "List MOs Using This"; product variants don't. Per-card decisions, not a global standard set.
4. Empty / N/A handling — Omit lines entirely when fields are None. The variant card has 9 conditional reference rows; rendering "N/A" for missing supplier / lead time / barcode produced visual noise in earlier iterations.

Sharp edge surfaced by code review

Cache IDs are not globally unique. Cache rows are keyed by (entity_type, id), so a product with id=42 and a material with id=42 are both legal. The first _enrich_variants_with_parent implementation merged products and materials into a single map keyed only by numeric ID, which would mis-attach parents on collision. Copilot caught it in review (#542 r3192338005 / r3192338016). Fixed by returning per-type maps and selecting based on which ID the variant carries.

Recommendation: any future card that does cross-entity enrichment should keep per-type maps, never merge by numeric ID alone. There's now a regression test pinning the variant case (test_enrich_variants_keeps_product_and_material_maps_separate).

What to do next

• File sub-issues for the remaining 11 cards using the variant-card template.
• Consider extracting the four-tier render scaffold into a helper that all cards opt into, once a second card is built and we can see what's truly common.
• Watch the empty-state behavior in production — if any card ends up with a tier rendering zero lines, surface a "No data yet" muted line so the empty card doesn't look broken.