firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:277-401 (handler)

  The GetStatisticsByRegionHandler class implements the core logic for the 'get_statistics_by_region' tool. It extends BaseToolHandler, calls firewalla.getStatisticsByRegion(), processes regional flow statistics, calculates percentages and top regions, and returns a standardized response.

  export class GetStatisticsByRegionHandler extends BaseToolHandler {
    name = 'get_statistics_by_region';
    description =
      'Get flow statistics grouped by country/region for geographic analysis. No required parameters. Data cached for 1 hour for performance.';
    category = 'analytics' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // Already contains geographic data
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'regional_statistics',
          entity_type: 'geographic_flow_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.getStatisticsByRegion(),
          this.name
        );
  
        // Validate response structure with comprehensive null/undefined guards
        if (
          !stats ||
          !SafeAccess.getNestedValue(stats, 'results') ||
          !Array.isArray(stats.results)
        ) {
          return this.createSuccessResponse({
            total_regions: 0,
            regional_statistics: [],
            top_regions: [],
            error:
              'No regional statistics available - API response missing results array',
            debug_info: {
              stats_exists: !!stats,
              results_exists: !!stats?.results,
              results_is_array: !!stats?.results && Array.isArray(stats.results),
              actual_structure: stats ? Object.keys(stats) : 'null',
            },
          });
        }
  
        // Calculate total flow count for percentage calculations
        const totalFlowCount = stats.results.reduce((sum: number, stat: any) => {
          return (
            sum +
            (typeof SafeAccess.getNestedValue(stat, 'value') === 'number'
              ? stat.value
              : 0)
          );
        }, 0);
  
        // Process regional statistics with defensive programming
        const regionalStatistics = SafeAccess.safeArrayFilter(
          stats.results,
          (stat: any): stat is any =>
            stat &&
            typeof SafeAccess.getNestedValue(stat, 'value') === 'number' &&
            !!SafeAccess.getNestedValue(stat, 'meta')
        )
          .map((stat: any) => ({
            country_code: SafeAccess.getNestedValue(stat, 'meta.code', 'unknown'),
            flow_count: SafeAccess.getNestedValue(stat, 'value', 0),
            percentage:
              totalFlowCount > 0
                ? Math.round(
                    ((SafeAccess.getNestedValue(stat, 'value', 0) as number) /
                      totalFlowCount) *
                      100
                  )
                : 0,
          }))
          .sort((a: any, b: any) => b.flow_count - a.flow_count);
  
        // Get top 5 regions with defensive programming
        const topRegions = SafeAccess.safeArrayFilter(
          stats.results,
          (stat: any): stat is any =>
            stat &&
            typeof SafeAccess.getNestedValue(stat, 'value') === 'number' &&
            SafeAccess.getNestedValue(stat, 'meta')
        )
          .sort(
            (a: any, b: any) =>
              (SafeAccess.getNestedValue(b, 'value', 0) as number) -
              (SafeAccess.getNestedValue(a, 'value', 0) as number)
          )
          .slice(0, 5)
          .map((stat: any) => ({
            country_code: SafeAccess.getNestedValue(stat, 'meta.code', 'unknown'),
            flow_count: SafeAccess.getNestedValue(stat, 'value', 0),
          }));
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          total_regions: stats.results.length,
          regional_statistics: regionalStatistics,
          top_regions: topRegions,
          total_flow_count: totalFlowCount,
        };
  
        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 statistics by region: ${errorMessage}`,
          ErrorType.API_ERROR
        );
      }
    }
  }

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

  The tool handler is registered in the ToolRegistry by instantiating GetStatisticsByRegionHandler and calling register() during registry construction.

  this.register(new GetStatisticsByRegionHandler());

• src/server.ts:554-573 (schema)

  The MCP tool schema definition including inputSchema with optional 'group' and 'limit' parameters is hardcoded in the ListToolsRequestHandler response.

  name: 'get_statistics_by_region',
  description:
    'Retrieve statistics by region (top regions by blocked flows)',
  inputSchema: {
    type: 'object',
    properties: {
      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: [],
  },

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

  Import of GetStatisticsByRegionHandler from './handlers/analytics.js' in the ToolRegistry module.

  GetStatisticsByRegionHandler,