MCP: úkoly a vrácení změn

Nástěnka úkolů obchodu i se seznamem členů týmu pro přiřazení a deník změn, které zapsaly nástroje. Vracení změn potřebuje oprávnění undo:write, proto ho k zápisovým klíčům přidávejte vždycky.

Nástroje volá klient přes server MCP na doméně obchodu, například https://muj-eshop.cz/api/mcp, a v odpovědi na tools/list dostane jen ty, na jejichž oprávnění klíč dosáhne. Jak server mluví, kdy se ptá člověka a jak se změny vracejí, popisuje článek MCP server.

U každého nástroje stojí oprávnění, které chce, jestli se server před provedením zeptá člověka a kudy, jestli volání strhne kredity obchodu nebo peníze z karty, co vrací pro deník změn a jakou větu o důsledku člověk v potvrzení uvidí. Všechno z toho se vyhodnocuje z téhož kódu, podle kterého se server rozhoduje. Popisy parametrů jsou převzaté ze schématu, které server posílá v tools/list; kde se v něm text obrací přímo k modelu, je tady převedený do vykání. Povinnost parametru platí uvnitř objektu, ve kterém parametr leží.

Před zápisem, který přepisuje nebo maže, před útratou kreditů nebo platbou kartou a před hledáním mimo obchod se server ptá člověka a do té doby neprovede nic. Nejdřív použije schválení, které pro totéž volání se stejnými hodnotami už v administraci leží schválené. Jinak se zeptá formulářem, když ho klient deklaruje a politika akce ho dovoluje; formulář potvrzuje ten, kdo drží klíč, takže před ukradeným klíčem takové potvrzení nechrání. Otázka ve formuláři nese pod nadpisem „Co se změní“ tytéž řádky jako stránka schválení. Klient s elicitací URL dostane odkaz na stránku schválení v administraci a klient bez elicitace odmítnutí approval_required s odkazem v _meta; po schválení volání zopakuje se stejnými hodnotami. Na stránce schválení rozhoduje jen přihlášený člověk, kterého u každé akce jmenuje odrážka Potvrzení přes MCP, a účet podpory SHOPZI nikdy. Když politika nedovoluje nic, co klient umí, přijde odmítnutí confirmation_required a neprovede se nic. Výsledek potvrzeného volání nese v _meta["cz.shopzi/confirmation"] údaj, že akci potvrdil člověk a kde (form nebo approval), a v obsahu českou větu pro model, u placené akce i s cenou a zůstatkem kreditů z dotazu. Na otázku formulářem je 15 minut, schválení na stránce platí 60 minut, pokud u akce není uvedeno jinak.

Zápisové nástroje vracejí v poli change_id ID záznamu v deníku změn; co pole u kterého nástroje nese, říká jeho odrážka Deník změn. Změnu z deníku vrací shopzi_undo_change podle jejího druhu: obnoví předchozí hodnoty, u skladu zapíše vyrovnávací pohyb, u běžné ceny zapíše návrat do 30denní historie cen (nic z ní nemaže) a změnu, která už opustila obchod nebo stála peníze (odeslaný e-mail, stržené kredity, platbu kartou), odmítne s vysvětlením.

shopzi_list_tasks

Vrátí nástěnku úkolů s filtrem podle sloupce, priority, řešitele (me jen v panelu Agenta, none nepřiřazené, nebo ID člena týmu) a hledaného textu. S includeTeam: true přidá seznam členů týmu (ID, jméno, role) pro přiřazení úkolu.

• Oprávnění: tasks:read, u klíče „Úkoly a seznam členů týmu (čtení)“.
• Druh: čtení (readOnlyHint).
• Potvrzení přes MCP: ne.
• Kredity a platba kartou: ne.

shopzi_list_tasks: parametry

• status (jedna z hodnot todo, in_progress, review a done; nepovinný): Filtr sloupce nástěnky.
• priority (jedna z hodnot low, medium, high a urgent; nepovinný): Filtr priority: low | medium | high | urgent.
• search (text; nepovinný): Hledá v názvu a popisu úkolu.
• assignedTo (text; nepovinný): Řešitel: me | none nebo ID člena. me = přihlášený (jen v panelu Agenta), none = nepřiřazené.
• includeTeam (true nebo false; nepovinný): true = vrátí i team pro přiřazení úkolu.
• limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete.
• offset (celé číslo od 0 do 100000, výchozí 0; nepovinný): Kolik položek přeskočit. 0 = první stránka.

shopzi_manage_task

Založí, upraví (včetně přiřazení člena týmu ze seznamu, který vrací shopzi_list_tasks) nebo smaže úkol na nástěnce. Všechny tři operace jde vrátit a smazaný úkol se vrátí se stejným ID.

• Oprávnění: tasks:write, u klíče „Úkoly (zápis)“.
• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).
• Potvrzení přes MCP: podle operation, viz seznam níž.
• Kredity a platba kartou: ne.
• Deník změn: výsledek nese change_id. ID záznamu v deníku. Předejte ho do shopzi_undo_change.

shopzi_manage_task: operace

• create (založit)
  • Potvrzení přes MCP: ne.
• update (upravit)
  • Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.
• delete (smazat)
  • Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.

shopzi_manage_task: parametry

