firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/network.ts:403-543 (handler)

  The primary handler class implementing the get_bandwidth_usage tool. Validates parameters (period enum ['1h','24h','7d','30d'], limit), calls firewalla.getBandwidthUsage(period, limit), processes results into structured bandwidth data per device (upload/download/total bytes/MB/GB), applies geo-enrichment on IP, and returns standardized paginated response.

  export class GetBandwidthUsageHandler extends BaseToolHandler {
    name = 'get_bandwidth_usage';
    description =
      'Get top bandwidth consuming devices by data usage. Requires limit and period parameters. Data is cached for 5 minutes for performance.';
    category = 'network' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: true,
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'bandwidth_usage',
          entity_type: 'device_bandwidth',
          supports_geographic_enrichment: true,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        // Parameter validation
        const periodValidation = ParameterValidator.validateEnum(
          args?.period,
          'period',
          ['1h', '24h', '7d', '30d'],
          true
        );
        const limitValidation = ParameterValidator.validateNumber(
          args?.limit,
          'limit',
          {
            required: false,
            defaultValue: 10,
            ...getLimitValidationConfig(this.name),
          }
        );
  
        const validationResult = ParameterValidator.combineValidationResults([
          periodValidation,
          limitValidation,
        ]);
  
        if (!validationResult.isValid) {
          return this.createErrorResponse(
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            validationResult.errors
          );
        }
  
        const usageResponse = await withToolTimeout(
          async () =>
            firewalla.getBandwidthUsage(
              periodValidation.sanitizedValue as string,
              limitValidation.sanitizedValue as number
            ),
          this.name
        );
  
        // Ensure we have results and validate count vs requested limit
        const results = usageResponse.results || [];
        const requestedLimit = limitValidation.sanitizedValue as number;
  
        // Note: if we get fewer results than requested, this may be due to
        // insufficient data rather than an error
  
        const startTime = Date.now();
  
        // Process bandwidth usage data
        const bandwidthData = SafeAccess.safeArrayMap(results, (item: any) => ({
          device_id: SafeAccess.getNestedValue(item, 'device_id', 'unknown'),
          device_name: SafeAccess.getNestedValue(
            item,
            'device_name',
            'Unknown Device'
          ),
          ip: SafeAccess.getNestedValue(item, 'ip', 'unknown'),
          bytes_uploaded: SafeAccess.getNestedValue(item, 'bytes_uploaded', 0),
          bytes_downloaded: SafeAccess.getNestedValue(
            item,
            'bytes_downloaded',
            0
          ),
          total_bytes: SafeAccess.getNestedValue(item, 'total_bytes', 0),
          total_mb:
            Math.round(
              ((SafeAccess.getNestedValue(item, 'total_bytes', 0) as number) /
                (1024 * 1024)) *
                100
            ) / 100,
          total_gb:
            Math.round(
              ((SafeAccess.getNestedValue(item, 'total_bytes', 0) as number) /
                (1024 * 1024 * 1024)) *
                100
            ) / 100,
        }));
  
        // Apply geographic enrichment for IP addresses
        const enrichedBandwidthData = await this.enrichGeoIfNeeded(
          bandwidthData,
          ['ip']
        );
  
        const unifiedResponseData = {
          period: periodValidation.sanitizedValue,
          top_devices: results.length,
          requested_limit: requestedLimit,
          bandwidth_usage: enrichedBandwidthData,
        };
  
        const executionTime = Date.now() - startTime;
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        // Handle timeout errors specifically
        if (error instanceof TimeoutError) {
          return createTimeoutErrorResponse(
            this.name,
            error.duration,
            10000 // Default timeout from timeout-manager
          );
        }
  
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        return this.createErrorResponse(
          `Failed to get bandwidth usage: ${errorMessage}`,
          ErrorType.API_ERROR,
          { originalError: errorMessage }
        );
      }
    }
  }

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

  Registration of the GetBandwidthUsageHandler in the central ToolRegistry during construction in registerHandlers() method.

  this.register(new GetBandwidthUsageHandler()); // wrapper around get_device_status

• src/server.ts:690-715 (schema)

  Tool schema definition exposed via MCP listTools request, defining input parameters, types, enum for period, limits, and required fields.

    name: 'get_bandwidth_usage',
    description:
      'Get top bandwidth consuming devices (convenience wrapper around get_device_status)',
    inputSchema: {
      type: 'object',
      properties: {
        period: {
          type: 'string',
          description: 'Time period for bandwidth calculation',
          enum: ['1h', '24h', '7d', '30d'],
        },
        limit: {
          type: 'number',
          description: 'Number of top devices to return',
          minimum: 1,
          maximum: 500,
          default: 10,
        },
        box: {
          type: 'string',
          description: 'Filter devices under a specific Firewalla box',
        },
      },
      required: ['period'],
    },
  },

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

  Import of GetBandwidthUsageHandler from './handlers/network.js' in registry.ts

  GetBandwidthUsageHandler,

• src/config/limits.ts:83-83 (helper)

  Configuration of rate limits and categorization for the get_bandwidth_usage tool in limits.ts, classifying it under moderate tools.

  get_bandwidth_usage: STANDARD_LIMITS.BANDWIDTH_ANALYSIS,