AirShelf Catalog MCP Server

Search the AirShelf cross-vendor product catalog by natural-language query, across any brand and category (e.g. flowers, jewelry, skincare, chocolate, apparel, keyboards, office printers, industrial hardware). Returns ranked products with prices, specs, and per-row match accounting. Example queries: "birthday bouquet under $80", "minimalist gold necklace", "Toshiba A3 colour multifunction device", "tactile mechanical keyboard under $150". Result fields: • canonical_name — the exact catalog name of the product. • spec_absence_note — spec fields absent from this product's golden record; null when nothing is missing. • constraint_match_score, matched_criteria, missing_criteria — which of the query's spec constraints the row satisfies. • parsed.price_availability — all_null = true means every returned price is null, which is normal for B2B unlisted pricing; query_had_budget reports whether the query carried one. • parsed.weak_match — the catalog could not satisfy the query's constraints, so the rows are approximate. parsed.no_match — no product satisfies a hard constraint, and candidates violating it were excluded server-side. On a miss or near-miss for a specific brand+model the response may also carry a `tier3` block: a real-time lookup for the exact SKU asked about, which can appear alongside fuzzy-neighbour rows. • tier3.status = "resolved" — a single-source reading of the page at tier3.source_url, MPN-confirmed but not AirShelf-verified (tier3.verification is "live-unverified"). tier3.cached = true means it came from a recent prior lookup, with fetched_at recording when the page was read. • tier3.status = "abstain" — the lookup could not confirm the product exists as asked, so no specs, price, or availability were established. tier3.guidance describes the quote-request path. No tier3 block on a miss means the lookup did not run (disabled, rate-limited, or no parseable product identity in the query). Optional `market` (ISO 3166-1 alpha-2, e.g. "TH") biases the tier3 lookup toward that country's retailers and pricing and scopes its cache; without it, tier3 prices and availability may come from a different market.

Compare 2-10 catalog products side-by-side on their datasheet specs. Slugs come from search_catalog and are case-insensitive and dash-tolerant ("e-STUDIO 331AC", "toshiba-e-studio-331ac" and "e-studio331ac" all resolve to the same product). Returns one item per product with canonical_name and spec_absence_note (spec fields absent from that product's golden record). A slug that does not resolve comes back as not_found with a did_you_mean suggestion. Set `provenance` to include per-claim sources, a signed-attestation URL, and jwks_url.

Return the agentic build trace (BuilderRunTrace) for a SKU — every stage of the cold-run pipeline that produced this catalog row, including costs and outcomes.

List the AirShelf merchants whose catalogs are searchable and who can receive a quote request, across every category. Returns each merchant's name, slug, and product count; the slug is the `merchant` argument for request_quote.

Get the full golden record and latest price for one catalog product by slug ("<manufacturer>-<model>"). Returns the product's specs and provenance, plus canonical_name (its exact catalog name). In clients that render MCP Apps the response also draws one product card per call.

Discover candidate products for a buyer need the verified catalog does not cover, and verify each one. Takes a need in natural language (e.g. "best value home espresso machine", market "TH"), runs a live web search, and returns up to 3 candidates, each independently checked by a live lookup against a fetched source page. This applies when the need is described rather than named and search_catalog returned weak_match or nothing. For a specific brand+model, search_catalog is cheaper and returns the same live-lookup block on a miss. Response fields: • candidates[].verification — always "live-unverified": each candidate is a single-source reading of the page at candidates[].source_url, not an AirShelf-verified catalog record. • candidates[].status — "resolved" means MPN-confirmed against that page; "abstain" means the product could not be confirmed to exist as named, so no specs, price, or availability were established. • Candidates come from current web-search results, so they are a sample of what the market offers rather than a ranking. • status at the top level — "disabled" or "rate_limited" means no discovery ran. Optional `market` (ISO 3166-1 alpha-2) biases both discovery and each verification toward that country's retailers and scopes the lookup cache.

Send a quote request for catalog products to a merchant's sales team on behalf of a named buyer. This is a two-step, double opt-in flow. The first call emails a confirmation link to `contact.email` and returns status "confirmation_required" — at that point no lead exists and the merchant has not been contacted. The buyer opens that email and confirms, and confirming is what sends their details onward. A later call with the same arguments reports where the request stands: "awaiting_confirmation" while the email is unconfirmed, or "received" with a reference_number once the buyer has confirmed. Resolve `merchant` from list_merchants. For a brand list_merchants does not return (network-catalog brands), pass merchant:"airshelf-network" with brandSlug:"<manufacturer-slug>" and AirShelf routes the confirmed request to that brand.