• operation (jedna z hodnot create, update a delete; povinný): Co s úkolem: create založí nový, update změní pole, delete ho smaže.
• taskId (text; nepovinný): ID úkolu z shopzi_list_tasks. Jen pro update a delete; u create se neposílá.
• fields (objekt; nepovinný): Pole úkolu. U create povinné a s title, u update jen pole ke změně, u delete se neposílá.
• fields.title (text; nepovinný): Název úkolu, max 200 znaků.
• fields.description (text nebo null; nepovinný)
• fields.status (jedna z hodnot todo, in_progress, review a done; nepovinný): Sloupec nástěnky.
• fields.priority (jedna z hodnot low, medium, high a urgent; nepovinný)
• fields.assignedToId (UUID nebo null; nepovinný): ID člena ze shopzi_list_tasks (includeTeam), null = nepřiřazeno.
• fields.dueAt (text nebo null; nepovinný): Termín v ISO tvaru, nebo null.
• idempotencyKey (text, 1 až 200 znaků; nepovinný): Klíč idempotence. Stejný klíč = stejný zápis: opakované volání vrátí původní výsledek a NEZAPÍŠE podruhé. Použijte vlastní náhodný řetězec pro každou zamýšlenou změnu; při opakování po chybě sítě pošlete tentýž.

shopzi_list_changes

Vrátí deník změn, které v obchodě zapsaly nástroje, od nejnovějších i s tím, jestli už je někdo vrátil, s filtrem podle stavu, druhu položky a jedné konkrétní položky. Odtud je change_id pro shopzi_undo_change.

• Oprávnění: undo:write, u klíče „Vrácení změn agenta (zápis)“.
• Druh: čtení (readOnlyHint).
• Potvrzení přes MCP: ne.
• Kredity a platba kartou: ne.

shopzi_list_changes: parametry

• status (jedna z hodnot applied, reversed, failed a pending; nepovinný): Filtr stavu. Vrátit lze jen applied.
• entityType (jedna z hodnot appearance, attribute, attribute_definition_order, attribute_definition_snapshot, attribute_preset_batch, bank_payment, bank_payment_queue, blog_category, blog_post, blog_post_entity, builder_page, business_hours, campaign, category, category_order, category_snapshot, category_tree, comgate_request, company_identity, contact_identity, contact_message_archive, custom_domain, customer, customer_b2b, discount_bulk_status, discount_code, discount_code_snapshot, feed_categories, feed_channel, feed_overrides, import_job_accept, info_panel_order, info_panel_snapshot, invoice_email, invoice_paid, legal_documents, media, onboarding_state, order_billing, order_fulfillment, order_payment, order_quotation, order_status, page, page_blocks, popup, product, product_ai_run_cancel, product_ai_run_regenerate, product_ai_run_revert, product_ai_run_start, product_attributes, product_bulk_status, product_bundle, product_categories, product_links, product_media, product_modifiers, product_page_content, product_sample_purge, product_translations, product_variants, product_vat, purchase_order, return_approval, return_claim, return_restock, return_shipment, return_status, review, search_facet, search_pin, search_redirect, search_synonym, segment, seo_audit_run, settings, shipping_method, shop_launch, site_gate, size_guide_order, size_guide_snapshot, stock_movement, stocktake, stocktake_item, storage_usage, storefront_layout, subscription_plan, supplier, supplier_price_list, task, task_snapshot, url_redirect, variant_cost, vendor, vendor_brand_import, vendor_snapshot, wholesale_price a wholesale_terms; nepovinný): Filtr podle toho, čeho se změna týkala.
• entityId (text; nepovinný): Jen změny jedné konkrétní položky.
• limit (celé číslo od 1 do 100, výchozí 25; nepovinný): Počet položek na stránku, 1 až 100. Velká stránka se do jedné odpovědi nemusí vejít a nástroj ji pak odmítne, což stojí krok navíc: berte jen tolik položek, kolik na odpověď opravdu potřebujete.
• offset (celé číslo od 0 do 100000, výchozí 0; nepovinný): Kolik položek přeskočit. 0 = první stránka.

shopzi_undo_change

Vrátí jednu změnu z deníku: obnoví předchozí hodnoty, založenou položku smaže a u skladu zapíše vyrovnávací pohyb. Když položku mezitím někdo upravil, vrácení odmítne a vypíše, která pole se změnila.

• Oprávnění: undo:write, u klíče „Vrácení změn agenta (zápis)“.

• Druh: zápis, který umí přepsat nebo smazat existující data (destructiveHint).

• Potvrzení přes MCP: ano: formulář v klientu, který potvrdí ten, kdo drží klíč; jinak odkaz na stránku schválení přes elicitaci URL; jinak odkaz na stránku schválení v odmítnutí approval_required. Na stránce schválení rozhoduje vlastník nebo manažer obchodu.

• Kredity a platba kartou: ne.

• Deník změn: výsledek nese change_id.

• Věta o důsledku, kterou člověk uvidí v potvrzení:

  Vrácení přepíše to, co je v obchodě teď. Když od té změny někdo položku upravil, nástroj to raději odmítne.

shopzi_undo_change: parametry

• changeId (text; povinný): change_id ze shopzi_list_changes nebo z odpovědi zápisového nástroje.