firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:26-141 (handler)

  The GetBoxesHandler class implements the core logic for the 'get_boxes' tool. It validates optional group_id parameter, calls firewalla.getBoxes(), normalizes and enriches the box data (including geo-enrichment for public IPs), and returns a unified response with total_boxes and detailed box information.

  export class GetBoxesHandler extends BaseToolHandler {
    name = 'get_boxes';
    description =
      'List all managed Firewalla boxes with status and configuration details.';
    category = 'analytics' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false,
        enableFieldNormalization: false,
        additionalMeta: {
          data_source: 'flow_trends',
          entity_type: 'historical_flow_data',
          supports_geographic_enrichment: false,
          supports_field_normalization: false,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      _args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const groupIdValidation = ParameterValidator.validateOptionalString(
          _args?.group_id,
          'group_id'
        );
  
        if (!groupIdValidation.isValid) {
          return this.createErrorResponse(
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            groupIdValidation.errors
          );
        }
  
        const groupId = groupIdValidation.sanitizedValue;
  
        const boxesResponse = await withToolTimeout(
          async () => firewalla.getBoxes(groupId as string),
          this.name
        );
  
        const boxResults = SafeAccess.safeArrayAccess(
          boxesResponse.results,
          (arr: any[]) => arr,
          []
        ) as any[];
  
        const normalizedBoxes = batchNormalize(boxResults, {
          name: (v: any) => sanitizeFieldValue(v, 'Unknown Box').value,
          model: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          mode: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          version: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          group: (v: any) => (v ? normalizeUnknownFields(v) : null),
          location: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          online: (v: any) => Boolean(v),
          gid: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          license: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          publicIP: (v: any) => sanitizeFieldValue(v, 'unknown').value,
          deviceCount: (v: any) => Number(v) || 0,
          ruleCount: (v: any) => Number(v) || 0,
          alarmCount: (v: any) => Number(v) || 0,
        });
  
        const startTime = Date.now();
  
        const boxData = normalizedBoxes.map((box: any) => {
          const timestampNormalized = normalizeTimestamps(box);
          const finalBox = timestampNormalized.data;
  
          return {
            gid: SafeAccess.getNestedValue(finalBox, 'gid', 'unknown'),
            name: finalBox.name,
            model: finalBox.model,
            mode: finalBox.mode,
            version: finalBox.version,
            online: SafeAccess.getNestedValue(finalBox, 'online', false),
            last_seen: SafeAccess.getNestedValue(finalBox, 'lastSeen', 0),
            license: SafeAccess.getNestedValue(finalBox, 'license', null),
            public_ip: finalBox.publicIP || finalBox.public_ip || 'unknown',
            group: finalBox.group,
            location: finalBox.location,
            device_count: SafeAccess.getNestedValue(finalBox, 'deviceCount', 0),
            rule_count: SafeAccess.getNestedValue(finalBox, 'ruleCount', 0),
            alarm_count: SafeAccess.getNestedValue(finalBox, 'alarmCount', 0),
          };
        });
  
        // Apply geographic enrichment for public IP addresses
        const enrichedBoxData = await this.enrichGeoIfNeeded(boxData, [
          'public_ip',
        ]);
  
        const unifiedResponseData = {
          total_boxes: normalizedBoxes.length,
          boxes: enrichedBoxData,
        };
  
        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 boxes: ${errorMessage}`,
          ErrorType.API_ERROR
        );
      }
    }
  }

• src/server.ts:525-537 (schema)

  Defines the input schema for the get_boxes tool in the MCP server's tools configuration, specifying an optional 'group' parameter.

  name: 'get_boxes',
  description: 'Retrieve list of Firewalla boxes',
  inputSchema: {
    type: 'object',
    properties: {
      group: {
        type: 'string',
        description:
          'Get boxes within a specific group (requires group ID)',
      },
    },
    required: [],
  },

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

  Registers the GetBoxesHandler instance in the central ToolRegistry during initialization.

  this.register(new GetBoxesHandler());

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

  Imports the GetBoxesHandler from the analytics handlers module for use in the registry.

  GetBoxesHandler,
  GetSimpleStatisticsHandler,