Ferramentas e recursos

Visão geral

O Zabbix MCP server expõe as funcionalidades do Zabbix para clientes MCP como tools e resources.

Os nomes das tools descrevem a atividade. Se o parâmetro ToolPrefix estiver definido, o prefixo será adicionado a todos os nomes das tools; as regras de acesso às tools correspondem aos nomes simples listados abaixo.

Ferramentas de leitura

Observe que:

• host_get e template_get também retornam os triggers de cada objeto (um conjunto limitado de campos), tags e templates vinculados. Items, regras de descoberta, interfaces e macros são retornados pelas ferramentas correspondentes.
• history_get requer um intervalo de tempo não superior a 7 dias e que comece no máximo 7 dias atrás. O argumento type deve ser um dos seguintes: float, unsigned, character, text, log ou json, e deve corresponder ao tipo de valor dos items; se o tipo estiver incorreto, será retornado um resultado vazio, que não pode ser distinguido de um item sem dados. O histórico de items binários (tipo de valor 5) não pode ser recuperado por meio do server MCP.
• As ferramentas de leitura solicitam uma lista fixa de campos; todos os campos (output: extend) nunca são solicitados.
• Os resultados das ferramentas que têm um recurso contêm o campo uri, para que um agent possa prosseguir de uma lista para uma única entidade.

Formato da resposta

Todas as ferramentas de leitura retornam a resposta no mesmo formato:

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

Uma resposta é limitada pelo argumento limit (padrão: 100, máximo: 1000) e pelo tamanho serializado da resposta (MaxResponseSize, padrão: 64K). A resposta é interrompida quando qualquer um dos limites é atingido. A resposta é truncada somente entre os resultados, nunca dentro de um resultado, e uma resposta truncada indica qual limite foi atingido. Cada ferramenta tem uma ordem de classificação fixa, portanto, uma resposta truncada sempre corresponde ao início do conjunto completo de resultados. A paginação não é compatível; para obter outros resultados, restrinja a consulta.

Ferramentas de problemas

Todas as ferramentas de problemas chamam event.acknowledge com os sinalizadores de ação correspondentes.
O argumento eventids é obrigatório; os IDs dos eventos podem ser obtidos com problem_get.
Uma mensagem (comentário) pode ser adicionada com qualquer ferramenta de problemas.
O argumento message é opcional, exceto para problem_annotate, em que é obrigatório; se especificado, a mensagem é registrada na mesma chamada da API do Zabbix.

Não é possível criar ou excluir problemas; todas as ferramentas de problemas atualizam problemas existentes.

Ferramentas de manutenção

Quando um período de manutenção é atualizado, os argumentos de lista (como hostids, groupids e timeperiods) substituem os valores existentes em vez de adicioná-los. Por exemplo, se um período de manutenção abranger os hosts A e B e maintenance_update for chamado com hostids contendo apenas o host C, o período de manutenção abrangerá somente o host C.

maintenance_create é a única operação que não é idempotente, e maintenance_delete é a única operação que não pode ser revertida. Para impedir seu uso, negue essas ferramentas com o parâmetro DenyTool.

Comportamento das ferramentas de gravação

As ferramentas de problemas e manutenção são ferramentas de gravação. Elas funcionam da seguinte forma:

• Os argumentos são validados antes de qualquer chamada à API do Zabbix; se a validação falhar, o erro identificará a restrição que não foi atendida.
• Se o cliente oferecer suporte, a alteração será aplicada somente após ser aprovada pelo usuário.
• A alteração é realizada pelo Zabbix usando o token do chamador. O Zabbix verifica as permissões e registra a alteração no log de auditoria associada ao proprietário do token.
• Os erros do Zabbix, incluindo erros de permissão, são retornados inalterados como um objeto de erro com os campos code, message e data.
• As ferramentas de gravação retornam diretamente o resultado do Zabbix; os limites de resposta das ferramentas de leitura não se aplicam.
• As chamadas de gravação nunca são repetidas pelo servidor MCP.

Recursos

Os recursos usam o esquema de URI zabbix://<kind>/<id>. Somente zabbix://about está incluído na resposta de resources/list; os IDs das entidades não podem ser enumerados e são obtidos nos resultados das ferramentas. A resposta de resources/templates/list lista os tipos de entidades.

Um recurso cuja ferramenta correspondente tenha acesso negado não existe. Uma entidade inexistente e uma entidade à qual o proprietário do token não tem acesso são relatadas como recurso não encontrado; esses casos são deliberadamente indistinguíveis. O recurso zabbix://about não é afetado pelas regras de acesso às ferramentas.