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());