ツールとリソース

概要

Zabbix MCPサーバーは、Zabbixの機能をMCPクライアントにツールおよびリソースとして公開します。

ツール名はアクティビティを表します。 ToolPrefixパラメータが設定されている場合、すべてのツール名にプレフィックスが追加されます。ツールアクセスルールでは、以下に示すプレーンな名前が照合されます。

読み取りツール

ツール Zabbix API メソッド 引数 並べ替え基準 リソース
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 または global, macro_names, limit macro -
problem_get problem.get eventids, groupids, hostids, severities, acknowledged, suppressed, recent, limit event ID、降順 -
maintenance_get maintenance.get maintenanceids, groupids, hostids, limit name -
history_get history.get itemids, time_from, time_till, type, limit clock、降順 -
trigger_get trigger.get triggerids, hostids, search, limit description zabbix://trigger/<id>

次の点に注意してください。

  • 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 引数は必須です。イベントIDは problem_get で取得できます。
任意の障害ツールでメッセージ（コメント）を追加できます。
message 引数は、problem_annotate を除いて任意です。指定した場合、メッセージは同じZabbix API呼び出しで記録されます。

Tool Effect Additional arguments
problem_acknowledge 障害を承認します。 -
problem_unacknowledge 承認を解除します。 -
problem_close 障害を手動でクローズします（手動クローズを許可するトリガーの場合のみ）。 -
problem_annotate メッセージを記録します。 message（必須）
problem_change_severity 障害の深刻度を変更します。 severity（0-5）
problem_suppress 指定した時刻まで、または無期限に障害を抑制します。 suppress_until
problem_unsuppress 抑制を解除します。 -

障害を作成または削除することはできません。すべての障害ツールは既存の障害を更新します。

メンテナンスツール

ツール Zabbix APIメソッド 引数
maintenance_create maintenance.create name、groupids および/または hostids、active_since、active_till、timeperiods、description、tags、tags_evaltype
maintenance_update maintenance.update maintenanceid および上記の引数のいずれか。リスト引数は値のセット全体を置き換えます。空のリストを指定すると、セットがクリアされます。
maintenance_delete maintenance.delete maintenanceids

メンテナンス期間を更新すると、リスト引数（hostids、groupids、timeperiods など）は既存の値に追加されるのではなく、既存の値を置き換えます。 たとえば、メンテナンス期間がホストAとホストBを対象としていて、hostids にホストCのみを含めて maintenance_update を呼び出した場合、メンテナンス期間の対象はホストCのみになります。

maintenance_create は冪等ではない唯一の操作であり、maintenance_delete は元に戻せない唯一の操作です。 これらの使用を防止するには、DenyTool パラメータでこれらのツールを拒否します。

書き込みツールの動作

障害およびメンテナンスツールは書き込みツールです。 次のように動作します。

  • Zabbix API を呼び出す前に引数が検証されます。検証に失敗した場合、満たされていない制約がエラーに示されます。
  • クライアントが対応している場合、変更はユーザーによる承認後にのみ適用されます。
  • 変更は、呼び出し元のトークンを使用して Zabbix によって実行されます。Zabbix は権限を確認し、トークン所有者に対する監査ログに変更を記録します。
  • 権限エラーを含む Zabbix のエラーは、code、message、data フィールドを持つエラーオブジェクトとして変更せずに返されます。
  • 書き込みツールは Zabbix の結果を直接返します。読み取りツールの応答制限は適用されません。
  • 書き込み呼び出しが MCP サーバーによって再試行されることはありません。

リソース

リソースでは、zabbix://<kind>/<id> URIスキームを使用します。 resources/list のレスポンスに含まれるのは zabbix://about のみです。エンティティIDは列挙できず、ツールの結果から取得します。 resources/templates/list のレスポンスには、エンティティの種類が一覧表示されます。

URI 内容
zabbix://about API URL、WebインターフェースのURL、Zabbixのバージョン、呼び出し元のトークンが解決されるID、および公開されているツールの一覧。
zabbix://host/<hostid> アイテム、トリガー、インターフェース、マクロを含まないホストレコード。
zabbix://hostgroup/<groupid> メンバーの一覧を含まないホストグループレコード。
zabbix://template/<templateid> アイテム、トリガー、ディスカバリルールを含まないテンプレートレコード。
zabbix://templategroup/<groupid> メンバーの一覧を含まないテンプレートグループレコード。
zabbix://item/<itemid> 現在の値を含まないアイテム定義。
zabbix://trigger/<triggerid> ホスト、依存関係、関数、タグを含まないトリガー定義。

対応するツールへのアクセスが拒否されているリソースは存在しません。 存在しないエンティティと、トークン所有者がアクセス権を持たないエンティティは、どちらも resource not found として報告されます。これらのケースは意図的に区別できないようになっています。 zabbix://about リソースは、ツールのアクセスルールの影響を受けません。