Strumenti e risorse

Panoramica

Il server MCP di Zabbix espone le funzionalità di Zabbix ai client MCP come strumenti e risorse.

I nomi degli strumenti descrivono l'attività. Se il parametro ToolPrefix è impostato, il prefisso viene aggiunto a ogni nome dello strumento; le regole di accesso agli strumenti corrispondono ai nomi semplici elencati di seguito.

Strumenti di lettura

Nota:

• host_get e template_get restituiscono anche i trigger di ciascun oggetto (un insieme limitato di campi), i tag e i template collegati. Gli item, le regole di discovery, le interfacce e le macro vengono restituiti dagli strumenti corrispondenti.
• history_get richiede un intervallo di tempo non superiore a 7 giorni e con inizio non antecedente a 7 giorni fa. L'argomento type deve essere uno tra float, unsigned, character, text, log o json e deve corrispondere al tipo di valore degli item; se il tipo è errato, viene restituito un risultato vuoto, che non può essere distinto da un item privo di dati. La cronologia degli item binari (tipo di valore 5) non può essere recuperata tramite il server MCP.
• Gli strumenti di lettura richiedono un elenco fisso di campi; tutti i campi (output: extend) non vengono mai richiesti.
• I risultati degli strumenti che dispongono di una risorsa contengono il campo uri, in modo che un agent possa passare da un elenco a una singola entità.

Formato della risposta

Tutti gli strumenti di lettura restituiscono la risposta nello stesso formato:

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

Una risposta è limitata dall'argomento limit (predefinito: 100, massimo: 1000) e dalla dimensione serializzata della risposta (MaxResponseSize, predefinita: 64K). La risposta viene interrotta quando viene raggiunto uno dei due limiti. La risposta viene troncata solo tra i risultati, mai all'interno di un risultato, e una risposta troncata indica quale limite è stato raggiunto. Ogni strumento ha un ordine di ordinamento fisso, quindi una risposta troncata contiene sempre l'inizio dell'intero set di risultati. La paginazione non è supportata; per ottenere altri risultati, restringere la query.

Strumenti per i problemi

Tutti gli strumenti per i problemi chiamano event.acknowledge con i flag di azione corrispondenti.
L'argomento eventids è obbligatorio; gli ID degli eventi possono essere recuperati con problem_get.
È possibile aggiungere un messaggio (commento) con qualsiasi strumento per i problemi.
L'argomento message è facoltativo, tranne che per problem_annotate, per il quale è obbligatorio; se specificato, il messaggio viene registrato nella stessa chiamata all'API di Zabbix.

Non è possibile creare o eliminare problemi; tutti gli strumenti per i problemi aggiornano i problemi esistenti.

Strumenti di manutenzione

Quando viene aggiornato un periodo di manutenzione, gli argomenti elenco (come hostids, groupids e timeperiods) sostituiscono i valori esistenti invece di aggiungervi nuovi valori. Ad esempio, se un periodo di manutenzione include gli host A e B e maintenance_update viene chiamato con hostids contenente solo l'host C, il periodo di manutenzione includerà solo l'host C.

maintenance_create è l'unica operazione non idempotente e maintenance_delete è l'unica operazione che non può essere annullata. Per impedirne l'utilizzo, negare questi strumenti con il parametro DenyTool.

Comportamento degli strumenti di scrittura

Gli strumenti per i problemi e la manutenzione sono strumenti di scrittura. Funzionano come segue:

• Gli argomenti vengono convalidati prima di qualsiasi chiamata all'API di Zabbix; se la convalida non riesce, l'errore indica il vincolo non rispettato.
• Se il client lo supporta, la modifica viene applicata solo dopo essere stata approvata dall'utente.
• La modifica viene eseguita da Zabbix utilizzando il token del chiamante. Zabbix verifica le autorizzazioni e registra la modifica nel registro di audit associandola al proprietario del token.
• Gli errori di Zabbix, inclusi gli errori di autorizzazione, vengono restituiti invariati come oggetto di errore con i campi code, message e data.
• Gli strumenti di scrittura restituiscono direttamente il risultato di Zabbix; i limiti di risposta degli strumenti di lettura non si applicano.
• Le chiamate di scrittura non vengono mai ritentate dal server MCP.

Risorse

Le risorse utilizzano lo schema URI zabbix://<kind>/<id>. Solo zabbix://about è incluso nella risposta resources/list; gli ID delle entità non possono essere enumerati e vengono ottenuti dai risultati degli strumenti. La risposta resources/templates/list elenca i tipi di entità.

Una risorsa il cui strumento corrispondente è negato non esiste. Un'entità inesistente e un'entità a cui il proprietario del token non ha accesso vengono entrambe segnalate come resource not found; questi casi sono deliberatamente indistinguibili. La risorsa zabbix://about non è interessata dalle regole di accesso agli strumenti.