MCP Tool Reference
The tools the MCP server exposes: 13 commerce/analytics reads (all readOnlyHint: true) and the builder suite — 18 tools for reading, editing, and previewing the storefront. Builder writes only ever stage drafts; nothing a tool does reaches shoppers without a human publishing.
Every tool declares a JSON Schema your client can validate against, and every schema is closed (additionalProperties: false) — unrecognised arguments are rejected with invalid_arguments rather than ignored.
At a glance
| Tool | Required scope | What it answers |
|---|---|---|
get_shop_info | STORE_SETTINGS · READ | Store name, currency, language, status |
get_store_metrics | ANALYTICS · READ | Revenue, orders, AOV, refunds, conversion for a period |
get_today_snapshot | ANALYTICS · READ | Today's sales and live visitor count |
get_top_products | ANALYTICS · READ | Best sellers by revenue or units |
get_top_customers | CUSTOMERS · READ | Highest-spending customers |
get_low_stock_products | PRODUCTS · READ | What's running out |
search_products | PRODUCTS · READ | Find a product by name, SKU, vendor, or type |
get_product | PRODUCTS · READ | Full detail for one product |
list_categories | CATEGORIES · READ | Categories and how many products each holds |
get_review_summary | REVIEWS · READ | Rating average, breakdown, pending moderation |
list_recent_orders | ORDERS · READ | Orders for a period |
get_order | ORDERS · READ | One order by number, with line items |
Builder tools
Every builder tool requires the THEME scope — READ for the read/preview tools, plus WRITE for the staging writes.
| Tool | Kind | What it does |
|---|---|---|
builder_list_pages | read | Pages of the storefront: names, slugs, types, visibility |
builder_get_page | read | One page's full component tree, SEO, and layout settings — healed to what merchants actually see |
builder_list_drafts | read | Open drafts and whether each holds unpublished changes |
builder_create_draft | write | A fresh named draft to stage work on |
builder_update_page | write | Replace a page's component tree on a draft (validated against the catalog; restore point first) |
builder_create_page / builder_delete_page | write | Custom pages, on a draft |
builder_get_theme / builder_update_theme | read / write | Theme settings groups, global navbar/footer — updates stage on a draft |
builder_upload_asset | write | Upload an image for use in sections |
builder_get_components | read | The component catalog: types, descriptions, tags, nesting rules — filterable |
builder_get_component | read | One component's full contract: default props and every editable setting |
builder_get_component_examples | read | Proven example trees + tree-authoring rules + the design-replication playbook |
builder_list_liquid_components | read | The store's Custom Liquid definitions |
builder_get_liquid_examples | read | Reference Liquid definitions + the authoring rules |
builder_upsert_liquid_component | write | Create/replace a Custom Liquid definition, on a draft |
builder_preview_page | read | Screenshot a page (live or draft) at desktop/tablet/mobile — returned as an image |
builder_capture_reference | read | Capture a reference design from a URL: screenshots + measured fonts, palette, section bands |
builder_compare_preview | read | Diff a draft render against a captured reference: mismatch score + visual diff image |
The component catalog is also exposed as MCP resources (taketheme://builder/components and taketheme://builder/components/{type}) for clients that read resources; the tools serve the same data for clients that don't.
The three preview tools need the deployment's headless-browser service. Where it isn't enabled they answer PREVIEW_UNAVAILABLE — every other tool is unaffected.
A tool whose scope your key doesn't carry still appears in tools/list; calling it returns a permission_denied tool error.
Date periods
Tools that report on a time window share the same three arguments. Relative windows are resolved server-side in UTC — assistants are unreliable at date arithmetic, so prefer a named period over computing dates yourself.
| Argument | Type | Description |
|---|---|---|
period | enum | The window to report on |
startDate | string | YYYY-MM-DD. Required only when period is custom |
endDate | string | YYYY-MM-DD. Required only when period is custom |
Accepted period values: today, yesterday, last_7_days, last_30_days, last_90_days, this_week, last_week, this_month, last_month, this_year, custom.
Weeks start on Monday. Day boundaries are UTC, matching the dashboard's KPI boundaries — so chat answers and dashboard figures agree.
Every response echoes the resolved window as a human-readable period label ("the last 7 days", "2026-06-01 to 2026-06-30") so the assistant can state which window it actually used.
get_shop_info
Basic facts about the store — worth calling once at the start of a session so money figures get quoted in the right currency.
Scope: STORE_SETTINGS · READ · Arguments: none
Returns
| Field | Description |
|---|---|
storeName | Store name |
currency | Currency the store sells in |
language | Primary language |
status | Account status (live, readonly, suspended, …) |
openedAt | When the store was created |
get_store_metrics
Headline sales and order metrics for a period, optionally against the previous equivalent period.
Scope: ANALYTICS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
period, startDate, endDate | — | last_30_days | See Date periods |
compareToPrevious | boolean | false | Also return the previous equivalent period and the change |
Returns
| Field | Description |
|---|---|
period | Resolved window label |
currency | Currency all money figures are in |
startDate / endDate | Resolved window as ISO timestamps |
metrics | The metric object below |
previousPeriod | Same shape, present when compareToPrevious is true |
change | Period-over-period change |
metrics contains: total_sales, total_orders, aov, unique_customers, total_items_sold, cancelled_orders, refunded_orders, refund_rate, fulfilled_orders, conversion_rate, repeated_customer_rate, cod_orders, prepaid_orders.
Metrics that could not be computed are omitted and named in _degraded.unavailableFields — see Partially available data.
get_today_snapshot
What's happening right now, rather than over a historical window.
Scope: ANALYTICS · READ · Arguments: none
Returns
| Field | Description |
|---|---|
period | Always "today (UTC)" |
currency | Store currency |
metrics | total_sales, total_orders, unique_customers for today |
activeVisitors | Visitors currently on the storefront, or null if unavailable |
get_top_products
Best-selling products for a period. Ranks by sales — for what's running out of stock use get_low_stock_products.
Scope: ANALYTICS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
period, startDate, endDate | — | last_30_days | See Date periods |
sortBy | revenue | quantity | revenue | Revenue answers "what makes the most money"; quantity answers "what moves the most" |
limit | integer 1–50 | 10 | How many products to rank |
Returns: period, rankedBy, currency, and products[] with productId, title, revenue, unitsSold, orders.
get_top_customers
Highest-spending customers, with lifetime spend and order count.
Scope: CUSTOMERS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
limit | integer 1–50 | 10 | How many customers to return |
Returns: customers[] with customerId, name, email, phone, totalSpent, ordersCount, lastOrderDate.
get_low_stock_products
Products at or below a stock threshold, lowest first.
Products with inventory tracking disabled, or with overselling allowed, are excluded — their stock count isn't meaningful. For products with variants, stock is the sum across variants.
Scope: PRODUCTS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
threshold | integer 0–1000 | 5 | Report products with this many units or fewer |
limit | integer 1–100 | 20 | How many products to return |
includeOutOfStock | boolean | true | Include products already at zero |
Returns: threshold, products[], and isEmpty — true meaning "nothing is running low", not "the lookup failed".
search_products
Find products by title, SKU, vendor, or product type. Use this first when a product is referred to by name and you need its id.
Scope: PRODUCTS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
query | string 1–200 (required) | — | Part of a title, a SKU, a vendor, or a product type |
limit | integer 1–50 | 10 | How many matches to return |
Returns: query, matchCount, isEmpty, and products[] with productId, title, sku, price, discountPrice, quantity, status, vendor.
get_product
Full detail for one product, by id or SKU. Pass at least one of the two — with neither, the tool returns found: false and a message telling you to search first.
Scope: PRODUCTS · READ
Arguments
| Argument | Type | Description |
|---|---|---|
productId | string | Product id, as returned by search_products. Preferred |
sku | string | Product SKU. SKUs are unique within a store |
Returns
found, plus a product object when found:
| Field | Description |
|---|---|
productId, title, sku | Identity |
price, discountPrice | Pricing |
status, vendor, productType | Classification |
categories | Category names |
stock | total, tracked, oversellAllowed, lastRestockedAt |
variants | title, sku, price, quantity per variant |
rating, reviewCount | Review summary for the product |
list_categories
Product categories with how many products each holds.
Scope: CATEGORIES · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
limit | integer 1–200 | 50 | How many categories to return |
Returns: categories[] with categoryId, name, productCount, subcategoryCount, plus isEmpty.
get_review_summary
The store-wide review picture.
Scope: REVIEWS · READ · Arguments: none
Returns
| Field | Description |
|---|---|
totalReviews | Total review count |
averageRating | Average rating to 2 decimal places, or null |
ratingBreakdown | Count per star rating |
byStatus | Count per moderation status |
pendingModeration | Reviews awaiting approval |
list_recent_orders
Orders for a period, newest first. Returns individual orders — for aggregate revenue use get_store_metrics.
Deleted and draft orders are excluded. Reads come from the canonical order records, so an order placed seconds ago is already visible.
Scope: ORDERS · READ
Arguments
| Argument | Type | Default | Description |
|---|---|---|---|
period, startDate, endDate | — | last_7_days | See Date periods |
status | enum | all | One of pending, confirmed, processing, shipped, delivered, cancelled, returned |
limit | integer 1–100 | 20 | How many orders to return |
Returns: period, totalMatching (all orders matching the filter), returned (how many are in this response), and orders[] with orderId, orderNumber, status, total, currency, paymentMethod, itemCount, placedAt, tags.
get_order
One order in full, by order number.
The number is accepted with or without a leading #, and a tracking number works too.
Scope: ORDERS · READ
Arguments
| Argument | Type | Description |
|---|---|---|
orderNumber | string 1–64 (required) | The order number as it appears in the dashboard, or a tracking number |
Returns
found, plus an order object when found:
| Field | Description |
|---|---|
orderId, orderNumber, status, placedAt | Identity and state |
itemCount, note, tags | Order context |
payment | total, subtotal, shipping, discount, currency, method, status |
items[] | name, quantity, unitPrice, variant |
A number that doesn't match returns found: false rather than an error — check the number and try again.
Order tools deliberately omit customer contact details, addresses, IPs, and risk scores. Use the REST API when an integration genuinely needs them.