firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:403-577 (handler)

  The primary handler class GetStatisticsByBoxHandler that implements the core logic for the 'get_statistics_by_box' tool. It extends BaseToolHandler, defines the tool name and description, and in the execute method calls firewalla.getStatisticsByBox() to fetch data, processes box statistics with validation, calculates summaries, and returns a unified response.

  export class GetStatisticsByBoxHandler extends BaseToolHandler {
    name = 'get_statistics_by_box';
    description =
      'Get statistics for each Firewalla box with activity scores and health monitoring. No required parameters. Data cached for 1 hour for performance.';
    category = 'analytics' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // No IP fields in box statistics
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'box_statistics',
          entity_type: 'firewalla_box_statistics',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      _args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const stats = await withToolTimeout(
          async () => firewalla.getStatisticsByBox(),
          this.name
        );
  
        // Validate stats response structure
        if (!stats || typeof stats !== 'object') {
          throw new Error('Invalid stats response: not an object');
        }
  
        if (
          !SafeAccess.getNestedValue(stats, 'results') ||
          !Array.isArray(stats.results)
        ) {
          throw new Error('Invalid stats response: results is not an array');
        }
  
        // Process and validate each box statistic
        const boxStatistics = SafeAccess.safeArrayMap(
          stats.results,
          (stat: any) => {
            const boxMeta = SafeAccess.getNestedValue(stat, 'meta', {}) as any;
            return {
              box_id: SafeAccess.getNestedValue(
                boxMeta,
                'gid',
                'unknown'
              ) as string,
              name: SafeAccess.getNestedValue(
                boxMeta,
                'name',
                'Unknown Box'
              ) as string,
              model: SafeAccess.getNestedValue(
                boxMeta,
                'model',
                'unknown'
              ) as string,
              status: (SafeAccess.getNestedValue(
                boxMeta,
                'online',
                false
              ) as boolean)
                ? 'online'
                : 'offline',
              version: SafeAccess.getNestedValue(
                boxMeta,
                'version',
                'unknown'
              ) as string,
              location: SafeAccess.getNestedValue(
                boxMeta,
                'location',
                'unknown'
              ) as string,
              device_count: SafeAccess.getNestedValue(
                boxMeta,
                'deviceCount',
                0
              ) as number,
              rule_count: SafeAccess.getNestedValue(
                boxMeta,
                'ruleCount',
                0
              ) as number,
              alarm_count: SafeAccess.getNestedValue(
                boxMeta,
                'alarmCount',
                0
              ) as number,
              activity_score: SafeAccess.getNestedValue(
                stat,
                'value',
                0
              ) as number,
              last_seen: (SafeAccess.getNestedValue(
                boxMeta,
                'lastSeen',
                0
              ) as number)
                ? unixToISOString(
                    SafeAccess.getNestedValue(boxMeta, 'lastSeen', 0) as number
                  )
                : 'Never',
            };
          }
        ).sort((a: any, b: any) => b.activity_score - a.activity_score);
  
        // Calculate summary with safe operations
        const onlineBoxes = SafeAccess.safeArrayFilter(
          stats.results,
          (s: any) =>
            SafeAccess.getNestedValue(s, 'meta.online', false) as boolean
        ).length;
  
        const totalDevices = stats.results.reduce(
          (sum: number, s: any) =>
            sum + (SafeAccess.getNestedValue(s, 'meta.deviceCount', 0) as number),
          0
        );
        const totalRules = stats.results.reduce(
          (sum: number, s: any) =>
            sum + (SafeAccess.getNestedValue(s, 'meta.ruleCount', 0) as number),
          0
        );
        const totalAlarms = stats.results.reduce(
          (sum: number, s: any) =>
            sum + (SafeAccess.getNestedValue(s, 'meta.alarmCount', 0) as number),
          0
        );
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          total_boxes: stats.results.length,
          box_statistics: boxStatistics,
          summary: {
            online_boxes: onlineBoxes,
            total_devices: totalDevices,
            total_rules: totalRules,
            total_alarms: totalAlarms,
          },
        };
  
        const executionTime = Date.now() - startTime;
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        logger.error(
          'Error in get_statistics_by_box',
          error instanceof Error ? error : new Error(String(error))
        );
  
        return this.createErrorResponse(
          `Failed to get box statistics: ${error instanceof Error ? error.message : 'Unknown error'}`,
          ErrorType.API_ERROR,
          {
            total_boxes: 0,
            box_statistics: [],
            summary: {
              online_boxes: 0,
              total_devices: 0,
              total_rules: 0,
              total_alarms: 0,
            },
          }
        );
      }
    }

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

  Registration of the GetStatisticsByBoxHandler in the central ToolRegistry during automatic handler registration in the constructor.

  this.register(new GetStatisticsByBoxHandler());

• src/server.ts:576-601 (schema)

  The input schema definition for the 'get_statistics_by_box' tool provided in the MCP server's listTools response, defining parameters like type, group, and limit.

  name: 'get_statistics_by_box',
  description:
    'Get statistics for each Firewalla box (top boxes by blocked flows or security alarms)',
  inputSchema: {
    type: 'object',
    properties: {
      type: {
        type: 'string',
        enum: ['topBoxesByBlockedFlows', 'topBoxesBySecurityAlarms'],
        description: 'Statistics type to retrieve',
        default: 'topBoxesByBlockedFlows',
      },
      group: {
        type: 'string',
        description: 'Get statistics for specific box group',
      },
      limit: {
        type: 'number',
        description:
          'Maximum number of results (optional, default: 5)',
        minimum: 1,
        default: 5,
      },
    },
    required: [],
  },