# Product Catalog

> Discover product references, then hydrate selected Shopify products in one batch

Canonical URL: https://fa7e86e3d553:3005/tools/products

> **MCP v3 routing:** Pass the operation name to `lexsis_discover`, then call
> the returned router and action with these parameters inside `args`.

The catalogue is store-scoped and comes from Lexsis's synced Shopify read
model. `list_products` and `get_product` therefore see the same products.

## list_products

Search or browse product references. The response stays intentionally small:
each item contains only the Shopify product GID and handle. Pass the selected
IDs to `get_product` when full details are needed.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `workspace_id` | UUID | No | Required when the API key can access multiple workspaces |
| `store_id` | UUID | No | Required when the workspace has multiple active stores |
| `query` | string | No | Product search text |
| `search_mode` | `lexical`, `semantic`, or `hybrid` | No | Defaults to `hybrid` |
| `related_to_product_id` | Shopify product GID | No | Return products related to this product |
| `collection` | string | No | Filter by Shopify collection handle |
| `limit` | number (1–50) | No | Defaults to 20 |
| `cursor` | string | No | Opaque cursor returned by the preceding call |

`query` and `related_to_product_id` are mutually exclusive.

### Response

```json
{
  "items": [
    {
      "product_id": "gid://shopify/Product/7234567890",
      "handle": "hydrating-serum"
    }
  ],
  "total": 37,
  "returned": 1,
  "has_more": true,
  "next_cursor": "eyJvZmZzZXQiOjF9",
  "search_mode": "hybrid",
  "degraded_from": null,
  "catalog_synced_at": "2026-09-05T09:30:00Z"
}
```

`search_mode` reports the mode actually used. If semantic infrastructure is
temporarily unavailable, Lexsis returns lexical results and sets
`degraded_from`.

### Examples

```javascript
list_products({
  query: "five mukhi rudraksha",
  search_mode: "hybrid",
  limit: 10
})

list_products({
  related_to_product_id: "gid://shopify/Product/7234567890",
  limit: 8
})
```

## get_product

Hydrate one to twenty selected products in a single call. Products are returned
in request order. IDs that are not present in the selected store are reported
in `not_found`.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `product_ids` | Shopify product GID[] (1–20) | Yes | IDs returned by `list_products` |
| `workspace_id` | UUID | No | Required when workspace selection is ambiguous |
| `store_id` | UUID | No | Required when store selection is ambiguous |
| `handle` | string | Deprecated | Temporary single-product compatibility path |

### Response

```json
{
  "products": [
    {
      "id": "gid://shopify/Product/7234567890",
      "product_id": "gid://shopify/Product/7234567890",
      "title": "Hydrating Serum",
      "handle": "hydrating-serum",
      "description_html": "<p>A lightweight serum.</p>",
      "status": "ACTIVE",
      "total_inventory": 120,
      "product_type": "Skincare",
      "vendor": "Resolv Naturals",
      "tags": ["vegan"],
      "images": [
        {
          "url": "https://cdn.shopify.com/serum.jpg",
          "alt_text": "Hydrating Serum",
          "width": 1200,
          "height": 1200
        }
      ],
      "variants": [
        {
          "id": "gid://shopify/ProductVariant/9876543210",
          "title": "30 ml",
          "price": "45.00",
          "compare_at_price": null,
          "sku": "RES-HS-30",
          "available": true,
          "image_url": null,
          "selected_options": [{"name": "Size", "value": "30 ml"}]
        }
      ],
      "selling_plan_groups": []
    }
  ],
  "not_found": []
}
```

### Recommended workflow

```javascript
const refs = await list_products({ collection: "serums", limit: 12 })
const details = await get_product({
  product_ids: refs.items.slice(0, 5).map(product => product.product_id)
})
```

Always hydrate selected products before generating a page. Do not invent
product details, prices, images, variants, or subscription terms.