@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

⚡ 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:

OS	Cesta
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/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)

Proměnná	Povinné	Popis
REVELOR_API_KEY	ano	Bearer token (rvlr_*) z dashboardu
REVELOR_BASE_URL	ano	HTTPS URL tvé Revelor instance
REVELOR_TENANT_ID	ne	Auto-derived z tokenu. Nastavit jen pokud chceš override.
REVELOR_MCP_MODE	ne	auto (default) | readonly | full | mock
REVELOR_HTTP_TIMEOUT_MS	ne	Timeout requestu (default 30 000 ms)
REVELOR_CACHE_TTL_MS	ne	TTL in-memory cache (default 30 000 ms)

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.