MCP server pro audioknihy.cz

Co je MCP server?

MCP (Model Context Protocol) je otevřený protokol od Anthropicu, přes který si AI aplikace povídají s ostatními systémy. Představte si ho jako univerzální kabel: jeden katalog — jedno API — a najednou ho umí používat Claude Desktop, ChatGPT, Cursor, Perplexity i vlastní agenti, aniž bychom pro každého psali zvlášť integraci.

Server v MCP terminologii vystavuje sadu nástrojů (tools) — pojmenovaných operací s definovaným vstupem a výstupem. Když AI host (například Claude) potřebuje konkrétní data, sám pozná, který nástroj zavolat, předá mu parametry a výsledek vloží do odpovědi uživateli. Vše přes standardní JSON-RPC 2.0 nad HTTP.

Pro nás znamená MCP konec čtení skrz HTML scraping. Místo toho, aby AI nástroj musel rozumět tomu, jak vykreslujeme tabulku cen na webu, zavolá si přímo compare_all_offers a dostane čistá strukturovaná data — ceny, odkazy, partnery, časová razítka.

Co s tím můžete dělat

Po napojení audioknihy.cz MCP serveru do svého AI klienta můžete psát úplně přirozeně:

• „Najdi audioknihu Hobit a porovnej ceny napříč obchody."

  AI volá search_audiobooks → compare_all_offers, výsledek vrátí jako tabulku.

• „Co dabuje Václav Knop? Top 10."

  AI volá get_narrator a vrátí profil + works array.

• „Detektivky v češtině pod 200 Kč."

  AI volá search_by_filters s genre + price_max.

• „Doporuč mi tři audioknihy z fantasy a kde je nejlevněji koupit."

  AI kombinuje search_by_filters + find_cheapest_offer per title.

Reálná hodnota: AI agent přestane být jen chatbot „obecného vědění" a stává se konkrétním asistentem pro váš český audioknižní nákup — s aktuálními cenami a transparentními affiliate odkazy.

Proč jsme to postavili

AI nástroje jsou už teď způsob, jakým hodně lidí hledá knižní tipy a srovnává ceny — místo toho, aby procházeli desítku e-shopů. Když AI nemá strukturovaný přístup k českému audioknižnímu trhu, buď vrátí zastaralé informace ze svého trénovacího datasetu, nebo scrapuje stránky obchodů a často přehlíží předplatitelské služby jako Radiotéku.

MCP nám umožňuje být v té smyčce přímo. Když Claude nebo ChatGPT doporučí audioknihu, vidí naše aktuální data, naše porovnání cen, naše affiliate odkazy. Pro uživatele to znamená lepší doporučení; pro nás stabilní zdroj návštěvnosti, který nezávisí na tom, jak se zrovna chová Google Search.

A je to první podobný server pro český audioknižní trh. Chceme, aby se „audioknihy.cz" stalo synonymem pro „spolehlivý zdroj v AI asistentech", podobně jako se „Fakturoid" stal synonymem pro fakturaci v AI workflow pro účetní.

Endpoint + technické parametry

POST https://audioknihy.cz/api/mcp

Verze

0.2.0 (od 2026-05-10)

Transport

Streamable HTTP, JSON-RPC 2.0, stateless

Autentizace

Anonymní (read-only katalog)

Rate limit

60 req/min/IP (anonymous tier)

Timeout

5 s na požadavek

Nástrojů

9 read-only

9 nástrojů, které server nabízí

Každý nástroj má kompletní JSON-Schema specifikaci v Agent Skills indexu.

• search_audiobookssearch

  Full-text + fuzzy search across 12 367 Czech audiobooks (title, author, narrator). Use when an agent needs to resolve a free-form query into one or more audiobook records.

• get_audiobookdetail

  Full audiobook detail by author + work slug — title, description, cover, runtime, ISBN, genres, narrator, publisher, and the full table of active offers across retail partners.

• find_cheapest_offercompare

  Lowest-price active offer for an audiobook across all affiliate partners. USP — only Czech site that compares audiobook prices across all major retail partners.

• compare_all_offerscompare

  Full price comparison table across every active retail partner for one audiobook. Returns price + format + last-seen timestamp per partner — agents can rank or filter.

