list_agents

Instructions

Implementation Reference

• src/tools/agents.ts:5-84 (registration)

  The registerAgentTools function registers the 'list_agents' tool on the MCP server via server.tool().

  export function registerAgentTools(
    server: McpServer,
    client: WazuhClient
  ): void {
    server.tool(
      "list_agents",
      "List all Wazuh agents with optional status filtering",
      {
        status: z
          .enum(["active", "disconnected", "never_connected", "pending"])
          .optional()
          .describe(
            "Filter by agent status: active, disconnected, never_connected, or pending"
          ),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .default(10)
          .describe("Maximum number of agents to return (1-100)"),
        offset: z
          .number()
          .int()
          .min(0)
          .default(0)
          .describe("Pagination offset"),
        sort: z
          .string()
          .optional()
          .describe("Sort field with direction prefix (e.g., '-name', '+id')"),
      },
      async ({ status, limit, offset, sort }) => {
        try {
          const params: Record<string, string | number> = { limit, offset };
          if (status) params.status = status;
          if (sort) params.sort = sort;
  
          const response = await client.getAgents(params);
          const data = response.data;
  
          const result = {
            agents: data.affected_items.map((agent) => ({
              id: agent.id,
              name: agent.name,
              ip: agent.ip,
              status: agent.status,
              group: agent.group,
              os_name: agent.os?.name,
              os_version: agent.os?.version,
              os_platform: agent.os?.platform,
              version: agent.version,
              manager: agent.manager,
              node_name: agent.node_name,
              date_add: agent.dateAdd,
              last_keepalive: agent.lastKeepAlive,
            })),
            total: data.total_affected_items,
            limit,
            offset,
          };
  
          return {
            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  error: error instanceof Error ? error.message : String(error),
                }),
              },
            ],
            isError: true,
          };
        }
      }
    );

• src/tools/agents.ts:37-84 (handler)

  The async handler that executes the 'list_agents' tool logic. It calls client.getAgents() with status/limit/offset/sort params and returns a formatted JSON response with agent details (id, name, ip, status, group, os, version, manager, node, dates).

    async ({ status, limit, offset, sort }) => {
      try {
        const params: Record<string, string | number> = { limit, offset };
        if (status) params.status = status;
        if (sort) params.sort = sort;
  
        const response = await client.getAgents(params);
        const data = response.data;
  
        const result = {
          agents: data.affected_items.map((agent) => ({
            id: agent.id,
            name: agent.name,
            ip: agent.ip,
            status: agent.status,
            group: agent.group,
            os_name: agent.os?.name,
            os_version: agent.os?.version,
            os_platform: agent.os?.platform,
            version: agent.version,
            manager: agent.manager,
            node_name: agent.node_name,
            date_add: agent.dateAdd,
            last_keepalive: agent.lastKeepAlive,
          })),
          total: data.total_affected_items,
          limit,
          offset,
        };
  
        return {
          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                error: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/tools/agents.ts:12-36 (schema)

  Zod input schema for the 'list_agents' tool: optional status filter (active/disconnected/never_connected/pending), limit (1-100, default 10), offset (default 0), and optional sort field.

  {
    status: z
      .enum(["active", "disconnected", "never_connected", "pending"])
      .optional()
      .describe(
        "Filter by agent status: active, disconnected, never_connected, or pending"
      ),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(10)
      .describe("Maximum number of agents to return (1-100)"),
    offset: z
      .number()
      .int()
      .min(0)
      .default(0)
      .describe("Pagination offset"),
    sort: z
      .string()
      .optional()
      .describe("Sort field with direction prefix (e.g., '-name', '+id')"),
  },

• src/client.ts:232-236 (helper)

  The client.getAgents() method called by the handler. It makes a GET request to the '/agents' Wazuh API endpoint with the provided parameters.

  async getAgents(
    params: Record<string, string | number> = {}
  ): Promise<WazuhApiResponse<WazuhPaginatedData<WazuhAgent>>> {
    return this.get("/agents", params);
  }

• src/types.ts:33-53 (helper)

  The WazuhAgent type definition used for the API response data structure that the handler maps into its JSON output.

  export interface WazuhAgent {
    id: string;
    name: string;
    ip: string;
    status: string;
    group?: string[];
    os?: {
      name?: string;
      version?: string;
      platform?: string;
      arch?: string;
      codename?: string;
    };
    version?: string;
    manager?: string;
    node_name?: string;
    dateAdd?: string;
    lastKeepAlive?: string;
    registerIP?: string;
    status_code?: number;
  }