Narzędzia i zasoby

Przegląd

Serwer MCP Zabbix udostępnia funkcje Zabbix klientom MCP jako narzędzia i zasoby.

Nazwy narzędzi opisują ich działanie. Jeśli ustawiono parametr ToolPrefix, prefiks jest dodawany do każdej nazwy narzędzia; reguły dostępu do narzędzi odnoszą się do zwykłych nazw wymienionych poniżej.

Narzędzia odczytu

Narzędzie Metoda Zabbix API Argumenty Sortowanie według Zasób
hostgroup_get hostgroup.get groupids, names, search, limit name zabbix://hostgroup/<id>
templategroup_get templategroup.get groupids, names, search, limit name zabbix://templategroup/<id>
host_get host.get hostids, groupids, search, limit name zabbix://host/<id>
template_get template.get templateids, groupids, search, limit name zabbix://template/<id>
item_get item.get hostids, itemids, search, limit name zabbix://item/<id>
lld_get discoveryrule.get hostids, ruleids, limit name -
interface_get hostinterface.get hostids, interfaceids, limit interface ID -
macro_get usermacro.get hostids lub global, macro_names, limit macro -
problem_get problem.get eventids, groupids, hostids, severities, acknowledged, suppressed, recent, limit event ID, malejąco -
maintenance_get maintenance.get maintenanceids, groupids, hostids, limit name -
history_get history.get itemids, time_from, time_till, type, limit clock, malejąco -
trigger_get trigger.get triggerids, hostids, search, limit description zabbix://trigger/<id>

Należy pamiętać, że:

  • host_get i template_get zwracają również wyzwalacze każdego obiektu (ograniczony zestaw pól), tagi i połączone szablony. Pozycje, reguły wykrywania, interfejsy i makra są zwracane przez odpowiednie narzędzia.
  • history_get wymaga zakresu czasu nie szerszego niż 7 dni, rozpoczynającego się nie wcześniej niż 7 dni temu. Argument type musi mieć jedną z wartości float, unsigned, character, text, log lub json i musi odpowiadać typowi wartości pozycji; jeśli typ jest nieprawidłowy, zwracany jest pusty wynik, którego nie można odróżnić od pozycji bez danych. Historii pozycji binarnych (typ wartości 5) nie można pobrać za pośrednictwem serwera MCP.
  • Narzędzia odczytu żądają stałej listy pól; nigdy nie są żądane wszystkie pola (output: extend).
  • Wyniki narzędzi zawierających zasób mają pole uri, dzięki czemu agent może przejść od listy do pojedynczej encji.

Format odpowiedzi

Wszystkie narzędzia odczytu zwracają odpowiedź w tym samym formacie:

{
  "results": [ ... ],
  "count": 2,
  "truncated": true,
  "truncated_by": "count",
  "limit": 2,
  "note": "Osiągnięto limit liczby wyników ..."
}

Odpowiedź jest ograniczana przez argument limit (domyślnie: 100, maksymalnie: 1000) oraz przez serializowany rozmiar odpowiedzi (MaxResponseSize, domyślnie: 64K). Odpowiedź zostaje zatrzymana po osiągnięciu któregokolwiek z limitów. Odpowiedź jest skracana wyłącznie między wynikami, nigdy wewnątrz wyniku, a skrócona odpowiedź wskazuje, który limit został osiągnięty. Każde narzędzie ma stałą kolejność sortowania, dlatego skrócona odpowiedź zawsze zawiera początek pełnego zestawu wyników. Stronicowanie nie jest obsługiwane; aby uzyskać inne wyniki, zawęź zapytanie.

Narzędzia problemów

Wszystkie narzędzia problemów wywołują metodę event.acknowledge z odpowiednimi flagami akcji. Argument eventids jest wymagany; identyfikatory zdarzeń można pobrać za pomocą problem_get. Za pomocą dowolnego narzędzia problemów można dodać wiadomość (komentarz). Argument message jest opcjonalny, z wyjątkiem problem_annotate, dla którego jest wymagany; jeśli zostanie określony, wiadomość zostanie zarejestrowana w tym samym wywołaniu Zabbix API.