• browse_genresbrowse

  List all 35 Czech audiobook genres with audiobook counts. Discovery entry point — agents enumerate genres before drilling into a specific one.

• search_by_filtersfilter

  Multi-facet search of audiobooks: combine genre, narrator, max price, year range. Use when an agent has structured constraints rather than a free-form query. V1 supports genre + narrator + price_max + year filters; partner filter coming in V2.

• get_authordetail

  Author profile + their audiobook works. Returns biography, photo, country, and the full list of audiobook editions where this person is credited as author / co-author / editor.

• get_narratordetail

  Narrator profile + audiobooks they have read. Czech audiobook listeners often choose by narrator (performance quality often matters more than the underlying text).

• list_partnersdisclosure

  List active retail partners with audiobook counts. Required for transparency / disclosure when an agent needs to explain HOW audioknihy.cz monetises recommendations (we are an affiliate aggregator, not a retailer).

Jak si MCP server zprovoznit ve vašem AI nástroji

Většina klientů potřebuje jen URL https://audioknihy.cz/api/mcp a žádné credentials. Konkrétní postup pro všechny rozšířené klienty v ČR:

{
  "mcpServers": {
    "audioknihy": {
      "type": "http",
      "url": "https://audioknihy.cz/api/mcp"
    }
  }
}

claude mcp add audioknihy --transport http --url https://audioknihy.cz/api/mcp

{
  "mcpServers": {
    "audioknihy": {
      "type": "http",
      "url": "https://audioknihy.cz/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "audioknihy": {
      "url": "https://audioknihy.cz/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "audioknihy": {
      "httpUrl": "https://audioknihy.cz/api/mcp"
    }
  }
}

{
  "mcpServers": {
    "audioknihy": {
      "url": "https://audioknihy.cz/api/mcp"
    }
  }
}

Příklad volání přes curl (sanity check)

curl -X POST https://audioknihy.cz/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_audiobooks",
      "arguments": { "query": "Hobit", "limit": 5 }
    },
    "id": 1
  }'

Discovery metadata pro automatické skenery

• /.well-known/mcp/server-card.json — Server Card (SEP-2127): server info + capabilities + tool list
• /.well-known/mcp.json — kanonický alias téhož
• /.well-known/agent-skills/index.json — Agent Skills (Cloudflare RFC v0.2.0): per-skill markdown specifikace
• /.well-known/api-catalog — API Catalog (RFC 9727)
• /llms.txt + /llms-full.txt — narativní AI manifesty

Často kladené otázky

Co je MCP server?

MCP (Model Context Protocol) je otevřený protokol od Anthropicu, kterým AI aplikace mluví s externími systémy. Funguje jako univerzální kabel: jeden a tentýž audioknižní katalog tak zpřístupníme Claudu, ChatGPT, Cursoru i Perplexity současně, aniž bychom pro každého psali zvlášť integraci.

Co s tím můžu jako uživatel dělat?

Po napojení MCP serveru můžete v AI chatu psát přirozeně: „Najdi audioknihu Hobit a porovnej ceny", „Co dabuje Václav Knop?" nebo „Detektivky pod 200 Kč v češtině". AI vyhledá přímo v našem katalogu a vrátí strukturovanou odpověď s odkazy na jednotlivé obchody.

Potřebuju API klíč?

Ne. Anonymous tier je veřejný a zdarma — pouze rate-limit 60 požadavků za minutu na IP adresu. Pokud potřebujete vyšší limity (B2B, partnerský přístup), napište nám na /kontakt.

Funguje to i bez instalace? Jen v prohlížeči?

Ano — implementovali jsme i WebMCP. Když navštívíte audioknihy.cz v prohlížeči, který WebMCP podporuje (Chrome 146+ Canary, brzy stable), AI asistent v browseru získá přístup ke stejným nástrojům automaticky, bez konfigurace.

Co se stane, když AI doporučí audioknihu? Dostanete provizi?

Ano, jsme affiliate srovnávač — platí to stejné jako pro běžné návštěvy přes web. Nástroj list_partners (a každá odpověď s odkazem na obchod) vrací URL ve formátu /go/<partner>, abyste mohli AI agenta naučit transparentně sdělit, že nákup po kliknutí přináší audioknihy.cz provizi. Cena pro koncového zákazníka je vždy shodná s nákupem napřímo.