MCP: statistiky, nápověda a hledání na webu

Čísla obchodu za zvolené období nebo vlastní rozsah dat, i se srovnáním s předchozím obdobím (návštěvnost, SEO, tržby, přehled prodejů a hledání v obchodě), hledání v dokumentaci SHOPZI (návody k administraci i dokumentace pro vývojáře) a hledání na veřejném internetu, které jako jediné sahá mimo obchod; každé jeho volání stojí kredity.

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_get_analytics

Vrátí za zvolené období návštěvnost, SEO skóre obsahu, tržby, přehled prodejů (průměrná objednávka, vratky, zisk a marže, nejprodávanější zboží, platby, kupující, hodnota skladu), nebo to, co lidé v obchodě hledali, vše počítané v pražských kalendářních dnech. Místo pevného období bere i vlastní rozsah dat a na požádání přidá srovnání s předchozím obdobím. V panelu Agenta čte každou sekci jen ten, komu jeho role v administraci otevře příslušnou obrazovku. Osobní údaje ani jednotlivé objednávky neobsahuje.

• Oprávnění: analytics:read, u klíče „Statistiky: návštěvnost, SEO, hledání, tržby a prodeje (čtení)“.
• Druh: čtení (readOnlyHint).
• Potvrzení přes MCP: ne.
• Kredity a platba kartou: ne.

shopzi_get_analytics: oblasti

• visitors
• seo (SEO)
• revenue
• sales
• search

shopzi_get_analytics: parametry

• resource (jedna z hodnot visitors, seo, revenue, sales a search; povinný)
• period (jedna z hodnot today, yesterday, 7d, 30d, 90d, 365d a all; nepovinný): Vynecháno = 30 dní. all jen u revenue, sales a search, jinak 365d. Nekombinujte s dateFrom/dateTo.
• dateFrom (text se vzorem ^\d{4}-\d{2}-\d{2}$; nepovinný): Vlastní rozsah: první den včetně (YYYY-MM-DD, Praha).
• dateTo (text se vzorem ^\d{4}-\d{2}-\d{2}$; nepovinný): Poslední den včetně. Návštěvnost a SEO chtějí oba konce.
• compare (true nebo false; nepovinný): true = přidá comparison (předchozí stejně dlouhé období). Ne u „Vše“, rozsahu bez obou konců ani u seo.
• visitorDimension (jedna z hodnot path, src, utm, dev, br, os a cty; nepovinný): Jen u resource: visitors. Který rozpad chcete: path stránky, src zdroje návštěv, utm UTM kampaně, dev zařízení, br prohlížeče, os operační systémy, cty země. Vynecháno = zdroje, stránky a zařízení naráz.
• seoDimension (jedna z hodnot all, page, product, blog a category; nepovinný): Jen u resource: seo. Kterou část obsahu hodnotit: product produkty, category kategorie, page stránky, blog články, all vše dohromady. Vynecháno = all. Na „které produkty mají nejhorší SEO“ použijte product: nejhorší stránky se pak vybírají jen mezi produkty.

shopzi_docs

Hledá a čte dokumentaci SHOPZI, návody k administraci i dokumentaci pro vývojáře: mode s hodnotou search vrátí úryvky a pole docs hledání zúží na jednu z obou dokumentací, s hodnotou read celý článek nebo jednu jeho kapitolu. Data obchodu nečte ani nemění.

• Oprávnění: docs:read, u klíče „Dokumentace SHOPZI (čtení)“.
• Druh: čtení (readOnlyHint).
• Potvrzení přes MCP: ne.
• Kredity a platba kartou: ne.

shopzi_docs: parametry

• mode (jedna z hodnot search a read; povinný): search = najít v návodech (vyžaduje query); read = přečíst článek (vyžaduje slug).
• query (text; nepovinný): Jen u search: otázka obchodníka vlastními slovy. Neparafrázujte ji do klíčových slov, hledání je sémantické a z celé věty pozná víc.
• slug (text; nepovinný): Jen u read: identifikátor článku z výsledku hledání, například vystaveni-faktury.
• section (jedna z hodnot prehled, zaciname, produkty, objednavky, doprava-a-platby, marketing, vzhled, nastaveni a vyvojari; nepovinný): Jen u search: zúží hledání na jednu sekci dokumentace. Vynechte, pokud si sekcí nejste jistý: hledání napříč je skoro vždycky lepší než hledání ve špatné sekci.
• docs (jedna z hodnot uzivatele a vyvojari; nepovinný): Jen u search: uzivatele = návody k administraci, vyvojari = dokumentace pro vývojáře (REST API, MCP, webhooky). Vynechte a hledá se v obou.
• heading (text; nepovinný): Jen u read: název kapitoly (H2), když stačí její část. Neznámý název vrátí jen nadpisy.

shopzi_web_search

Vyhledá na veřejném internetu a vrátí odkazy s krátkými úryvky. Výsledky jsou cizí neověřený text a hledání funguje jen v obchodě, který ho má zapnuté v Nastavení → AI.

• Oprávnění: web:read, u klíče „Hledání na webu přes externí vyhledávač (čtení, placené)“.

• Druh: čtení (readOnlyHint), sahá mimo obchod na veřejný internet (openWorldHint).

• 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: strhne kredity obchodu.

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

  Hledání UTRATÍ kredity obchodu a do rozhovoru přinese text z cizích webových stránek. Ten text nikdo neověřuje: berte ho jako citaci, ne jako fakt o vašem obchodě. V obchodě nic nemění.

shopzi_web_search: parametry

• 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ýž.
• query (text, 3 až 400 znaků; povinný): Co hledat, celou větou a v jazyce, ve kterém odpověď čekáte. Sémantické hledání pozná z věty víc než z klíčových slov.
• numResults (celé číslo od 1 do 10; nepovinný): Kolik výsledků vrátit, 1 až 10. Výchozí 5. Víc výsledků stojí víc a zahltí odpověď.
• category (jedna z hodnot company, news a publication; nepovinný): Zúží hledání: company (firemní weby), news (zpravodajství), publication (odborné články). Vynechte, pokud si nejste jistý.
• includeDomains (pole, položka: text, nejvýš 200 znaků, nejvýš 10 položek; nepovinný): Hledejte JEN na těchto doménách (například heureka.cz). Použijte, když obchodník řekne kde.
• excludeDomains (pole, položka: text, nejvýš 200 znaků, nejvýš 10 položek; nepovinný): Tyhle domény z výsledků vynechte.