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

> Nástroje MCP, které odpovídají na otázky a v obchodě nic nemění: statistiky obchodu, hledání v dokumentaci SHOPZI a placené hledání na veřejném internetu.

- Sekce: Pro vývojáře
- Stránka: https://shopzi.cz/dokumentace/vyvojari/mcp-statistiky-a-napoveda
- Ověřeno: 2026-09-16

---

Čí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](/dokumentace/vyvojari/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` [#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 [#shopzi-get-analytics-oblasti]

* `visitors`
* `seo` (SEO)
* `revenue`
* `sales`
* `search`

## `shopzi_get_analytics`: parametry [#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` [#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 [#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` [#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 [#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.