refactor(mcp): extract _format_money helper + standardize currency rendering (#752)

**Helper extraction (closes #744)**

Pulled the duplicated ``f"${amount:,.2f} {currency or 'USD'}"`` block
out of three create-card builders (PO create, SO create, PO receipt)
plus the variant-detail price display into a single
``_format_money(amount, currency)`` helper in ``prefab_ui.py``.

**Babel for currency-aware formatting**

The old inline format hard-coded ``$`` and 2 decimals — wrong for
EUR (``$1,500.00 EUR`` instead of ``€1,500.00``), wrong for JPY
(JPY has no decimals on the wire), wrong for any currency whose
symbol isn't ``$``. ``_format_money`` now delegates to
``babel.numbers.format_currency`` so the rendered string picks up
the right symbol, decimal-digit count, and grouping per ISO 4217.

Examples (verified in new ``TestFormatMoney`` cases):
- ``_format_money(1500.0, "USD")`` → ``"$1,500.00"``
- ``_format_money(1500.0, "EUR")`` → ``"€1,500.00"``
- ``_format_money(1500, "JPY")`` → ``"¥1,500"`` (no decimals)
- ``_format_money(None, "USD")`` → ``"$0.00"``
- Unknown ISO code → ``"XYZ1,500.00"`` (code prefix, doesn't raise)

Added ``babel>=2.17`` to ``katana_mcp_server/pyproject.toml`` (it
was already a transitive dep via mkdocs-material; promoting to a
direct dependency).

**Two Katana currency concepts, both surfaced**

The helper's docstring records the two-currency model so future
callers know which to pass:

- **Transaction currency** — ``SalesOrder.currency`` /
  ``PurchaseOrder.currency``; the currency line totals (``total``,
  ``price_per_unit``, ``cogs_value``) are denominated in.
- **Factory base currency** — ``Factory.base_currency_code``;
  the tenant home currency. Pass this when formatting
  ``*_in_base_currency`` amounts. Threading factory data into
  card builders is the remaining piece — currently only the
  three migrated Total metrics receive transaction currency; the
  variant-price builder falls back to USD because the factory
  record isn't plumbed into it yet. Tracked as a follow-up.

**MCP boundary fixes for the #749 schema changes**

PR #749 reclassified two MO recipe row fields from ``number`` to
``string`` (their wire format). The consumer in
``_recipe_row_info_from_attrs`` passed the strings straight
through to ``RecipeRowInfo``'s ``float | None`` field annotations
— it worked via pydantic coercion but was inconsistent with the
boundary pattern established in #741 for SalesOrderRow. Wrapped
the affected reads with ``float_or_none(unwrap_unset(...))`` to
match. Also fixed ``MO operation row`` consumers for the five
string-on-wire fields that were already strings before #749.

And ``invoicing_status`` on ``SalesOrderSummary`` / the get-SO
response was passed bare while its sibling status fields used
``enum_to_str``. After #749 made it an actual enum, the bare
pass relied on StrEnum coincidence; brought it in line with
``status`` / ``production_status``.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dougborg

katana_mcp_server/pyproject.toml

@@ -47,6 +47,10 @@ dependencies = [
     # context for the DB driver. Declared explicitly for the #342 typed
     # cache; without it, async session operations raise at runtime.
     "greenlet>=3.0.0",
+    # ISO 4217 currency-aware money formatting (Prefab UI ``Total`` metrics).
+    # Picks per-currency symbol, decimal digits, and separators so non-USD
+    # orders render correctly (€1,500.00, ¥1500 with no decimals, etc.).
+    "babel>=2.17",
 ]
 
 # Note: Development dependencies like mcp-hmr require Python >=3.12

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

@@ -60,6 +60,7 @@
     apply_date_window_filters,
     coerce_enum,
     enum_to_str,
+    float_or_none,
     iso_or_none,
     make_json_result,
     make_tool_result,
@@ -838,16 +839,20 @@ def _recipe_row_info_from_attrs(
         sku=sku,
         display_name=display_name,
         notes=unwrap_unset(row.notes, None),
-        planned_quantity_per_unit=unwrap_unset(row.planned_quantity_per_unit, None),
-        total_actual_quantity=unwrap_unset(row.total_actual_quantity, None),
+        planned_quantity_per_unit=float_or_none(
+            unwrap_unset(row.planned_quantity_per_unit, None)
+        ),
+        total_actual_quantity=float_or_none(
+            unwrap_unset(row.total_actual_quantity, None)
+        ),
         total_consumed_quantity=unwrap_unset(row.total_consumed_quantity, None),
         total_remaining_quantity=unwrap_unset(row.total_remaining_quantity, None),
         ingredient_availability=unwrap_unset(row.ingredient_availability, None),
         ingredient_expected_date=iso_or_none(
             unwrap_unset(row.ingredient_expected_date, None)
         ),
         batch_transactions=batch_infos,
-        cost=unwrap_unset(row.cost, None),
+        cost=float_or_none(unwrap_unset(row.cost, None)),
         created_at=iso_or_none(unwrap_unset(row.created_at, None)),
         updated_at=iso_or_none(unwrap_unset(row.updated_at, None)),
         deleted_at=iso_or_none(unwrap_unset(row.deleted_at, None)),
@@ -885,13 +890,19 @@ def _operation_row_info_from_attrs(row: Any) -> OperationRowInfo:
         assigned_operators=assigned,
         completed_by_operators=completed,
         active_operator_id=unwrap_unset(row.active_operator_id, None),
-        planned_time_per_unit=unwrap_unset(row.planned_time_per_unit, None),
-        planned_time_parameter=unwrap_unset(row.planned_time_parameter, None),
-        total_actual_time=unwrap_unset(row.total_actual_time, None),
+        planned_time_per_unit=float_or_none(
+            unwrap_unset(row.planned_time_per_unit, None)
+        ),
+        planned_time_parameter=float_or_none(
+            unwrap_unset(row.planned_time_parameter, None)
+        ),
+        total_actual_time=float_or_none(unwrap_unset(row.total_actual_time, None)),
         total_consumed_time=unwrap_unset(row.total_consumed_time, None),
         total_remaining_time=unwrap_unset(row.total_remaining_time, None),
-        planned_cost_per_unit=unwrap_unset(row.planned_cost_per_unit, None),
-        total_actual_cost=unwrap_unset(row.total_actual_cost, None),
+        planned_cost_per_unit=float_or_none(
+            unwrap_unset(row.planned_cost_per_unit, None)
+        ),
+        total_actual_cost=float_or_none(unwrap_unset(row.total_actual_cost, None)),
         cost_per_hour=unwrap_unset(row.cost_per_hour, None),
         cost_parameter=unwrap_unset(row.cost_parameter, None),
         group_boundary=unwrap_unset(row.group_boundary, None),

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

@@ -917,7 +917,7 @@ def _variant_for_row(row: Any) -> Any:
                 location_id=so.location_id,
                 status=enum_to_str(so.status),
                 production_status=enum_to_str(so.production_status),
-                invoicing_status=so.invoicing_status,
+                invoicing_status=enum_to_str(so.invoicing_status),
                 created_at=iso_or_none(so.created_at),
                 delivery_date=iso_or_none(so.delivery_date),
                 total=so.total,
@@ -1335,7 +1335,7 @@ def _display_name_for(v: Any) -> str | None:
         order_created_date=iso_or_none(unwrap_unset(so.order_created_date, None)),
         status=enum_to_str(unwrap_unset(so.status, None)),
         production_status=enum_to_str(unwrap_unset(so.production_status, None)),
-        invoicing_status=unwrap_unset(so.invoicing_status, None),
+        invoicing_status=enum_to_str(unwrap_unset(so.invoicing_status, None)),
         product_availability=enum_to_str(unwrap_unset(so.product_availability, None)),
         product_expected_date=iso_or_none(unwrap_unset(so.product_expected_date, None)),
         ingredient_availability=enum_to_str(

katana_mcp_server/src/katana_mcp/tools/prefab_ui.py

@@ -48,6 +48,7 @@
 
 from typing import Any, Literal
 
+from babel.numbers import format_currency
 from prefab_ui.actions import Action, SetState, ShowToast
 from prefab_ui.actions.mcp import CallTool, SendMessage, UpdateContext
 from prefab_ui.actions.navigation import OpenLink
@@ -830,7 +831,12 @@ 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}"
+        # Variant prices are tenant-wide and don't carry a per-record
+        # currency on the wire; they're denominated in
+        # ``Factory.base_currency_code``. The factory record isn't
+        # plumbed into this builder yet, so the format falls back to
+        # USD via :func:`_format_money` — wiring tracked in #751.
+        return f"{_format_money(p, None)}{suffix}"
 
     with PrefabApp(state={"variant": variant}, css_class="p-4") as app, Card():
         with CardHeader(), Column(gap=1):
@@ -1339,6 +1345,36 @@ def _format_cost(cost: float | int | None) -> str:
     return f"{cost:.2f}"
 
 
+def _format_money(amount: float | int | None, currency: str | None) -> str:
+    """Format a Metric ``Total`` value using ISO 4217 currency-aware rules.
+
+    Delegates to :func:`babel.numbers.format_currency` so the rendered string
+    picks up the right symbol, decimal-digit count, and grouping for the
+    currency (``$1,500.00`` for USD, ``€1,500.00`` for EUR, ``¥1,500`` for
+    JPY with no decimals). Integer ``amount`` is passed through unchanged
+    — Babel handles ``int`` and ``float`` identically.
+
+    Katana has two currency concepts:
+
+    - **Transaction currency** — ``SalesOrder.currency`` / ``PurchaseOrder.currency``;
+      the currency the line totals (``total``, ``total_cost``, ``price_per_unit``)
+      are denominated in. Pass this when formatting per-order amounts.
+    - **Factory base currency** — ``Factory.base_currency_code``; the tenant's
+      home currency. Pass this when formatting ``*_in_base_currency`` amounts
+      (converted totals).
+
+    Falls back to ``USD`` when ``currency`` is missing so the widget reads
+    cleanly even on the path where the response hasn't populated the field.
+    Unlike :func:`_format_cost`, never returns ``—`` — every Total-style
+    metric has a value to show (``$0.00`` for unset).
+    """
+    return format_currency(
+        0 if amount is None else amount,
+        currency or "USD",
+        locale="en_US",
+    )
+
+
 def _iso_date_only(value: object) -> str:
     """Trim a serialized ISO datetime to its ``YYYY-MM-DD`` prefix.
 
@@ -1850,7 +1886,9 @@ def build_po_create_ui(
     Four-tier framework (#537):
     - Tier 1 — Identity: title, order_number badge, PREVIEW/CREATED state
       badge, status badge, entity_type badge (regular/outsourced).
-    - Tier 2 — Decision metrics: Total ($X.XX <currency>), Line Items.
+    - Tier 2 — Decision metrics: Total (formatted per
+      ``response["currency"]`` via :func:`_format_money` — symbol + decimal
+      precision picked by Babel from the ISO 4217 code), Line Items.
     - Tier 3 — Reference: supplier, location, notes, plus warnings.
     - Tier 4 — Actions: Confirm + Cancel via the direct-apply rail
       (Confirm fires ``tools/call`` directly and pushes the structured
@@ -1861,7 +1899,7 @@ def build_po_create_ui(
     status = response.get("status")
     entity_type = response.get("entity_type")
     total_cost = response.get("total_cost")
-    currency = response.get("currency") or "USD"
+    currency = response.get("currency")
     item_count = response.get("item_count")
 
     apply_action = _build_apply_action_direct(confirm_tool, confirm_request)
@@ -1885,7 +1923,7 @@ def build_po_create_ui(
             if total_cost is not None or item_count is not None:
                 with Row(gap=4):
                     if total_cost is not None:
-                        Metric(label="Total", value=f"${total_cost:,.2f} {currency}")
+                        Metric(label="Total", value=_format_money(total_cost, currency))
                     if item_count is not None:
                         Metric(label="Line Items", value=str(item_count))
             _render_party_line(
@@ -1945,7 +1983,7 @@ def build_so_create_ui(
     order_number = response.get("order_number") or "N/A"
     status = response.get("status")
     total = response.get("total")
-    currency = response.get("currency") or "USD"
+    currency = response.get("currency")
     item_count = response.get("item_count")
     delivery_date = response.get("delivery_date")
 
@@ -1966,7 +2004,7 @@ def build_so_create_ui(
             if total is not None or item_count is not None or delivery_date:
                 with Row(gap=4):
                     if total is not None:
-                        Metric(label="Total", value=f"${total:,.2f} {currency}")
+                        Metric(label="Total", value=_format_money(total, currency))
                     if item_count is not None:
                         Metric(label="Line Items", value=str(item_count))
                     if delivery_date:
@@ -2736,7 +2774,9 @@ def build_receipt_ui(
             if response.get("total_cost") is not None:
                 Metric(
                     label="PO Total",
-                    value=f"${response['total_cost']:,.2f} {response.get('currency') or 'USD'}",
+                    value=_format_money(
+                        response["total_cost"], response.get("currency")
+                    ),
                 )
 
             block_warnings, regular_warnings = _split_warnings(response.get("warnings"))

katana_mcp_server/tests/test_prefab_ui.py

@@ -15,6 +15,7 @@
 from katana_mcp.tools.prefab_ui import (
     PREVIEW_APPLY_COACHING,
     PREVIEW_APPLY_DIRECT_COACHING,
+    _format_money,
     build_batch_recipe_update_ui,
     build_fulfill_preview_ui,
     build_fulfill_success_ui,
@@ -112,6 +113,32 @@ def _assert_valid_prefab(app: PrefabApp) -> None:
     _assert_state_bindings_resolve(result)
 
 
+class TestFormatMoney:
+    """``_format_money`` delegates to Babel for currency-aware rendering."""
+
+    def test_usd_amount(self):
+        assert _format_money(1500.0, "USD") == "$1,500.00"
+
+    def test_eur_uses_euro_symbol(self):
+        assert _format_money(1500.0, "EUR") == "€1,500.00"
+
+    def test_jpy_has_no_decimals(self):
+        # JPY's ISO definition has zero decimal places — Babel drops them
+        # automatically; a hand-rolled formatter would render "¥1500.00".
+        assert _format_money(1500, "JPY") == "¥1,500"
+
+    def test_missing_currency_falls_back_to_usd(self):
+        assert _format_money(1500.0, None) == "$1,500.00"
+
+    def test_none_amount_renders_as_zero(self):
+        assert _format_money(None, "USD") == "$0.00"
+
+    def test_unknown_currency_keeps_code_prefix(self):
+        # Babel gracefully handles unknown ISO codes by prefixing the code
+        # instead of raising — keeps the helper total over partial.
+        assert _format_money(1500.0, "XYZ") == "XYZ1,500.00"
+
+
 class TestBuildSearchResultsUI:
     def test_with_items(self):
         items = [