firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:143-275 (handler)

  Implements the core logic for the get_simple_statistics tool. Fetches statistics from Firewalla API using firewalla.getSimpleStatistics(), processes box status, alarms, rules, calculates availability and health score, and returns unified response.

  export class GetSimpleStatisticsHandler extends BaseToolHandler {
    name = 'get_simple_statistics';
    description =
      'Get network statistics including box status, security metrics, and system health indicators.';
    category = 'analytics' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // No IP fields in statistics
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'statistics',
          entity_type: 'network_statistics',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      _args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const statsResponse = await withToolTimeout(
          async () => firewalla.getSimpleStatistics(),
          this.name
        );
        const stats = SafeAccess.safeArrayAccess(
          statsResponse?.results,
          (arr: any[]) => arr[0],
          {}
        ) as any;
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          statistics: {
            online_boxes: SafeAccess.getNestedValue(
              stats,
              'onlineBoxes',
              0
            ) as number,
            offline_boxes: SafeAccess.getNestedValue(
              stats,
              'offlineBoxes',
              0
            ) as number,
            total_boxes:
              (SafeAccess.getNestedValue(stats, 'onlineBoxes', 0) as number) +
              (SafeAccess.getNestedValue(stats, 'offlineBoxes', 0) as number),
            total_alarms: SafeAccess.getNestedValue(stats, 'alarms', 0) as number,
            total_rules: SafeAccess.getNestedValue(stats, 'rules', 0) as number,
            box_availability: this.calculateBoxAvailability(stats),
          },
          summary: {
            status:
              (SafeAccess.getNestedValue(stats, 'onlineBoxes', 0) as number) > 0
                ? 'operational'
                : 'offline',
            health_score: this.calculateHealthScore(stats),
            active_monitoring:
              (SafeAccess.getNestedValue(stats, 'onlineBoxes', 0) as number) > 0,
          },
        };
  
        const executionTime = Date.now() - startTime;
  
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        return this.createErrorResponse(
          `Failed to get simple statistics: ${errorMessage}`,
          ErrorType.API_ERROR
        );
      }
    }
  
    private calculateBoxAvailability(stats: any): number {
      const onlineBoxes = SafeAccess.getNestedValue(
        stats,
        'onlineBoxes',
        0
      ) as number;
      const offlineBoxes = SafeAccess.getNestedValue(
        stats,
        'offlineBoxes',
        0
      ) as number;
      const totalBoxes = onlineBoxes + offlineBoxes;
      return totalBoxes > 0 ? Math.round((onlineBoxes / totalBoxes) * 100) : 0;
    }
  
    private calculateHealthScore(stats: any): number {
      let score = 100;
  
      const onlineBoxes = SafeAccess.getNestedValue(
        stats,
        'onlineBoxes',
        0
      ) as number;
      const offlineBoxes = SafeAccess.getNestedValue(
        stats,
        'offlineBoxes',
        0
      ) as number;
      const alarms = SafeAccess.getNestedValue(stats, 'alarms', 0) as number;
      const rules = SafeAccess.getNestedValue(stats, 'rules', 0) as number;
  
      const totalBoxes = onlineBoxes + offlineBoxes;
      if (totalBoxes === 0) {
        return 0;
      }
  
      // Penalize for offline boxes (up to -40 points)
      const offlineRatio = offlineBoxes / totalBoxes;
      score -= Math.round(offlineRatio * 40);
  
      // Penalize for high alarm count (up to -30 points)
      const alarmPenalty = Math.min(alarms * 2, 30);
      score -= alarmPenalty;
  
      // Bonus for having active rules (up to +10 points)
      const ruleBonus = Math.min(rules / 10, 10);
      score += ruleBonus;
  
      return Math.max(0, Math.min(100, score));
    }
  }

• src/server.ts:539-551 (schema)

  Defines the input schema for the get_simple_statistics tool in the ListToolsRequestSchema handler, specifying optional 'group' parameter.

  {
    name: 'get_simple_statistics',
    description: 'Retrieve basic statistics overview',
    inputSchema: {
      type: 'object',
      properties: {
        group: {
          type: 'string',
          description: 'Get statistics for specific box group',
        },
      },
      required: [],
    },

• src/tools/registry.ts:162-162 (registration)

  Registers the GetSimpleStatisticsHandler instance in the ToolRegistry during initialization.

  this.register(new GetSimpleStatisticsHandler());