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

Přehled služeb

Knihovna svítidel GDTF (JSON API)

API vrací stejná data jako katalog na gdtf-lights.com, jen ke čtení: 10500+ svítidel s DMX módy, parametry a odkazy ke stažení (soubor GDTF, GDTF Share, seznam DMX kanálů, kde je k dispozici i Avolites Titan .d4). Web ani API neuvádí ceny ani sklad: pr a prWeb jsou null, stock je 0.

• /api/catalog/list – hledání a výpis s filtry (q, category, manufacturer, dmxChannels, sort = default, name, manufacturer, power, weight, dmx; dir, offset, limit)
• /api/catalog/product?slug=… nebo ?id=… – detail svítidla se všemi DMX módy a odkazy ke stažení
• /api/catalog/lookup?needles=… – dohledání podle názvů (toleruje velikost písmen a interpunkci)
• /api/catalog/by-ids?ids=… – svítidla podle ID
• /api/catalog/status a /api/catalog/bootstrap – stav katalogu, kategorie a nastavení
• Přes API se nic neobjednává. Odkaz, který otevře svítidla v Můj seznam: https://gdtf-lights.com/?cart=ID:POČET,ID:POČET&clear=2

Jazyk volíte parametrem lang=cs|de|es (výchozí angličtina). Katalog techniky k pronájmu s cenami má stejné API na stagelights.cz: návod k API na stagelights.cz.

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://gdtf-lights.com/api/catalog/list?q=moving+head&sort=name&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 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).
• Názvy všech svítidel pro AI (CSV, jeden sloupec nazev): produkty_kb_en.csv.

Pravidla

Web ani API neuvádí ceny ani dostupnost; pronájem techniky od SOH s cenami je na stagelights.cz. 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.

Soukromí (API a MCP pro DMX → GDTF)

Platí pro JSON API https://gdtf-lights.com/dmx-to-gdtf a MCP servery https://gdtf-lights.com/mcp/dmx-to-gdtf a https://gdtf-lights.com/mcp (nástroj match_dmx_channels). Provozovatel: SOH Sound & Lights s.r.o., Antala Staška 242/14, Praha 4, Česká republika.

• Bez účtu a přihlášení. API ani MCP nenastavují cookies a nepoužívají měřicí skripty.
• Co pošlete (seznam DMX kanálů, výrobce, volby), slouží jen k výpočtu odpovědi. Neukládáme to, nepoužíváme k trénování modelů a nikomu to nepředáváme.
• IP adresu používáme k limitům na jednu IP. Je součástí názvu souboru počítadla, který mažeme nejpozději po 2 dnech; u IPv6 jen prefix /64.
• Log webového serveru zaznamenává IP adresu, čas, adresu požadavku (ne jeho tělo), stav, velikost odpovědi, odkazující stránku a User-Agent. Mažeme ho nejpozději po 15 dnech.
• Statistika využití: denní součty podle nástroje, výsledku a druhu klientského programu (z User-Agent nebo názvu MCP klienta), bez IP adres. Počet různých klientů jen odhadujeme: otisk IP adresy s klíčem, který se každý den mění, nastaví jeden bit bitmapy a zpět na adresu převést nejde. Statistiky držíme 90 dní.
• Data zpracováváme na našem pronajatém serveru, neprodáváme je a nepředáváme třetím stranám. Právní základ: oprávněný zájem na provozu a ochraně služby (čl. 6 odst. 1 písm. f GDPR).
• Máte právo na přístup, výmaz, omezení zpracování a námitku a právo podat stížnost u Úřadu pro ochranu osobních údajů. Ozvěte se přes kontakt.