Алатке MCP сервера
Zammad одговара на Model Context Protocol (MCP) на сопственом серверу, поред REST API интерфејса. AI клијент, на пример апликација за ћаскање или алатка за програмирање, преко њега чита, проналази, мења и креира тикете. Сервер је део сваке инсталације, ништа не мора додатно да се инсталира нити покреће.
Ова страница описује алатке које сервер нуди и ограничења која за њих важе. Како корисник повезује AI клијент описано је у водичу за MCP сервер. Да ли сервер уопште одговара, одлучује администратор, који га укључује у API подешавањима Zammad-а.
Приступ
Сервер одговара на https://{fqdn}/mcp преко MCP транспорта Streamable HTTP, и то само на POST захтеве. AI клијент мора уз сваки захтев да шаље фиксно заглавље Authorization: Bearer {your_token}. Сама подршка за транспорт није довољна, AI клијент који не може да постави заглавље остаје без приступа.
Захтеви стижу до сервера само на адресама из подешавања Квалификовани назив домена и Алтернативни квалификовани назив домена или на повратној адреси (localhost, 127.0.0.1, ::1). Захтеви на другој адреси се одбијају, као и захтеви прегледача са другог порекла, што штити сервер од DNS rebinding напада.
Прекидач MCP сервер је подразумевано искључен. Док је искључен, сервер одбија сваки захтев, без обзира на то који кључ захтев носи. AI клијенти се аутентификују искључиво личним приступним кључевима: не пролазе ни лозинка ни OAuth2 кључ, као ни захтев који делује у име другог корисника. И кључ и његов власник задржавају своја ограничења, тако да AI клијент може да ради тачно оно што они смеју и ништа више. Свака алатка захтева дозволу ticket.agent, а корисник без дозвола оператера, на пример клијент, не добија никакве алатке.
Алатке
AI клијент добија следеће алатке, редоследом који сам одређује. Колона приступа наводи шта алатка ради са подацима: читање не мења ништа, измена мења тикет.
| Алатка | Приступ | Шта ради |
|---|---|---|
add_internal_note | измена | Додаје интерну напомену тикету. Клијент је никада не види. |
create_article | измена | Додаје чланак тикету или шаље одговор клијенту. |
create_ticket | измена | Креира тикет са првом поруком из телефонског позива или имејла, или као интерну напомену. |
get_current_user | читање | Чита корисника у чије име веза ради, са његовим групама и приступом бази знања. |
get_knowledge_base_answer | читање | Чита један чланак базе знања у целости, на траженом језику. |
get_organization | читање | Чита организацију са њеним доменом, VIP статусом, напоменом, прилагођеним пољима и члановима. |
get_overview_tickets | читање | Чита тикете једног прегледа, као што је „Моји додељени тикети”. |
get_shared_draft | читање | Чита заједнички нацрт сачуван за тикет. |
get_ticket | читање | Чита тикет са његовим клијентом, организацијом, власником, везама и порукама. |
get_ticket_articles | читање | Чита поруке тикета: индекс, претрагу у њима или изабране поруке са њиховим текстом. |
get_ticket_fields | читање | Наводи поља која тикет има, са вредностима које се могу изабрати. |
get_ticket_history | читање | Чита шта се променило на тикету, када и ко или која аутоматизација је то променила. |
get_user | читање | Чита корисника са имејлом, телефоном, мобилним телефоном, организацијама и прилагођеним пољима. |
link_knowledge_base_answer | измена | Повезује чланак базе знања са тикетом. |
link_tickets | измена | Повезује два тикета. |
list_overviews | читање | Наводи прегледе са бројем њихових тикета. |
list_tags | читање | Наводи постојеће ознаке, почевши од најчешће коришћених. |
read_attachment | читање | Чита текст датотеке приложене уз поруку тикета. Погледајте Ограничења за то које датотеке чита. |
save_shared_draft | измена | Чува одговор као заједнички нацрт тикета. Ништа се не шаље. |
search_knowledge_base | читање | Претражује базу знања по речима или по значењу. |
search_organizations | читање | Проналази организације по називу или домену. |
search_tickets | читање | Претражује тикете по упиту, по филтерима или на оба начина. |
search_users | читање | Проналази кориснике по имену, имејлу, корисничком имену или броју телефона. |
send_shared_draft | измена | Шаље заједнички нацрт тикета онакав какав је сачуван. |
set_ticket_tags | измена | Додаје ознаке тикету и уклања ознаке са њега. |
update_ticket | измена | Мења стање, приоритет, групу, власника, време на чекању или прилагођена поља тикета. |
Три алатке за базу знања, get_knowledge_base_answer, link_knowledge_base_answer и search_knowledge_base, појављују се само тамо где је база знања активна.
Ограничења
Алатка чита текст текстуалне датотеке: обичан текст, дневнике, CSV, JSON, XML или HTML, до 10 MB. Друге датотеке, као и веће од тога, не чита. Алатка тада наводи разлог и враћа линк за преузимање датотеке, тако да AI клијент може да проследи линк кориснику. Дугачак текст стиже у деловима, по један део по позиву.
Датотеке се не могу слати преко сервера. create_article и create_ticket примају само текст, а корисник који жели да пошаље датотеку додаје је поруци у самом Zammad-у.
Које поруке AI клијент шаље без додатног одобрења, и када Zammad од корисника тражи одобрење, описано је у администраторској документацији API подешавања.