search_products

io.kifly/mcp · Verify this server

Search or browse Kifly's product catalog. Multilingual semantic search (100+ languages). Returns a JSON-LD ItemList with `kifly:totalCatalogSize`. When empty, `kifly:emptyReason` is 'empty_catalog' | 'no_matches_for_query' — on 'no_matches_for_query' tell the buyer nothing matched rather than guessing, then offer `kifly:suggestions` (related products — NOT matches) and `kifly:availableCategories` (what the catalog carries) so you can help without a second search. Results carry `kifly:relevanceScore` [0–1]; a semantic similarity floor filters out irrelevant results automatically. Omit `q` to browse. In cross-seller (network) results, each item's `kifly:seller` is just the seller's handle — look it up once in the ItemList's `kifly:sellers` map (keyed by handle) to read `delivery_fee_cents` and `delivery_coverage` — `nationwide:true` for all 50 states, a `states` list, or `coverage_configured:false` meaning the seller ships NOWHERE yet (empty `states` is NOT nationwide). `merchant_managed:true` is a THIRD case: the seller settles on their own checkout and sets shipping there, so quote no coverage and no delivery fee, and never report them as not shipping. `delivery_coverage.cities` may be capped — compare `cities.length` against `city_count` and call `get_seller` for the full list if fewer. Seller-scoped results carry the full record once at the list level (`kifly:seller` on the ItemList itself) instead. Each item also carries `kifly:variantId`. When a product has 2+ size/style variants, `kifly:productOptions` gives the option AXES (Color, Size, …) in the seller's own order, each listing only values a real variant exists for — ask the buyer one axis at a time, never recite the combination matrix. `kifly:hasVariant` lists every combination with its own `kifly:variantId` plus `kifly:optionValues` positionally aligned to those axes; match the buyer's answers against it and pass that `kifly:variantId` to `create_cart`/`add_to_cart`. Two fields are omitted when redundant: a variant's `name` when `kifly:optionValues` is present (it was those values joined by ' / '), and its `offers` when it costs the same as the product's own `offers` — a missing variant price means the product price applies, NOT that it is unpriced. No `kifly:productOptions` means the seller never declared options: read each variant's `name` instead. Capped at 100 variants; `kifly:variantCount` is set if the product has more. `image` is capped to 2 URLs per product — if `kifly:imageCount` is present, there are more than shown (not retrievable via this API; the cap is a hard limit, not a paginated detail). Each result's `offers` carries `kifly:purchasable`: when **false**, the seller is discovery-only (directory-tier or not yet able to charge) — checkout will hand off / fail, so present it as a referral, not a buy. `availability:InStock` is about stock, NOT buyability — read `kifly:purchasable` to decide whether to route the buyer to checkout. `availability:OutOfStock` means the seller lists it as SOLD OUT: still show it if the buyer asked for it, say it's sold out, and never try to cart it — `add_to_cart` returns 409 VARIANT_OUT_OF_STOCK. A variant entry carrying `kifly:inStock: false` is that size/style sold out while the product itself is still buyable — offer the other values, not that one (absent means in stock). **You can read the delivery fee and check coverage from here — no need to call `set_shipping_address` just to learn the cost.** **Pagination (browse only):** when `kifly:hasMore` is true, pass `kifly:nextCursor` as `cursor` to fetch the next page. **Seller filter:** pass `seller_handle` to scope results to one seller. **Category filter:** free-text, case-insensitive (e.g. 'fashion'). **Multiple queries:** pass `q` as an array (up to 5) to try several phrasings in one call instead of N separate searches. **Before checkout, call `set_shipping_address`.**