Инструменты и ресурсы

Обзор

MCP-сервер Zabbix предоставляет клиентам MCP функциональность Zabbix в виде инструментов и ресурсов.

Названия инструментов описывают выполняемое действие. Если задан параметр ToolPrefix, этот префикс добавляется к названию каждого инструмента; правила доступа к инструментам сопоставляются с указанными ниже названиями без префикса.

Инструменты чтения

Обратите внимание:

• host_get и template_get также возвращают триггеры каждого объекта (ограниченный набор полей), теги и связанные шаблоны. Элементы данных, правила обнаружения, интерфейсы и макросы возвращаются соответствующими инструментами.
• history_get требует диапазон времени не более 7 дней, начинающийся не ранее чем 7 дней назад. Аргумент type должен иметь одно из значений float, unsigned, character, text, log или json и соответствовать типу значения элементов данных; если тип указан неправильно, возвращается пустой результат, который невозможно отличить от элемента данных без данных. Историю двоичных элементов данных (тип значения 5) нельзя получить через MCP-сервер.
• Инструменты чтения запрашивают фиксированный список полей; все поля (output: extend) никогда не запрашиваются.
• Результаты инструментов, у которых есть ресурс, содержат поле uri, чтобы агент мог перейти от списка к отдельной сущности.

Формат ответа

Все инструменты чтения возвращают ответ в одном и том же формате:

{
  "results": [ ... ],
  "count": 2,
  "truncated": true,
  "truncated_by": "count",
  "limit": 2,
  "note": "The result count limit was reached ..."
}

Ответ ограничивается аргументом limit (по умолчанию: 100, максимум: 1000) и сериализованным размером ответа (MaxResponseSize, по умолчанию: 64K). Формирование ответа прекращается при достижении любого из этих ограничений. Ответ усекается только между результатами, но не внутри результата; в усечённом ответе указывается, какое ограничение было достигнуто. Для каждого инструмента задан фиксированный порядок сортировки, поэтому усечённый ответ всегда содержит начало полного набора результатов. Постраничная выдача не поддерживается; чтобы получить другие результаты, сузьте запрос.

Инструменты для работы с проблемами

Все инструменты для работы с проблемами вызывают event.acknowledge с соответствующими флагами действий.
Аргумент eventids является обязательным; идентификаторы событий можно получить с помощью problem_get.
С помощью любого инструмента для работы с проблемами можно добавить сообщение (комментарий).
Аргумент message является необязательным, за исключением problem_annotate, где он обязателен; если он указан, сообщение записывается в рамках того же вызова API Zabbix.

Проблемы нельзя создавать или удалять; все инструменты для работы с проблемами обновляют существующие проблемы.

Инструменты обслуживания

При обновлении периода обслуживания аргументы-списки (например, hostids, groupids и timeperiods) заменяют существующие значения, а не добавляются к ним. Например, если период обслуживания охватывает узлы сети A и B, а вызывается maintenance_update с hostids, содержащим только узел сети C, период обслуживания будет охватывать только узел сети C.

maintenance_create — единственная операция, которая не является идемпотентной, а maintenance_delete — единственная операция, которую невозможно отменить. Чтобы запретить их использование, запретите эти инструменты с помощью параметра DenyTool.

Поведение инструментов записи

Инструменты для работы с проблемами и обслуживаниями являются инструментами записи. Они работают следующим образом:

• Аргументы проверяются до любого вызова API Zabbix; если проверка не пройдена, в ошибке указывается невыполненное ограничение.
• Если клиент поддерживает эту возможность, изменение применяется только после его одобрения пользователем.
• Изменение выполняется Zabbix с использованием токена вызывающей стороны. Zabbix проверяет права доступа и записывает изменение в журнал аудита с указанием владельца токена.
• Ошибки Zabbix, включая ошибки доступа, возвращаются без изменений в виде объекта ошибки с полями code, message и data.
• Инструменты записи напрямую возвращают результат Zabbix; ограничения на размер ответа инструментов чтения не применяются.
• Вызовы записи никогда не повторяются MCP-сервером.

Ресурсы

Ресурсы используют схему URI zabbix://<kind>/<id>. Только zabbix://about включается в ответ resources/list; идентификаторы сущностей нельзя перечислить, их получают из результатов работы инструментов. В ответе resources/templates/list перечислены виды сущностей.

Ресурс, для которого соответствующий инструмент запрещен, не существует. Несуществующая сущность и сущность, к которой владелец токена не имеет доступа, в обоих случаях обозначаются как ресурс не найден; эти случаи намеренно неразличимы. На ресурс zabbix://about правила доступа к инструментам не распространяются.