dns_get_stats

Instructions

Implementation Reference

• src/tools/dashboard.ts:30-47 (handler)

  The handler function for the dns_get_stats tool. Calls the /api/dashboard/stats/get endpoint with the given period, then returns stats, topClients, topDomains, and topBlockedDomains.

  handler: async (args) => {
    const period = args.period
      ? validatePeriod(args.period as string)
      : "LastDay";
    const data = await client.callOrThrow("/api/dashboard/stats/get", {
      type: period,
    });
    const stats = data.stats as Record<string, unknown>;
    const topClients = data.topClients as unknown[];
    const topDomains = data.topDomains as unknown[];
    const topBlocked = data.topBlockedDomains as unknown[];
  
    return JSON.stringify(
      { stats, topClients, topDomains, topBlockedDomains: topBlocked },
      null,
      2
    );
  },

• src/tools/dashboard.ts:12-27 (schema)

  Input schema for dns_get_stats. Defines 'period' as an optional string enum (LastHour, LastDay, LastWeek, LastMonth, LastYear).

  inputSchema: {
    type: "object",
    properties: {
      period: {
        type: "string",
        enum: [
          "LastHour",
          "LastDay",
          "LastWeek",
          "LastMonth",
          "LastYear",
        ],
        description: "Time period for stats (default: LastDay)",
      },
    },
  },

• src/tools/dashboard.ts:6-48 (registration)

  Tool registration: dns_get_stats is registered as a ToolEntry inside the dashboardTools() function array, with definition, readonly=true, and handler.

  return [
    {
      definition: {
        name: "dns_get_stats",
        description:
          "Get DNS query statistics for a time period. Returns total queries, cached, blocked, failure counts, plus top clients, top domains, and top blocked domains.",
        inputSchema: {
          type: "object",
          properties: {
            period: {
              type: "string",
              enum: [
                "LastHour",
                "LastDay",
                "LastWeek",
                "LastMonth",
                "LastYear",
              ],
              description: "Time period for stats (default: LastDay)",
            },
          },
        },
      },
      readonly: true,
      handler: async (args) => {
        const period = args.period
          ? validatePeriod(args.period as string)
          : "LastDay";
        const data = await client.callOrThrow("/api/dashboard/stats/get", {
          type: period,
        });
        const stats = data.stats as Record<string, unknown>;
        const topClients = data.topClients as unknown[];
        const topDomains = data.topDomains as unknown[];
        const topBlocked = data.topBlockedDomains as unknown[];
  
        return JSON.stringify(
          { stats, topClients, topDomains, topBlockedDomains: topBlocked },
          null,
          2
        );
      },
    },

• src/tools/index.ts:14-27 (registration)

  Aggregated registration: getAllTools() collects all tool entries including dashboardTools which contains dns_get_stats.

  export function getAllTools(client: TechnitiumClient): ToolEntry[] {
    return [
      ...dashboardTools(client),
      ...dnsClientTools(client),
      ...zoneTools(client),
      ...recordTools(client),
      ...blockingTools(client),
      ...cacheTools(client),
      ...settingsTools(client),
      ...logTools(client),
      ...appTools(client),
      ...dnssecTools(client),
    ];
  }

• src/validate.ts:66-71 (helper)

  The validatePeriod helper function used by the handler to validate the 'period' input parameter.

  export function validatePeriod(period: string): string {
    if (!VALID_PERIODS.has(period)) {
      throw new Error(`Invalid period: ${period}. Valid: ${[...VALID_PERIODS].join(", ")}`);
    }
    return period;
  }