fix(vtex): repair broken GET_HOME_TOP_VIEWED_PRODUCTS and LIST_COLLECTIONS

[guitavano]

Summary

Fixes 4 issues reported against the VTEX MCP tools. Two were real bugs (fixed); two were API behaviors surfaced through misleading tool descriptions (now documented accurately).

Changes

🔴 GET_HOME_TOP_VIEWED_PRODUCTS — broken (fixed)

The handler returned the raw JSON array from the analytics endpoint. MCP structuredContent must be a record, so every call failed with -32602: expected record, received array. It was also the only home-analytics tool without an outputSchema.

Fix: wrap the payload as { items: [...] } and declare a matching outputSchema — the same normalization the tool adapter and orders-sales-card.ts already apply to array payloads.

🟡 LIST_COLLECTIONS — returned empty (fixed properly)

The tool used the generated getAllInactiveCollections operation (/api/catalog/pvt/collection/inactive), which by design returns only inactive collections — so stores with active collections got { items: [] }.

Fix: replaced it with a custom tool backed by /api/catalog_system/pvt/collection/search (the same endpoint SEARCH_COLLECTIONS uses), which returns all collections when paged with a blank term. Pagination is extracted into a pure collectAllCollections(fetchPage, pageSize) helper (stops on a short page, on reaching paging.total, or at a 100-page cap) with unit tests.

🟡 ORDERS_TIMELINE — totalValue always 0 (documented)

The primary home-orders-trend analytics endpoint reports only per-bucket order counts, not revenue, so totalValue is 0 on that path (the OMS fallback populates it). Not fixable without adding 24 OMS requests, defeating the single-request design. Description now points to ORDERS_SALES_CARD for hourly revenue.

🟡 GET_COLLECTION_PRODUCTS — automatic collections empty (documented)

Genuine VTEX behavior: automatic (rule-based) collections resolve their products at query time and return TotalRows: 0 from this endpoint. Description updated to explain it.

Testing

• New unit tests for collectAllCollections (multi-page, single-page early stop, empty, missing paging.total).
• Full vtex suite passes; source typechecks clean.

⚠️ Not verified against a live VTEX account — the collection-search response shape (items + paging.total) is based on VTEX's documented contract and the existing SEARCH_COLLECTIONS tool. Worth a sanity check against a real store before merge.

🤖 Generated with Claude Code

---

Summary by cubic

Fixes VTEX tools by repairing GET_HOME_TOP_VIEWED_PRODUCTS and updating LIST_COLLECTIONS to return all collections; also clarifies two API behaviors so callers get correct results and expectations.

• GET_HOME_TOP_VIEWED_PRODUCTS: previously returned a bare array and failed MCP validation; now wraps the result as { items: [...] } and declares an outputSchema.
• LIST_COLLECTIONS: replaced the inactive-only endpoint with a custom tool that pages the catalog search endpoint; adds input pageSize (default 50), returns { items, total }, and caps at 100 pages; includes a tested pagination helper.
• Documentation: notes that ORDERS_TIMELINE’s analytics path reports counts only (totalValue stays 0; use ORDERS_SALES_CARD for revenue) and that GET_COLLECTION_PRODUCTS returns empty for automatic collections.
• Rollout: no migrations required; callers should read items (and optional total) from LIST_COLLECTIONS.

^{Written for commit 4322fc9. Summary will update on new commits.}