Skip to main content

Changes and confirmations

Beta

The MCP server is in beta. You can use it, but its tools, limits and behavior can still change. The changelog announces changes.

Every tool that changes data takes dryRun: true. A dry run checks everything a real run checks and returns exactly what would change, without changing anything.

Previews and the user's yes​

Each dry run returns a nextStep that tells the assistant whether it may go ahead:

ChangenextStep saysThe assistant
A rename, a move, a new order, hide or show (update_category without other texts, order_category_products)Write now if this is exactly what the user asked forWrites right after a matching dry run when the user named exactly what to change
Everything else: changes to many categories, texts the assistant writes or overwrites, links, main categories, new categories and deletesShow the user and write only after their yesShows the dry run and waits for the user to agree

This dry run of link_products puts two products in a category and makes it their main category, so it waits for the user's yes:

{
"filter": { "skus": ["LZ-1010-80", "LZ-1010-50"], "statuses": "any", "kind": "any" },
"matched": 2,
"dryRun": true,
"nextStep": "Show the user what this changes, and write only after they say yes.",
"changes": [
{
"add": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"wouldAdd": 2,
"alreadyIn": 0
},
{
"main": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"wouldMakeMain": 2,
"alreadyMain": 0
}
],
"gatewayCallsNeeded": 3,
"gatewayCallsLeftThisMinute": 594,
"sample": [
{ "productId": 10512, "sku": "LZ-1010-80", "name": "Leitz 180° lever arch file A4 80 mm" },
{ "productId": 10513, "sku": "LZ-1010-50", "name": "Leitz 180° lever arch file A4 50 mm" }
]
}

In the response, "statuses": "any" means the filter covers every status, the default when products are named by SKU or id. To ask for every status in a request, send "statuses": [].

Most assistants also ask the user to approve a tool that changes data. That approval comes on top of the dry run.

Texts​

  • A text write fills empty values. It replaces an existing value only with overwrite: true, and the assistant says so when it uses it.
  • A write changes only the languages it names. The other languages stay as they are.
  • set_category_texts can fill one field across many categories from a template with {name}, {parent} and {path}.
  • A name must stay filled in the catalog's default language. A slug must be lowercase and URL-friendly.

New categories​

  • New categories start hidden. The assistant makes them visible with update_category (hidden: false) once they have content.
  • Every new category needs a name in the catalog's default language. Slugs are generated from the names.
  • One create_categories call can create a small tree: each category can name a parent created earlier in the same call.
  • Categories can't move from one catalog to another. A move stays within the catalog.

Main categories​

  • Every product and cluster has one main category, which applies across all catalogs.
  • link_products with main adds the items to that category first when they aren't in it yet.
  • An item is never left without a main category. Removing items from their main category keeps them there, reported as keptBecauseMain, unless the same call gives them a new main.

Deleting categories​

  • By default only empty categories are deleted. includeSubcategories takes the whole branch, and unlinkProducts takes its products and clusters out first.
  • When items have their main category in the branch, the call needs reassignMainTo, the category that becomes their new main category.
  • The root category of a channel's catalog can't be deleted.
  • A delete can't be undone. Hiding a category with update_category can.

When product lists show a change​

Product lists and searches come from a search index that follows changes after a short delay. A product or cluster added to or removed from a category shows after about 10 seconds, a new main category after about 15 seconds and a new order after up to a minute. Category data itself changes immediately.

  • A write result says when lists show the change, in listsShowThisIn.
  • A list or search made shortly after the same user's change carries recentChange, so an assistant knows the list may not show it yet.
  • The tools plan from the user's own recent changes, so an assistant can reorder or remove a product right after linking it.

list_category_products on Filing, four seconds after the two products from the example above were added:

{
"category": { "categoryId": 3120, "name": "Filing", "path": "Office supplies", "catalogueId": 17 },
"total": 0,
"page": 1,
"pages": 0,
"hasMore": false,
"items": [],
"recentChange": {
"secondsAgo": 4,
"note": "changed moments ago: this list may not show it yet (links and main categories take about 10 to 15 seconds)"
}
}

Partial results​

FieldMeaningWhat to do
truncatedA scan stopped at its limitNarrow the filter, for example to one branch
cappedAtMaxTargetsMore items matched than one call changes (500 at most). The rest is untouched.Split the job with a narrower filter, for example per category or manufacturer
stoppedEarlyThe time budget ended a change partwayFollow the result's note. Most calls continue when run again and skip what was written. A text overwrite lists the categories that are left.

The assistant tells the user when an answer is partial and never presents a partial count as the total.

See also​