Tool Effect Additional arguments
problem_acknowledge Potwierdzenie problemu. -
problem_unacknowledge Usunięcie potwierdzenia. -
problem_close Ręczne zamknięcie problemu (tylko w przypadku wyzwalaczy, które umożliwiają ręczne zamykanie). -
problem_annotate Zarejestrowanie wiadomości. message (wymagany)
problem_change_severity Zmiana ważności problemu. severity (0-5)
problem_suppress Wyciszenie problemu do określonego czasu lub bezterminowo. suppress_until
problem_unsuppress Usunięcie wyciszenia. -

Nie można tworzyć ani usuwać problemów; wszystkie narzędzia problemów aktualizują istniejące problemy.

Narzędzia do obsługi okresów utrzymania

Narzędzie Metoda API Zabbix Argumenty
maintenance_create maintenance.create name, groupids i/lub hostids, active_since, active_till, timeperiods, description, tags, tags_evaltype
maintenance_update maintenance.update maintenanceid oraz dowolne z powyższych argumentów. Argumenty będące listami zastępują cały zestaw wartości; pusta lista czyści zestaw.
maintenance_delete maintenance.delete maintenanceids

Po zaktualizowaniu okresu utrzymania argumenty będące listami (takie jak hostids, groupids i timeperiods) zastępują istniejące wartości, zamiast je dodawać. Na przykład jeśli okres utrzymania obejmuje hosty A i B, a wywołanie maintenance_update zawiera hostids tylko z hostem C, okres utrzymania będzie obejmować wyłącznie hosta C.

maintenance_create jest jedyną operacją, która nie jest idempotentna, a maintenance_delete jest jedyną operacją, której nie można cofnąć. Aby uniemożliwić ich używanie, zablokuj te narzędzia za pomocą parametru DenyTool.

Działanie narzędzi zapisu

Narzędzia problemów i konserwacji są narzędziami zapisu. Działają w następujący sposób:

  • Argumenty są sprawdzane przed wykonaniem jakiegokolwiek wywołania API Zabbix; jeśli sprawdzanie zakończy się niepowodzeniem, błąd wskazuje niespełnione ograniczenie.
  • Jeśli klient obsługuje tę funkcję, zmiana jest stosowana dopiero po jej zatwierdzeniu przez użytkownika.
  • Zmiana jest wykonywana przez Zabbix przy użyciu tokenu wywołującego. Zabbix sprawdza uprawnienia i rejestruje zmianę w dzienniku audytu w odniesieniu do właściciela tokenu.
  • Błędy Zabbix, w tym błędy uprawnień, są zwracane bez zmian jako obiekt błędu z polami code, message i data.
  • Narzędzia zapisu zwracają bezpośrednio wynik Zabbix; ograniczenia odpowiedzi narzędzi odczytu nie mają zastosowania.
  • Wywołania zapisu nigdy nie są ponawiane przez serwer MCP.

Zasoby

Zasoby używają schematu URI zabbix://<kind>/<id>. Tylko zabbix://about jest uwzględniany w odpowiedzi resources/list; identyfikatorów encji nie można wyliczyć i są one uzyskiwane z wyników działania narzędzi. Odpowiedź resources/templates/list zawiera listę rodzajów encji.

URI Zawartość
zabbix://about URL API, URL frontendu, wersja Zabbix, tożsamość, na którą rozwiązuje się token wywołującego, oraz lista udostępnionych narzędzi.
zabbix://host/<hostid> Rekord hosta bez pozycji, wyzwalaczy, interfejsów i makr.
zabbix://hostgroup/<groupid> Rekord grupy hostów bez listy członków.
zabbix://template/<templateid> Rekord szablonu bez pozycji, wyzwalaczy i reguł wykrywania.
zabbix://templategroup/<groupid> Rekord grupy szablonów bez listy członków.
zabbix://item/<itemid> Definicja pozycji bez bieżącej wartości.
zabbix://trigger/<triggerid> Definicja wyzwalacza bez hostów, zależności, funkcji i znaczników.

Zasób, któremu odpowiada odmówione narzędzie, nie istnieje. Nieistniejąca encja oraz encja, do której właściciel tokenu nie ma dostępu, są w obu przypadkach zgłaszane jako resource not found; przypadki te są celowo nierozróżnialne. Na zasób zabbix://about nie mają wpływu reguły dostępu do narzędzi.