Needle By D

List Brands

List all store brands grouped by first character (Arabic or English alphabet). Returns a browsable brand directory. Use this to show the buyer available brands or let them pick a brand to explore. After listing, use catalog-product-list with source=brands and source_value=<brand_id> to browse products from that brand.

Get Brand Details

Retrieve full brand details by ID, including name, description, logo, banner, and SEO metadata. Use this after catalog-brand-list when the buyer wants to learn about a specific brand. After getting brand details, use catalog-product-list with source=brands to see all products from this brand, then checkout-item-add to purchase.

List Categories

List store categories. Returns the root list by default, or the direct children of a specific category when parent_id is provided. Use this to discover category IDs cold-start — categories are not exposed elsewhere in the storefront MCP. After listing, use catalog-category-retrieve for full details with nested sub-categories, or catalog-product-list with source=categories and source_value=<category_id> to browse products in a category.

Get Category

Retrieve a category by ID, including its name, description, image, product count, and nested sub-categories (recursively included). Use this to let the buyer browse store categories and find products. Discover category IDs via catalog-category-list. After getting category details, use catalog-product-list with source=categories and source_value=<category_id> to browse all products in that category.

Browse Products

Browse and filter products from the store catalog. Supports 16 source types: latest (new arrivals), brands (by brand_id), categories (by category_id), search (by keyword), offers (on sale), top-rated, recently (viewed), related (similar products), selected (by product IDs), tags, wishlist, sales, reorder, best_selling, json, landing-page. Set filterable=true to get available filter facets (price range, brands, etc.) for refining results. After finding products, use catalog-product-retrieve for f

Search Products

Search products by keyword — a convenience shortcut for catalog-product-list with source "search". Matches product names, descriptions, and SKUs. Use this when the buyer asks "do you have...", "search for...", "looking for...", or "find me...". After finding matching products, use catalog-product-retrieve for details and checkout-item-add to add to cart.

Get Product Details

Retrieve full product details by ID, including images, videos, options (color, size, etc. with available values), variants/SKUs with pricing, star ratings, tags, brand, category, bundle items, and sold quantity. Use this after browsing or searching when the buyer wants to learn more about a specific product. Check price, sale_price, and variants (skus) fields. To purchase: use checkout-item-add with identifier_type=id for the base product, variant_id for a specific variant, or sku for SKU-based

Create Cart

Create a new empty shopping cart. Use this as the first step when a buyer wants to start shopping. Returns cart_id for subsequent operations and checkout_url — provide this link to the buyer whenever they say "checkout", "pay", "go to checkout", or "complete my order".

Get Cart

Retrieve current cart contents including items, quantities, pricing, applied coupons, and the checkout URL. Use this to confirm what's in the buyer's cart before they proceed to payment. The response always includes checkout_url — provide this link to the buyer when they're ready to complete their purchase. Items are included by default; set include_items=false to skip them when only totals/coupon/url are needed.

Proceed to Checkout

Get the checkout URL to redirect the buyer to complete payment. Use this when the buyer says "checkout", "pay", "pay now", "complete order", "go to checkout", or similar. The returned checkout_url is a direct link to the storefront payment page — provide it as a clickable link so the buyer can finalize their purchase. Includes cart summary (item count, total, currency) for confirmation.

Assign Cart to Account

Link a guest cart to the authenticated buyer's account. Call this after the buyer signs in, before proceeding to checkout, so their cart history and saved addresses are available. After assignment, use checkout-retrieve to get the updated cart and checkout URL for payment.

Apply Discount Code

Apply a coupon/discount code to the cart. Use this when the buyer provides a promo code or asks "do you have a discount code?". After applying, use checkout-retrieve to see the updated totals and checkout URL before proceeding to payment.

Remove Discount Code

Remove the applied coupon from the cart. Use this when the buyer asks to "remove the coupon" or "try a different code". After removal, use checkout-retrieve to see the updated totals and checkout URL before proceeding to payment.

Add to Cart

Add a product to the shopping cart. Set identifier_type to one of "id" (product ID), "variant_id" (specific variant/SKU), or "sku" (product SKU code), and put the value in identifier. Example: { cart_id, identifier_type: "id", identifier: "155055923", quantity: 1 }. Returns the full updated cart including line items (with each item's internal id, needed for checkout-item-update / checkout-item-remove) and checkout_url — provide this link to the buyer when they're ready to pay. Use catalog-produc

Update Cart Item

Update a cart item's quantity or options. The item_id is the internal cart item ID from the cart response (items[].id), NOT the product ID. Use this when the buyer says "change quantity", "I want 2 instead", or "update my cart". Returns the full updated cart including checkout_url for payment redirect.

Remove from Cart

Remove an item from the cart. The item_id is the internal cart item ID from the cart response (items[].id). Use this when the buyer says "remove this", "take it out of my cart", or "I don't want this anymore". Returns the full updated cart including checkout_url for payment redirect.