nks-osticket-mcp

Helpdesk na osTicketu se po čase plní tikety, které se opakují: stejný dotaz, stejná odpověď, stejné přeřazení do jiného stavu. nks-osticket-mcp dovolí tuhle práci svěřit AI asistentovi. Je to MCP server, přes který Claude nebo jiný agent s podporou protokolu MCP vypíše a prohledá tikety, přečte celé vlákno, odpoví zákazníkovi e-mailem, přidá interní poznámku, změní stav, propojí související tikety a stáhne nebo přiloží soubor.

Proč osTicket potřeboval vlastní API

Vestavěné API osTicketu je dělané na příjem tiketů z jiných systémů: klíč v základní instalaci umí jen zakládat tikety a spouštět cron. Číst je, odpovídat na ně nebo měnit jejich stav přes něj nejde. Proto server stojí na doplňku nks-osticket-plugin, který do osTicketu přidá jeden koncový bod JSON s celou sadou akcí nad tikety. MCP server je jeho překlad do řeči, které rozumí jazykový model: 14 nástrojů s popsanými parametry, které agent volá sám podle toho, co má zrovna udělat.

Co tím agent získá

Celý tiket i s historií

osticket_get_ticket vrátí tiket s kompletním vláknem zpráv. U každé položky vlákna jsou i přílohy s identifikátorem, názvem, typem a velikostí, takže agent ví, co zákazník poslal, a osticket_download_attachment mu soubor stáhne jako base64. Výpis jde filtrovat podle stavu a oddělení a stránkovat, hledání pracuje s předmětem tiketu.

Odpověď, která opravdu odejde

osticket_reply_ticket pošle zákazníkovi odpověď e-mailem, ne jen zápis do vlákna. Parametr replyTo určí, kdo ji dostane: všichni, jen zadavatel, nebo jen další účastníci. S staffId se odpověď i interní poznámka zapíšou jménem konkrétního agenta osTicketu, takže sedí podpis, jméno odesílatele i automatické přidělení tiketu. Zákazník tak dostane odpověď se stejným jménem a podpisem jako od kohokoli z týmu.

Přílohy z disku

Od verze 1.2.0 jde k odpovědi přiložit soubory. Agent předá cestu, server soubor načte z vlastního disku, typ MIME odhadne podle přípony (jpg, png, gif, webp, pdf, txt, jinak obecný binární typ) a pošle ho zakódovaný. Když soubor neexistuje, odpověď se neodešle a agent dostane chybu čtení. Velikost každého souboru omezuje nastavení osTicketu.

Pořádek v souvisejících tiketech

Čtyři nástroje pracují s nadřazenými a podřízenými tikety: propojení, zrušení vazby, výpis podřízených a dohledání nadřazeného. Agent tak může deset hlášení stejné poruchy pověsit pod jeden hlavní tiket. Statistiky vrátí počty všech, otevřených, uzavřených a zpožděných tiketů.

Srozumitelné selhání

Požadavek, na který osTicket neodpoví do 30 sekund, skončí kódem 504, výpadek sítě kódem 502 a chyby API se vrátí s kódem a zprávou z osTicketu. Agent tak pozná, jestli má zkusit znovu, nebo jestli chybí oprávnění. Pro testovací instalace s certifikátem podepsaným sám sebou jde kontrolu TLS vypnout.

Jak se zapojí

{
  "mcpServers": {
    "osticket": {
      "command": "node",
      "args": ["/absolute/path/to/nks-osticket-mcp/dist/index.js"],
      "env": {
        "NKS_OSTICKET_URL": "https://support.example.com/api/nks-osticket.php",
        "NKS_OSTICKET_API_KEY": "your-api-key"
      }
    }
  }
}

Server běží jako proces klienta přes standardní vstup a výstup a nastavuje se jen proměnnými prostředí: adresa koncového bodu doplňku, API klíč osTicketu, volitelně lhůta v milisekundách a kontrola certifikátu. API klíč se zakládá v administraci osTicketu, je vázaný na IP adresu, ze které server běží, a nese jen oprávnění, která mu správce dá. Agent s klíčem bez práva mazat tedy tiket nesmaže, ani když ho o to někdo požádá.

Kde se hodí

• Třídění ranní fronty: agent projde nové tikety, opakované dotazy zodpoví a zbytek opatří interní poznámkou se shrnutím pro člověka.
• Odpověď s podkladem: agent připraví návod nebo snímek obrazovky a pošle ho zákazníkovi jako přílohu přímo ve vlákně.
• Výpadek služby: hlášení od různých zákazníků se propojí pod jeden hlavní tiket a po opravě se zodpoví najednou.
• Přehled pro vedení: počty otevřených a zpožděných tiketů bez exportu z administrace.

Stav projektu

Verze 1.0.0 vyšla 5. července 2026 se 14 nástroji, 1.1.0 o dva dny později doplnila popis příloh ve vlákně. Poslední vydání 1.2.0 z 28. října 2026 přidalo přílohy k odpovědím, výběr agenta a adresátů. Přílohy potřebují doplněk ve verzi 1.3.0 nebo novější. Automatické testy projekt zatím nemá, kontrolou je typová kontrola a sestavení.

Jak začít

git clone https://github.com/nks-hub/nks-osticket-mcp.git
cd nks-osticket-mcp
npm install
npm run build

Potřeba je Node.js 18 nebo novější, osTicket s nainstalovaným doplňkem nks-osticket-plugin a API klíč s potřebnými oprávněními. Balíček v npm není, server se sestaví z repozitáře a v konfiguraci klienta se uvede cesta k dist/index.js. Vydání v Releases obsahují jen popis změn, hotové sestavení v nich není.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/nks-osticket-mcp pod licencí MIT, napsaný v TypeScriptu 5 nad oficiálním MCP SDK. Změny po verzích popisuje CHANGELOG.md.