opnsense_diag_log_system

Instructions

Implementation Reference

• src/tools/diagnostics.ts:409-413 (handler)

  Handler case for opnsense_diag_log_system: parses args with LogQuerySchema (limit 1-5000, default 500), then calls fetchLogWithFallback(client, 'system', limit) which tries multiple API endpoint variants to retrieve system log entries, and returns the result as JSON text.

  case "opnsense_diag_log_system": {
    const parsed = LogQuerySchema.parse(args);
    const result = await fetchLogWithFallback(client, "system", parsed.limit);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }

• src/tools/diagnostics.ts:207-261 (helper)

  fetchLogWithFallback helper function: tries three API endpoint variants (GET /diagnostics/log/system?limit=N, POST /diagnostics/log/system/search with rowCount, GET /diagnostics/log/core/system?limit=N) and returns the first non-empty response. Used by the log system handler.

  async function fetchLogWithFallback(
    client: OPNsenseClient,
    category: string,
    limit: number,
  ): Promise<unknown> {
    type Variant = { method: "get" | "post"; path: string; body?: unknown };
    const variants: Variant[] = [
      { method: "get", path: `/diagnostics/log/${category}?limit=${limit}` },
      {
        method: "post",
        path: `/diagnostics/log/${category}/search`,
        body: { current: 1, rowCount: limit, sort: {}, searchPhrase: "" },
      },
      { method: "get", path: `/diagnostics/log/core/${category}?limit=${limit}` },
    ];
  
    let lastResult: unknown = null;
    let lastError: unknown = null;
  
    for (const variant of variants) {
      try {
        const result =
          variant.method === "get"
            ? await client.get<unknown>(variant.path)
            : await client.post<unknown>(variant.path, variant.body);
  
        // A non-empty payload wins. Treat the result as non-empty if:
        //   - array with length > 0
        //   - object with rows[].length > 0
        //   - object with any other non-empty data field
        if (isNonEmptyLogPayload(result)) {
          return result;
        }
        lastResult = result;
      } catch (error) {
        lastError = error;
        // Endpoint not present (404) → keep trying. Other errors propagate
        // only if every variant fails.
      }
    }
  
    if (lastResult !== null) return lastResult;
    if (lastError) throw lastError;
    return [];
  }
  
  function isNonEmptyLogPayload(payload: unknown): boolean {
    if (Array.isArray(payload)) return payload.length > 0;
    if (payload && typeof payload === "object") {
      const obj = payload as Record<string, unknown>;
      if (Array.isArray(obj["rows"]) && (obj["rows"] as unknown[]).length > 0) return true;
      if (typeof obj["total"] === "number" && obj["total"] > 0) return true;
    }
    return false;
  }

• src/tools/diagnostics.ts:33-35 (schema)

  LogQuerySchema - Zod schema for log query input validation: limit is a coerced integer between 1 and 5000, defaults to 500.

  const LogQuerySchema = z.object({
    limit: z.coerce.number().int().min(1).max(5000).optional().default(500),
  });

• src/tools/diagnostics.ts:144-153 (registration)

  Tool definition registration for opnsense_diag_log_system: name, description ('Retrieve recent OPNsense system log entries'), and input schema (limit parameter). Exported in diagnosticsToolDefinitions array.

  {
    name: "opnsense_diag_log_system",
    description: "Retrieve recent OPNsense system log entries (kernel, generic system events).",
    inputSchema: {
      type: "object" as const,
      properties: {
        limit: { type: "number", description: "Number of log entries (1-5000, default 500)" },
      },
    },
  },

• src/index.ts:61-61 (registration)

  Registration: maps all diagnosticsToolDefinitions (including opnsense_diag_log_system) to the handleDiagnosticsTool handler in the central toolHandlers map via server.setRequestHandler(CallToolRequestSchema).

  for (const def of diagnosticsToolDefinitions) toolHandlers.set(def.name, handleDiagnosticsTool);