API a MCP pro vývojáře a AI agenty

Přehled služeb

Katalog techniky k pronájmu (JSON API)

API vrací stejná data jako katalog na stagelights.cz, jen ke čtení. Cena prWeb je cena zobrazená na webu: 1 kus na 1–2 dny včetně DPH; za delší pronájem platí slevy podle ceníku. Dostupnost v termínu potvrzuje půjčovna.

• /api/catalog/list – hledání a výpis s filtry (q, category, manufacturer, sort = default, price, name, manufacturer, power, weight, dmx; dir, offset, limit)
• /api/catalog/product?slug=… nebo ?id=… – detail produktu
• /api/catalog/lookup?needles=… – dohledání podle názvů (toleruje velikost písmen a interpunkci)
• /api/catalog/by-ids?ids=LEDFLATPAR,JBLEON612 – produkty podle ID
• /api/catalog/status a /api/catalog/bootstrap – stav katalogu, kategorie a nastavení

Jazyk volíte parametrem lang=en|de|es (výchozí čeština). Stejné API pro knihovnu svítidel běží na gdtf-lights.com (výchozí angličtina, bez cen).

MCP server (Model Context Protocol)

Vzdálený MCP server pro AI asistenty a agenty běží na https://gdtf-lights.com/mcp (pro jiný jazyk katalogu ?lang=cs|de|es). Používá Streamable HTTP bez stavu a bez přihlášení: zprávy JSON-RPC 2.0 posílejte metodou POST, GET vrací 405. Připojíte ho v každém klientovi MCP, který podporuje vzdálený server přes HTTP.

Nástroje:

• search_fixtures, get_fixture, get_gdtf_download, list_categories – hledání svítidel, detail se všemi DMX módy a odkaz na soubor GDTF
• match_dmx_channels – najde svítidlo a jeho DMX mód podle seznamu kanálů
• prepare_mvr_export – zkontroluje svítidla, počty a módy a vrátí zadání pro generátor a odkaz na stránku MVR export
• generate_mvr a get_mvr_job – vytvoří soubor MVR a vrátí odkaz ke stažení (jediný nástroj, který něco vytváří)
• list_layouts, list_scene_templates, list_visualizers – rozmístění, šablony scén a profily programů

Generátor 3D scény MVR

Stejný soubor jako nástroj generate_mvr vytvoří veřejné API: POST na https://gdtf-lights.com/mvr-generate.php se zadáním (job) z prepare_mvr_export v těle (JSON). Soubory GDTF se berou z katalogu, vlastní lze přidat jako multipart pole gdtf[]. Odpověď obsahuje download_url, report_url a expires: soubor stáhněte do 2 hodin (scény nad 50 MB do 30 minut). Seznamy programů a rozmístění vrací GET, například ?action=visualizers. Pro lidi je tentýž generátor na stránce MVR export.

DMX → GDTF (Fixture Finder)

Hledání svítidla podle DMX kanálů má vlastní API (https://gdtf-lights.com/dmx-to-gdtf, POST s polem channels) a nástroj MCP match_dmx_channels; samostatný MCP server jen s tímto nástrojem běží na https://gdtf-lights.com/mcp/dmx-to-gdtf. Podrobnosti a příklady jsou u nástroje: gdtf-lights.com/dmx-to-gdtf#api.

Příklady

curl -s 'https://stagelights.cz/api/catalog/list?q=led+par&sort=price&dir=asc&limit=5'

curl -s https://gdtf-lights.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

curl -s 'https://gdtf-lights.com/mvr-generate.php?action=visualizers'

Limity a chyby

• Katalog API a MCP: 10 požadavků za sekundu z jedné IP adresy (krátce až 60).
• Generování MVR (API i generate_mvr dohromady): 2000 za den a 10 za minutu z jedné IP adresy.
• DMX → GDTF (API i match_dmx_channels): 20 000 za den a 300 za minutu z jedné IP adresy; pro všechny dohromady 500 za minutu, 10 000 za hodinu a nejvýš 3 hledání současně.
• Chyby jsou ve strojovém tvaru s polem code (např. rate_day, rate_minute, busy). Při 429 a 503 přijde i Retry-After; tak dlouho počkejte. Denní limity se nulují o půlnoci UTC.
• Využití se počítá souhrnně, bez IP adres.

Pro AI agenty na webu

• Pravidla a ceník pro AI: llms.txt a llms-full.txt; strojový popis API: openapi.json (OpenAPI 3.1, katalog API podle RFC 9727 na /.well-known/api-catalog).
• Markdown verze stránek: index.md, navod.md, akce.md (nebo hlavička Accept: text/markdown).
• Nástroje přímo v prohlížeči (WebMCP, návrh W3C) jako prototyp s parametrem ?webmcp=1: hledání techniky, košík, termín, cena, AI vizualizace a příprava poptávky. Odeslání poptávky i generování obrázku vždy potvrzuje návštěvník.

Pravidla

Poptávka odeslaná přes web nebo AI chat není potvrzená rezervace; dostupnost a cenu potvrzuje půjčovna. AI vizualizace (obrázky a videa) se generují jen na webu se souhlasem návštěvníka, API je nenabízí. S dotazy k napojení se ozvěte přes kontakt.