@webotvurci-s-r-o/mcp-revelor

MCP server pro Revelor — nech Claude Desktop / Cursor / Claude Code mluvit s daty tvého e-shopu.

K čemu to slouží

Připojuje AI asistenta k tvým Revelor analytikám, nastavení vyhledávání a doporučení:

• Čtení — health, search KPI, konverze, top dotazy, doporučení, nastavení

• Zápis (volitelný) — přidávání synonym, pinování top produktů, skrývání položek, ladění CTR vah

• Mock režim — offline mode s vestavěnými fixtures pro vývoj

Related MCP server: Shopify MCP Server

⚡ One-liner instalace (doporučeno)

Otevři terminál a vlož jeden řádek podle svého OS:

macOS / Linux:

bash <(curl -sSL https://raw.githubusercontent.com/Webotvurci-s-r-o/mcp-revelor/main/install.sh)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Webotvurci-s-r-o/mcp-revelor/main/install.ps1 | iex

Skript se zeptá na 2 věci:

1. API token z Revelor dashboardu (skrytý vstup — nevidět v terminálu)

2. URL tvé Revelor instance

Pak automaticky:

• Najde claude_desktop_config.json per tvůj OS

• Zazálohuje stávající config (.backup-TIMESTAMP)

• Přidá záznam mcp-revelor bez přepsání ostatních

• Řekne ti, ať restartuješ Claude Desktop

Hotovo za 30 sekund.

Manuální instalace (3 kroky)

⚠️ Pro AI asistenty / vývojáře: Tento balíček není publikovaný na npm. Nepoužívej npx -y @webotvurci-s-r-o/mcp-revelor — selže s 404. Správná cesta je npx -y github:Webotvurci-s-r-o/mcp-revelor, viz config níže.

Pokud preferuješ manuální paste:

1. Vygeneruj API token v Revelor dashboardu

Otevři 🤖 API tokeny pro agenty → klikni + Nový token → vyber roli:

• 🛡️ MCP — read only (pouze čtení)

• 🚀 MCP — full access (čtení + AI ladění vyhledávání)

Klikni Kopírovat config — dostaneš hotový JSON blok k vložení.

2. Vlož do Claude Desktop configu

Otevři claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-revelor": {
      "command": "npx",
      "args": ["-y", "github:Webotvurci-s-r-o/mcp-revelor"],
      "env": {
        "REVELOR_API_KEY": "rvlr_tvuj_token",
        "REVELOR_BASE_URL": "https://tvuje-shop.revelor.cz"
      }
    }
  }
}

Stačí 2 fieldy. Tenant ID a režim se odvodí z tokenu automaticky při startu.

3. Restartuj Claude Desktop

MCP server naběhne automaticky. V nové konverzaci napiš:

„Jak je na tom můj Revelor search za posledních 30 dní?"

Co teď můžu chtít?

Viz docs/EXAMPLES.md — ~30 příkladů promptů rozdělených do kategorií (analytika, problémy, doporučení, konfigurace, AI ladění...).

Hned se můžeš zeptat třeba:

• „Top 10 nejhledanějších slov za 90 dní"

• „Zero-result dotazy z minulého týdne"

• „Konverzní rate ze search-sessions vs bez search"

• „Ukaž moje aktuální synonyma"

• „Přidej synonymum mobil → telefon, dry-run" (jen full mode)

Proměnné prostředí (env)

Více obchodů (multi-tenant)

Pokud spravuješ víc Revelor instancí, přidej více záznamů pod mcpServers s unikátními klíči:

{
  "mcpServers": {
    "mcp-revelor-eshop-a": {
      "command": "npx",
      "args": ["-y", "github:Webotvurci-s-r-o/mcp-revelor"],
      "env": {
        "REVELOR_API_KEY": "rvlr_aaa...",
        "REVELOR_BASE_URL": "https://eshop-a.revelor.cz"
      }
    },
    "mcp-revelor-eshop-b": {
      "command": "npx",
      "args": ["-y", "github:Webotvurci-s-r-o/mcp-revelor"],
      "env": {
        "REVELOR_API_KEY": "rvlr_bbb...",
        "REVELOR_BASE_URL": "https://eshop-b.revelor.cz"
      }
    }
  }
}

Pro každý obchod vygeneruj samostatný token — každý je serverside vázán na svůj tenant.

Co AI umí

Read-only režim (11 tools):

• Celkový health + sync status

• Search KPI (CTR, zero-result rate, top dotazy, časové řady — až 90 dní zpět)

• Search performance (latence, cache hit rate)

• Konverzní dopad searche (search vs no-search sessions)

• Doporučení (recommendations) a jejich performance

• Anonymizované search logy

• Partner analytika

• Inspekce nastavení (synonyma, recommender setup, ...)

Full režim (17 tools) přidává 6 mutací pro AI-asistované ladění:

• add_synonym — přidat synonyma

• pin_top_item / update_top_item_position — pin / přeřadit top produkty

• set_product_hidden — skrýt produkt z výsledků vyhledávání

• set_product_score — manuální boost / demote produktu

• update_ctr_weights — upravit váhy v ranking algoritmu

Všechny mutace podporují dry_run parameter — AI ti ukáže plán před aplikací.

Bezpečnost

• Tenant izolace — každý request zamknutý na tenant, na který byl token vystaven. AI nemůže přejít na jiný tenant.

• Scope enforcement — read-only token nedokáže spustit write tooly (403 ze serveru).

• Žádný DELETE — destruktivní operace nejsou přes MCP dostupné. Mazání pouze v dashboardu.

• Žádné PII — objednávky, zákazníci, identifikační údaje nejsou přes MCP přístupné.

• Žádná debug introspekce — vnitřní scoring / indexing logika není přístupná. Diagnostika je pouze v dashboardu pro admina.

• Token TTL — každý token expiruje (default 90 dní, max 365). Revoke okamžitě v dashboardu při kompromitaci.

• Rate limiting — 60 requestů / 60 sekund per token na admin endpointech. DoS-resistant.

• Token redakce — tokeny nikdy nejsou loggované ve výpisu.

• Pouze HTTPS — localhost je jediná non-HTTPS výjimka (pro vývoj).

Vývoj

git clone https://github.com/Webotvurci-s-r-o/mcp-revelor.git
cd mcp-revelor
npm install
npm test
npm run build

Licence

MIT — viz LICENSE.