What this MCP does
Searches Kapruka products, checks delivery, creates guest orders with payment links, and tracks order fulfillment.
Capabilities
Tools
8
tools
kapruka_check_delivery
Check whether Kapruka can deliver to a given city on a given date, and at what rate.
Returns the flat delivery rate (LKR), whether the requested date is available,
and â if not â the next available date plus reason. Kapruka delivers as a
single shipment per order at one flat rate regardless of item count.
Pass `product_id` whenever the customer has named a product: the answer then
also checks that ITEM's delivery scope (restaurant food, hotel cakes and
liquor only reach selected cities, typically the Colombo area). With a
product_id, `available` is true only if the date is open AND the item is
deliverable to that city. When `item_deliverable` is false, offer the
customer one of the returned `deliverable_cities` or an island-wide
alternative â do not attempt kapruka_create_order with the same city, it
will be rejected. An unknown product_id is silently ignored (no item fields
in the result), so check `item_deliverable` is present before relying on it.
product_id also selects the SAME-DAY rule the checkout applies to that item:
vendor-delivered items (restaurant food) can go today until late afternoon;
ordinary items move to the next date; ordinary same-day is only possible early
in the morning near Colombo. So a check without product_id can differ from one
with it â always pass it once an item is chosen. When `available` is false,
offer `next_available_date`. Do not interpret the `reason` text (it is the
website's wording and may say slots are full when the real cause is the cutoff).
Perishable codes (CAKE*, FLOWER*, COMBO*) additionally get a freshness
warning when the chosen delivery date is more than 1 day out.
Args:
params (CheckDeliveryInput):
- city (str): Canonical city name (e.g. 'Colombo 03', 'Galle')
- delivery_date (Optional[str]): YYYY-MM-DD; defaults to today (LK time)
- product_id (Optional[str]): Check the city against this item's delivery scope
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Delivery feasibility + rate in the requested format.
JSON schema:
{
"city": str,
"now": str, # ISO timestamp, Sri Lanka time
"checked_date": str, # YYYY-MM-DD
"available": bool, # date open AND (if product_id) item deliverable
"rate": number, # flat LKR rate per order
"currency": "LKR",
"reason": str | null, # date-block message, else "This item is not delivered to <City>."
"next_available_date": str|null, # only for date blocks
"item_deliverable": bool, # only when product_id resolved to a real product
"deliverable_cities": [str], # only when item_deliverable=false (capped at 60)
"perishable_warning": str | null # populated when product_id is perishable
}
Read only
Open world
Input schema
{'type': 'object', '$defs': {'CheckDeliveryInput': {'type': 'object', 'title': 'CheckDeliveryInput', 'required': ['city'], 'properties': {'city': {'type': 'string', 'title': 'City', 'maxLength': 100, 'minLength': 2, 'description': "Canonical city name (use kapruka_list_delivery_cities to find one). Examples: 'Colombo 03', 'Anuradhapura', 'Galle'."}, 'product_id': {'anyOf': [{'type': 'string', 'maxLength': 80}, {'type': 'null'}], 'title': 'Product Id', 'default': None, 'description': "Product ID to check the city AGAINST THAT ITEM'S delivery scope. Food, hotel cakes and liquor only reach selected cities â\x80\x94 always pass this when a customer names a product and a city, and only promise delivery if `available` is true. Also adds a freshness warning for perishable codes (cake/flower/combo) when the date is >1 day out."}, 'delivery_date': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Delivery Date', 'default': None, 'description': 'Target delivery date in ISO format (YYYY-MM-DD), Sri Lanka time. Omit to check today.'}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' (default) or 'json'"}}, 'additionalProperties': False}}, 'title': 'kapruka_check_deliveryArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/CheckDeliveryInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_check_deliveryOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_create_order
Create a guest-checkout order on Kapruka and return a click-to-pay link.
Builds a Kapruka order from the supplied cart + recipient + delivery + sender,
then returns a checkout URL the customer opens in a browser to complete payment.
No Kapruka account is required. Prices are locked for the lifetime of the link
(60 minutes) â the customer pays exactly the quoted grand total even if the
catalog price changes meanwhile.
Free public tier limits: 30 orders per hour per client IP. Cart up to 30 items,
quantity up to 99 per item. A fresh idempotency key is generated per call so
retries on transient errors return the same checkout URL rather than duplicates.
Args:
params (CreateOrderInput):
- cart (list[CartItem]): 1â30 lines. Catalogue line: product_id, quantity (default 1), optional icing_text (cakes only).
Custom cake line: custom_cake_request_id + phone â orders the cake Kapruka staff quoted via
kapruka_custom_cake_status (status must be 'quoted'; quantity is always 1; never send a price).
Lines can be mixed in one order â one delivery fee covers everything; the whole cart must be
deliverable to delivery.city. Only place a custom cake order after the customer clearly
accepted the quoted total.
- recipient (Recipient): name + phone (E.164 +9477⦠or local 077â¦)
- delivery (Delivery): address, city (must be Kapruka-deliverable â use kapruka_list_delivery_cities), location_type (house/apartment/office/other, default house), date (YYYY-MM-DD, today-or-future Asia/Colombo), optional instructions
- sender (Sender): name + anonymous flag
- gift_message (Optional[str]): Up to 300 chars
- currency (str): LKR (default), USD, GBP, AUD, EUR
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Order confirmation with checkout URL.
JSON schema:
{
"checkout_url": str, # Open in browser to pay (no login required)
"order_ref": str, # e.g. "ORD-20260520-7823"
"order_id": str, # id used by the bank-deposit flow
"summary": {
"items_total": number,
"delivery_fee": number,
"addons_total": number,
"grand_total": number, # items_total + delivery_fee + addons_total
"currency": str
},
"expires_at": str # ISO 8601 â link stops working after this
}
Error: "Error (<code>): <message>" on failure. Common codes:
empty_cart, missing_field, past_delivery_date, product_not_found,
product_out_of_stock, city_not_deliverable (city not in the network at
all), date_not_deliverable, city_not_deliverable_for_item.
Custom cake lines add: request_not_found (404 â wrong id/phone or staff
removed it), quote_not_ready (409 â staff haven't priced it; check
kapruka_custom_cake_status later), quote_expired (410 â submit a new
kapruka_custom_cake_request). summary.items_total may differ from the
quoted cake total by a few rupees (USD round-trip) â quote the summary
numbers when asking for payment.
city_not_deliverable_for_item (HTTP 422): at least one cart item (food /
hotel cake / liquor) cannot reach delivery.city. NOTHING is created â the
API never places a partial order and neither should you. The error text
names every blocking item and lists the cities the whole cart CAN go to.
Tell the customer which item blocks the order and offer to (a) change the
city to one of those, or (b) remove/replace that item. Never retry with
the same city. Avoid this entirely by calling kapruka_check_delivery with
`product_id` for each limited item before ordering.
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'Sender': {'type': 'object', 'title': 'Sender', 'required': ['name'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'maxLength': 80, 'minLength': 1, 'description': 'Sender name on the gift card.'}, 'anonymous': {'type': 'boolean', 'title': 'Anonymous', 'default': False, 'description': "If true, gift card shows 'Anonymous' instead of the sender name."}}, 'additionalProperties': False}, 'CartItem': {'type': 'object', 'title': 'CartItem', 'properties': {'phone': {'anyOf': [{'type': 'string', 'maxLength': 30, 'minLength': 7}, {'type': 'null'}], 'title': 'Phone', 'default': None, 'description': 'The customer.phone the custom cake request was made with (custom cake lines only).'}, 'quantity': {'anyOf': [{'type': 'integer', 'maximum': 99, 'minimum': 1}, {'type': 'null'}], 'title': 'Quantity', 'default': None, 'description': 'Quantity (1â\x80\x9399, default 1). Catalogue lines only.'}, 'icing_text': {'anyOf': [{'type': 'string', 'maxLength': 120}, {'type': 'null'}], 'title': 'Icing Text', 'default': None, 'description': 'Cake icing text. Silently ignored for non-cake products. Catalogue lines only.'}, 'product_id': {'anyOf': [{'type': 'string', 'maxLength': 80, 'minLength': 3}, {'type': 'null'}], 'title': 'Product Id', 'default': None, 'description': "Kapruka product ID (e.g. 'cakeXX000000'). Catalogue line."}, 'custom_cake_request_id': {'anyOf': [{'type': 'string', 'maxLength': 80, 'minLength': 6}, {'type': 'null'}], 'title': 'Custom Cake Request Id', 'default': None, 'description': "request_id of a custom cake that kapruka_custom_cake_status reports as 'quoted'. Orders the staff-quoted cake (quantity 1). Requires `phone`."}}, 'description': 'One cart line â\x80\x94 EITHER a catalogue product OR a quoted custom cake.\n\nCatalogue line: {"product_id": "...", "quantity": 1, "icing_text": "..."}\nCustom cake line: {"custom_cake_request_id": "...", "phone": "+9477..."}\nThe custom cake line is turned into the staff-quoted cake server-side\n(name, picture, price); quantity is always 1 and no price is ever sent.', 'additionalProperties': False}, 'Delivery': {'type': 'object', 'title': 'Delivery', 'required': ['address', 'city', 'date'], 'properties': {'city': {'type': 'string', 'title': 'City', 'maxLength': 100, 'minLength': 2, 'description': 'Must be a Kapruka delivery city (canonical name from kapruka_list_delivery_cities) that EVERY cart item can reach. The order ships as one shipment, so food / hotel cake / liquor items restrict the whole cart to their city set â\x80\x94 verify with kapruka_check_delivery(city, product_id) first; otherwise the order is rejected with city_not_deliverable_for_item.'}, 'date': {'type': 'string', 'title': 'Date', 'description': 'Delivery date in YYYY-MM-DD (Asia/Colombo). Must be today or future.'}, 'address': {'type': 'string', 'title': 'Address', 'maxLength': 250, 'minLength': 3, 'description': 'Street address.'}, 'instructions': {'anyOf': [{'type': 'string', 'maxLength': 250}, {'type': 'null'}], 'title': 'Instructions', 'default': None, 'description': 'Free-form delivery instructions.'}, 'location_type': {'type': 'string', 'title': 'Location Type', 'default': 'house', 'description': 'One of: house, apartment, office, other.'}}, 'additionalProperties': False}, 'Recipient': {'type': 'object', 'title': 'Recipient', 'required': ['name', 'phone'], 'properties': {'name': {'type': 'string', 'title': 'Name', 'maxLength': 80, 'minLength': 1, 'description': 'Recipient name shown on the order.'}, 'phone': {'type': 'string', 'title': 'Phone', 'maxLength': 30, 'minLength': 7, 'description': 'Recipient phone â\x80\x94 E.164 (+9477â\x80¦) or local SL (077â\x80¦) format.'}}, 'additionalProperties': False}, 'CreateOrderInput': {'type': 'object', 'title': 'CreateOrderInput', 'required': ['cart', 'recipient', 'delivery', 'sender'], 'properties': {'cart': {'type': 'array', 'items': {'$ref': '#/$defs/CartItem'}, 'title': 'Cart', 'maxItems': 30, 'minItems': 1, 'description': '1â\x80\x9330 items.'}, 'sender': {'$ref': '#/$defs/Sender'}, 'currency': {'type': 'string', 'title': 'Currency', 'default': 'LKR', 'description': 'Pricing currency. Supported: LKR, USD, GBP, AUD, EUR.'}, 'delivery': {'$ref': '#/$defs/Delivery'}, 'recipient': {'$ref': '#/$defs/Recipient'}, 'gift_message': {'anyOf': [{'type': 'string', 'maxLength': 300}, {'type': 'null'}], 'title': 'Gift Message', 'default': None, 'description': 'Optional gift card message.'}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' (default) or 'json'."}}, 'additionalProperties': False}}, 'title': 'kapruka_create_orderArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/CreateOrderInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_create_orderOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_get_product
Fetch full details for a single Kapruka product by its product ID.
Returns name, description, price (with optional currency conversion), stock status,
images, variants, shipping info, delivery scope, and a direct product URL.
Delivery scope: most gifts ship island-wide, but restaurant food, hotel cakes
and liquor only reach a limited city set (typically the Colombo area). The
`delivery` object is the authority â search results do NOT carry it. When
`delivery.island_wide` is false, tell the customer up front that the item is
delivered only to selected cities, and confirm their city with
kapruka_check_delivery(city, product_id) before promising anything. If
`deliverable_city_count` exceeds the returned list, the list is truncated â
say "and more", don't treat it as complete.
Note: Some IDs starting with 'CATSYM' are category landing pages, not purchasable
products â this tool will flag those clearly.
Args:
params (GetProductInput):
- product_id (str): Kapruka product ID (e.g. 'cakeXX000000')
- currency (str): Price currency â LKR (default), USD, GBP, AUD, EUR
- type (Optional[str]): Optional type hint (e.g. 'specialgifts')
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Product details in the requested format.
JSON schema:
{
"id": str,
"name": str,
"description": str,
"summary": str,
"price": {"amount": float, "currency": str},
"compare_at_price": {"amount": float, "currency": str} | null,
"in_stock": bool,
"stock_level": str, # "low" | "medium" | "high"
"category": {"id": str, "name": str, "slug": str, "path": str},
"variants": [{"id": str, "name": str, "sku": str, "price": {...},
"in_stock": bool, "stock_level": str, "attributes": {...}}],
"images": [str], # list of full-resolution image URLs
"attributes": {"type": str, "subtype": str, "weight": str, "vendor": str},
"shipping": {"ships_from": str, "ships_internationally": bool, "restricted_countries": [str]},
"delivery": {
"island_wide": bool,
"deliverable_city_count": int, # only when island_wide=false; TRUE total
"deliverable_cities": [str] # only when island_wide=false; capped at 60
},
"rating": null,
"url": str
}
Error: "Error: <message>" on failure.
Read only
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'GetProductInput': {'type': 'object', 'title': 'GetProductInput', 'required': ['product_id'], 'properties': {'type': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Type', 'default': None, 'description': "Optional product type hint passed to the API (e.g. 'specialgifts'). Rarely needed."}, 'currency': {'type': 'string', 'title': 'Currency', 'default': 'LKR', 'description': 'Price currency. Supported: LKR, USD, GBP, AUD, EUR'}, 'product_id': {'type': 'string', 'title': 'Product Id', 'maxLength': 80, 'minLength': 3, 'description': "Kapruka product ID (e.g. 'cakeXX000000', 'EF_PC_CHOC0V2774P00065')"}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' for human-readable output, 'json' for raw structured data."}}, 'additionalProperties': False}}, 'title': 'kapruka_get_productArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/GetProductInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_get_productOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_list_categories
List top-level Kapruka product categories by name with browse URLs.
Returns the site's NAVIGATION categories plus the public Kapruka.com URL for each
category landing page â useful for sending a customer to a category to browse.
These names are NOT search filters. kapruka_search_products filters on search
facets, a different vocabulary (e.g. navigation 'Electronic' vs facet 'Electronics',
'Cakes' vs 'Kapruka Cakes'); every search response lists its valid facet names
under facets.categories. Use those for `category`, never these. Internal IDs and
product counts are not exposed. Results are cached for 30 minutes server-side.
Args:
params (ListCategoriesInput):
- depth (int): Sub-category levels to include, 1 or 2 (default 1)
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Category tree in the requested format.
JSON schema:
{
"categories": [
{
"name": str,
"url": str, # kapruka.com category landing page
"children": [{"name": str, "url": str, "children": [...]}]
}
]
}
Error: "Error: <message>" on failure.
Read only
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'ListCategoriesInput': {'type': 'object', 'title': 'ListCategoriesInput', 'properties': {'depth': {'type': 'integer', 'title': 'Depth', 'default': 1, 'maximum': 2, 'minimum': 1, 'description': 'How many levels of sub-categories to include (1 or 2). Default 1.'}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' for human-readable output, 'json' for raw structured data."}}, 'additionalProperties': False}}, 'title': 'kapruka_list_categoriesArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/ListCategoriesInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_list_categoriesOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_list_delivery_cities
List or search Sri Lankan cities Kapruka delivers to.
Use the `query` param to filter (e.g. "colombo" â all Colombo zones,
"anur" â Anuradhapura). Without a query you get the first 25 cities
alphabetically, which is rarely what an agent needs â pass a query.
Returns canonical city names (use these as the `city` argument to
kapruka_check_delivery) plus any common aliases / vernacular spellings.
Args:
params (ListDeliveryCitiesInput):
- query (Optional[str]): Partial match filter
- limit (int): Max results, 1â50 (default 25)
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Cities list in the requested format.
JSON schema:
{
"cities": [{"name": str, "aliases": [str]}],
"total_matched": int,
"showing": int
}
Read only
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'ListDeliveryCitiesInput': {'type': 'object', 'title': 'ListDeliveryCitiesInput', 'properties': {'limit': {'type': 'integer', 'title': 'Limit', 'default': 25, 'maximum': 50, 'minimum': 1, 'description': 'Max cities to return (1â\x80\x9350).'}, 'query': {'anyOf': [{'type': 'string', 'maxLength': 50}, {'type': 'null'}], 'title': 'Query', 'default': None, 'description': 'Filter cities by partial match against name or aliases (case-insensitive). Omit to see the first `limit` cities alphabetically.'}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' (default) or 'json'"}}, 'additionalProperties': False}}, 'title': 'kapruka_list_delivery_citiesArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/ListDeliveryCitiesInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_list_delivery_citiesOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_render_options_card
Render 1-4 products as ONE shareable JPEG "menu" card and return its URL.
The card shows each product's photo with a big numbered badge (the ref you
assign), and its name + price printed under the photo. Built for chat
commerce (WhatsApp): send the image, tell the customer "reply 1, 2 or 3",
and they pick without opening links. No AI is involved â the image is
server-composited from the live catalog data, so prices match what the
product tools return.
Ref numbering contract: refs are yours to assign â use sequential numbers
per conversation and NEVER reuse one (if the first card was 1-3, the next
card starts at 4). A number must keep meaning the same product for the whole
conversation.
Args:
params (RenderOptionsCardInput):
- items (list[CardProduct]): 1-4 of {product_id, ref}
- currency (str): LKR (default), USD, GBP, AUD, EUR
- courtesy ({currency, per_usd}, optional): home-currency figure printed
under each USD price ("â JPY 2,544"); the caller's rate, echoed back
- footer_note (str, optional): appended to the footer reply hint
Returns:
str: JSON:
{
"card_url": str, # public JPEG URL â send this as the image
"items": [{"ref": int, "product_id": str, "name": str,
"price": {"amount": float, "currency": str},
"price_note": str | null, "url": str}],
"courtesy": {"currency": str, "per_usd": float} | null, # what was printed, or null
"unavailable": [str] # product_ids that failed to load (omitted from card)
}
Error: "Error: <message>" when no product could be loaded.
Read only
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'Courtesy': {'type': 'object', 'title': 'Courtesy', 'required': ['currency', 'per_usd'], 'properties': {'per_usd': {'type': 'number', 'title': 'Per Usd', 'description': 'Units of that currency per 1 USD, as used for the chat text.', 'exclusiveMaximum': 1000000, 'exclusiveMinimum': 0}, 'currency': {'type': 'string', 'title': 'Currency', 'pattern': '^[A-Za-z]{3}$', 'maxLength': 3, 'minLength': 3, 'description': "ISO-4217 code of the customer's home currency, e.g. JPY."}}, 'description': "A home-currency approximation to print under each USD price.\n\nThe CALLER supplies the rate it used for its own chat text, so the card and\nthe text agree to the unit; the card never converts on its own. Only\napplied when the card is priced in USD â\x80\x94 the courtesy figure describes\nwhat a USD charge will look like on the customer's statement.", 'additionalProperties': False}, 'CardProduct': {'type': 'object', 'title': 'CardProduct', 'required': ['product_id', 'ref'], 'properties': {'ref': {'type': 'integer', 'title': 'Ref', 'maximum': 99, 'minimum': 1, 'description': "The reference number to print on this product's badge (customer replies with it). Assign sequentially per conversation and NEVER reuse a number."}, 'product_id': {'type': 'string', 'title': 'Product Id', 'maxLength': 80, 'minLength': 3, 'description': 'Kapruka product ID (from a search result).'}}, 'additionalProperties': False}, 'RenderOptionsCardInput': {'type': 'object', 'title': 'RenderOptionsCardInput', 'required': ['items'], 'properties': {'items': {'type': 'array', 'items': {'$ref': '#/$defs/CardProduct'}, 'title': 'Items', 'maxItems': 4, 'minItems': 1, 'description': '1-4 products to show side by side.'}, 'courtesy': {'anyOf': [{'$ref': '#/$defs/Courtesy'}, {'type': 'null'}], 'default': None, 'description': "Optional: print 'â\x89\x88 <home currency>' under each USD price (see Courtesy). Ignored unless currency is USD."}, 'currency': {'type': 'string', 'title': 'Currency', 'default': 'LKR', 'description': 'Price currency: LKR, USD, GBP, AUD, EUR.'}, 'footer_note': {'anyOf': [{'type': 'string', 'maxLength': 60}, {'type': 'null'}], 'title': 'Footer Note', 'default': None, 'description': "Optional short note appended to the footer's reply hint, e.g. 'Checkout charges USD'."}}, 'additionalProperties': False}}, 'title': 'kapruka_render_options_cardArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/RenderOptionsCardInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_render_options_cardOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_search_products
Search for products on Kapruka.com by keyword, with optional category filter and pagination.
Returns a ranked list of matching products with prices, stock status, images, and URLs,
plus the category facets available for the query (facets.categories) â the names that
work in `category` to narrow the same search.
Supports cursor-based pagination â pass next_cursor from one response into the next call.
Pagination is capped at 3 pages per query to discourage catalog enumeration; for broader
discovery, refine the query or narrow with a facet instead.
Queries must be at least 3 characters and contain specific terms â pure stopword queries
(e.g. "the", "a an") are rejected.
Relevance: the API matches ANY single query word, so extra words add loosely related
results rather than narrowing. Search the thing the customer wants (the head noun) and
check the product names actually contain it before presenting them.
Prices and min_price/max_price are both in `currency` â pass the customer's own budget
in their own currency; do not convert it.
Search results carry NO delivery-scope information. Food, hotel cakes and liquor
are delivered only to selected cities â never infer deliverability from a search
hit. Before quoting delivery on a specific item, call kapruka_get_product (read
`delivery.island_wide`) or kapruka_check_delivery with `product_id`.
Args:
params (SearchProductsInput):
- q (str): Search query (e.g. 'birthday cake', 'roses', 'tea gift'). Min 3 chars.
- category (Optional[str]): A facet name from a previous search's facets.categories
- limit (int): Results per page, 1â50 (default 10)
- cursor (Optional[str]): Pagination cursor from previous response
- currency (str): LKR (default), USD, GBP, AUD, EUR
- min_price (Optional[float]): Min price (inclusive) in `currency`
- max_price (Optional[float]): Max price (inclusive) in `currency`
- in_stock_only (bool): Restrict to in-stock items (default false)
- sort (str): 'relevance' | 'price_asc' | 'price_desc' | 'newest' | 'bestseller'
- include_stubs (bool): Deprecated, no effect
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Search results in the requested format.
JSON schema:
{
"results": [
{
"id": str,
"type": "product",
"name": str,
"summary": str,
"price": {"amount": float | null, "currency": str},
"compare_at_price": {"amount": float, "currency": str} | null,
"in_stock": bool,
"stock_level": str,
"image_url": str | null,
"category": {"id": str, "name": str, "slug": str},
"rating": null,
"ships_internationally": bool,
"url": str
}
],
"next_cursor": str | null, # null after page 3 even if upstream has more
"total_estimate": int, # index hits for the query words (any-word match)
"applied_filters": {"q": str, "category": str, "currency": str, ...},
"facets": {"categories": [{"name": str, "count": int}]},
"category_filter_dropped": str, # only when `category` was not a facet here
"valid_categories": [str] # ...and the facet names that are
}
Error: "Error: <message>" or "No products found for '<query>'" on failure.
Read only
Open world
Idempotent
Input schema
{'type': 'object', '$defs': {'SearchProductsInput': {'type': 'object', 'title': 'SearchProductsInput', 'required': ['q'], 'properties': {'q': {'type': 'string', 'title': 'Q', 'maxLength': 200, 'minLength': 3, 'description': "Search query (e.g. 'birthday cake', 'roses', 'chocolates for mom'). Min 3 characters, must contain specific terms (not stopwords only)."}, 'sort': {'type': 'string', 'title': 'Sort', 'default': 'relevance', 'description': "Sort order: 'relevance' (default), 'price_asc', 'price_desc', 'newest', 'bestseller'."}, 'limit': {'type': 'integer', 'title': 'Limit', 'default': 10, 'maximum': 50, 'minimum': 1, 'description': 'Number of results to return (1â\x80\x9350).'}, 'cursor': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Cursor', 'default': None, 'description': "Pagination cursor from a previous search response's 'next_cursor' field."}, 'category': {'anyOf': [{'type': 'string'}, {'type': 'null'}], 'title': 'Category', 'default': None, 'description': "Filter by a SEARCH FACET name. Every search response lists the valid ones for its words under facets.categories (e.g. 'Kapruka Cakes', 'Fresh Flowers', 'Electronics', 'Mobile Phones', 'Greeting Cards') â\x80\x94 search once without a category, then narrow with one of those names. Department words ('Cakes', 'Flowers') and names from kapruka_list_categories (the site's navigation, a different vocabulary) are NOT facet names. Case and spacing don't matter. A name that isn't a facet for this query is dropped: you get results without it plus the list of valid names."}, 'currency': {'type': 'string', 'title': 'Currency', 'default': 'LKR', 'description': 'Price currency. Supported: LKR, USD, GBP, AUD, EUR'}, 'max_price': {'anyOf': [{'type': 'number', 'minimum': 0}, {'type': 'null'}], 'title': 'Max Price', 'default': None, 'description': 'Maximum price (inclusive), in the requested currency.'}, 'min_price': {'anyOf': [{'type': 'number', 'minimum': 0}, {'type': 'null'}], 'title': 'Min Price', 'default': None, 'description': 'Minimum price (inclusive), in the requested currency.'}, 'in_stock_only': {'type': 'boolean', 'title': 'In Stock Only', 'default': False, 'description': 'If true, only return products currently in stock.'}, 'include_stubs': {'type': 'boolean', 'title': 'Include Stubs', 'default': False, 'description': "Deprecated, has no effect. Kept so existing callers don't break: since 2026-09-26 the API never returns category landing pages from a search."}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' for human-readable output, 'json' for raw structured data."}}, 'additionalProperties': False}}, 'title': 'kapruka_search_productsArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/SearchProductsInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_search_productsOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
kapruka_track_order
Look up status and delivery progress for a Kapruka order by order number.
Returns current status (received / confirmed / out-for-delivery / delivered /
cancelled), the recipient and delivery details on file, a timestamped progress
timeline, the cart contents, and flags for whether a delivery photo or video is
available. Use this after a customer has placed and paid for an order and reads
back the order number from their confirmation email or the order complete page.
The order number is NOT the `order_ref` returned by kapruka_create_order
(which is the pre-payment checkout reference). Once the customer completes
payment in the browser, Kapruka emails them a separate order number â that
is what this tool expects.
Args:
params (TrackOrderInput):
- order_number (str): Kapruka order number (e.g. 'VIMP34456CB2')
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Order tracking details in the requested format.
JSON schema:
{
"order_number": str,
"pnref": str, # internal payment reference (numeric; not the same as order_number)
"status": str, # received | confirmed | shipped | delivered | cancelled | ...
"status_display": str, # human label
"order_date": str, # human-formatted, Asia/Colombo
"delivery_date": str, # human-formatted
"shipped_date": str | null,
"amount": str, # LKR string (e.g. "15500.00")
"payment_method": str,
"comments": str | null,
"recipient": {"name": str, "phone": str, "address": str, "city": str},
"greeting_message": str | null,
"special_instructions": str | null,
"progress": [{"step": str, "timestamp": str}],
"live_tracking_available": bool,
"has_delivery_video": bool,
"has_delivery_photo": bool,
"items": [{"product_id": str, "name": str, "quantity": int, "selling_price": float}]
}
Error: "Error: <message>" on failure (e.g. order not found).
Read only
Open world
Input schema
{'type': 'object', '$defs': {'TrackOrderInput': {'type': 'object', 'title': 'TrackOrderInput', 'required': ['order_number'], 'properties': {'order_number': {'type': 'string', 'title': 'Order Number', 'maxLength': 40, 'minLength': 4, 'description': "Order number from the customer's Kapruka order confirmation email or the order complete page on kapruka.com (e.g. 'VIMP34456CB2'). This is NOT the same as the order_ref returned by kapruka_create_order â\x80\x94 the customer must complete payment first; the Kapruka order number is then emailed to them."}, 'response_format': {'type': 'string', 'title': 'Response Format', 'default': 'markdown', 'description': "'markdown' (default) or 'json'."}}, 'additionalProperties': False}}, 'title': 'kapruka_track_orderArguments', 'required': ['params'], 'properties': {'params': {'$ref': '#/$defs/TrackOrderInput'}}}
Output schema
{'type': 'object', 'title': 'kapruka_track_orderOutput', 'required': ['result'], 'properties': {'result': {'type': 'string', 'title': 'Result'}}}
History
Recent tool changes
Changed
kapruka_check_delivery
Sept. 27, 2026, 2:53 a.m.
Changed
kapruka_search_products
Sept. 27, 2026, 2:53 a.m.
Changed
kapruka_list_categories
Sept. 27, 2026, 2:53 a.m.
Changed
kapruka_render_options_card
Sept. 23, 2026, 2:53 a.m.
Changed
kapruka_create_order
Sept. 23, 2026, 2:53 a.m.
Changed
kapruka_search_products
Sept. 23, 2026, 2:53 a.m.
Changed
kapruka_get_product
Sept. 23, 2026, 2:53 a.m.
Changed
kapruka_render_options_card
Sept. 21, 2026, 3 a.m.
Changed
kapruka_create_order
Sept. 19, 2026, 2:51 a.m.
Added
kapruka_check_delivery
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_list_delivery_cities
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_render_options_card
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_track_order
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_create_order
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_search_products
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_get_product
Sept. 17, 2026, 12:35 p.m.
Added
kapruka_list_categories
Sept. 17, 2026, 12:35 p.m.
Discover
Similar MCP servers
AgentLot Marketplace
io.agentlot/marketplace
Enables agents and users to discover, bid on, purchase, deliver, and settle paid digital services and compute work.
apex-x1
xyz.apexfaucet/apex-x1
Provides X1 and Arc token screening, liquidity and exit-risk checks, wallet and bridge data, non-custodial token operations, comm…
SpellBook Finance
com.spellbook-finance/mcp
Provides Magic: The Gathering and other trading-card market prices, buylist offers, arbitrage analysis, sealed-product EV, seller…
API Direct
io.apidirect/api-direct
Searches and retrieves data from social networks, news and Google services, while also providing Amazon product, seller, ranking,…
Digital Manager Guru
io.github.mcp-dir/guru-mcp
Provides Digital Manager Guru checkout, customer, transaction, subscription, affiliate, coupon, blocklist, and digital-product sa…
Pagar.me
io.github.mcp-dir/pagarme-mcp
Connects to Pagar.me to manage customers, cards, orders, charges, invoices, payment captures, confirmations, retries, refunds, an…
amazon-product-research-mcp
com.webotee/amazon-product-research-mcp
Researches Amazon products, brands, sellers, buy-box activity, sourcing profitability, category competition, and supplier opportu…
AgentLux
io.github.agentlux/agentlux
Operates an agent avatar marketplace with item generation, purchases, creator earnings, public profiles, social activity, and ERC…