firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:772-1027 (handler)

  The GetNetworkRulesSummaryHandler class that executes the core tool logic: validates parameters (limit, rule_type, active_only), fetches network rules from Firewalla API, computes comprehensive statistics (breakdown by action/direction/status/target_type, hit statistics, age statistics), and returns structured summary data.
  export class GetNetworkRulesSummaryHandler extends BaseToolHandler { name = 'get_network_rules_summary'; description = 'Get overview statistics and counts of network rules by category. Requires limit parameter. Data cached for 10 minutes for performance.'; category = 'rule' as const; constructor() { super({ enableGeoEnrichment: false, // No IP fields in rule summary statistics enableFieldNormalization: true, additionalMeta: { data_source: 'rule_summary', entity_type: 'rule_statistics', supports_geographic_enrichment: false, supports_field_normalization: true, standardization_version: '2.0.0', }, }); } async execute( args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { // Parameter validation with standardized limits const limitValidation = ParameterValidator.validateNumber( args?.limit, 'limit', { required: false, defaultValue: 200, ...getLimitValidationConfig(this.name), } ); const ruleTypeValidation = ParameterValidator.validateEnum( args?.rule_type, 'rule_type', ['block', 'allow', 'timelimit', 'all'], false, 'all' ); const activeOnlyValidation = ParameterValidator.validateBoolean( args?.active_only, 'active_only', true ); const validationResult = ParameterValidator.combineValidationResults([ limitValidation, ruleTypeValidation, activeOnlyValidation, ]); if (!validationResult.isValid) { return createErrorResponse( this.name, 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, validationResult.errors ); } const limit = limitValidation.sanitizedValue! as number; const ruleType = ruleTypeValidation.sanitizedValue!; const activeOnly = activeOnlyValidation.sanitizedValue!; // Statistical Analysis Buffer Strategy: User-controlled limit for rule analysis // // Problem: Rule summary analysis requires processing potentially thousands // of rules to generate meaningful statistics. Without limits, this could: // - Consume excessive memory for large rule sets (10k+ rules) // - Cause slow API responses // - Risk timeout failures on resource-constrained systems // // Solution: Use user-specified limit (validated 1-10000) for statistical analysis. // This provides: // - User control over memory usage and response time // - Predictable memory usage based on user's choice // - Consistent with other rule tools' validation patterns // // The limit is validated to ensure reasonable bounds (1-10000) which allows // both lightweight queries and comprehensive enterprise-level analysis. const allRulesResponse = await withToolTimeout( async () => firewalla.getNetworkRules(undefined, limit), this.name ); const allRules = SafeAccess.getNestedValue( allRulesResponse, 'results', [] ) as any[]; // Group rules by various categories for overview const rulesByAction = allRules.reduce( (acc: Record<string, number>, rule: any) => { const action = SafeAccess.getNestedValue( rule, 'action', 'unknown' ) as string; acc[action] = (acc[action] || 0) + 1; return acc; }, {} ); const rulesByDirection = allRules.reduce( (acc: Record<string, number>, rule: any) => { const direction = SafeAccess.getNestedValue( rule, 'direction', 'unknown' ) as string; acc[direction] = (acc[direction] || 0) + 1; return acc; }, {} ); const rulesByStatus = allRules.reduce( (acc: Record<string, number>, rule: any) => { const status = SafeAccess.getNestedValue( rule, 'status', 'active' ) as string; acc[status] = (acc[status] || 0) + 1; return acc; }, {} ); const rulesByTargetType = allRules.reduce( (acc: Record<string, number>, rule: any) => { const targetType = SafeAccess.getNestedValue( rule, 'target.type', 'unknown' ) as string; acc[targetType] = (acc[targetType] || 0) + 1; return acc; }, {} ); // Calculate hit statistics const rulesWithHits = allRules.filter((rule: any) => { const hitCount = SafeAccess.getNestedValue( rule, 'hit.count', 0 ) as number; return hitCount > 0; }); const totalHits = allRules.reduce( (sum: number, rule: any) => sum + (SafeAccess.getNestedValue(rule, 'hit.count', 0) as number), 0 ); const avgHitsPerRule = allRules.length > 0 ? Math.round((totalHits / allRules.length) * 100) / 100 : 0; // Find most recent rule activity let mostRecentRuleTs: number | undefined = undefined; let oldestRuleTs: number | undefined = undefined; if (allRules.length > 0) { const validTimestamps = allRules .map((rule: any) => { const ts = SafeAccess.getNestedValue(rule, 'ts', 0) as number; const updateTs = SafeAccess.getNestedValue( rule, 'updateTs', 0 ) as number; return Math.max(ts, updateTs); }) .filter((ts: number) => ts > 0); const creationTimestamps = allRules .map( (rule: any) => SafeAccess.getNestedValue(rule, 'ts', 0) as number ) .filter((ts: number) => ts > 0); if (validTimestamps.length > 0) { mostRecentRuleTs = Math.max(...validTimestamps); } if (creationTimestamps.length > 0) { oldestRuleTs = Math.min(...creationTimestamps); } } const startTime = Date.now(); const unifiedResponseData = { total_rules: allRules.length, limit_applied: limit, summary_timestamp: getCurrentTimestamp(), breakdown: { by_action: rulesByAction, by_direction: rulesByDirection, by_status: rulesByStatus, by_target_type: rulesByTargetType, }, hit_statistics: { total_hits: totalHits, rules_with_hits: rulesWithHits.length, rules_with_no_hits: allRules.length - rulesWithHits.length, average_hits_per_rule: avgHitsPerRule, hit_rate_percentage: allRules.length > 0 ? Math.round((rulesWithHits.length / allRules.length) * 100) : 0, }, age_statistics: { most_recent_activity: safeUnixToISOString( mostRecentRuleTs, undefined ), oldest_rule_created: safeUnixToISOString(oldestRuleTs, undefined), has_timestamp_data: mostRecentRuleTs !== undefined || oldestRuleTs !== undefined, }, filters_applied: { rule_type: ruleType || 'all', active_only: activeOnly, }, }; const executionTime = Date.now() - startTime; return this.createUnifiedResponse(unifiedResponseData, { executionTimeMs: executionTime, }); } catch (error: unknown) { if (error instanceof TimeoutError) { return createTimeoutErrorResponse( this.name, error.duration, 10000 // Default timeout ); } const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; return this.createErrorResponse( `Failed to get network rules summary: ${errorMessage}` ); } } }
• src/tools/registry.ts:170-176 (registration)

  Registration of the GetNetworkRulesSummaryHandler in the ToolRegistry's registerHandlers() method, as one of the convenience wrapper tools.
  // Convenience Wrappers (5 handlers) this.register(new GetBandwidthUsageHandler()); // wrapper around get_device_status this.register(new GetOfflineDevicesHandler()); // wrapper around get_device_status this.register(new SearchDevicesHandler()); // wrapper with client-side filtering this.register(new SearchTargetListsHandler()); // wrapper with client-side filtering this.register(new GetNetworkRulesSummaryHandler()); // wrapper around get_network_rules }
• src/config/limits.ts:88-88 (schema)

  Limit configuration for the get_network_rules_summary tool in the centralized limits system, setting max limit to STANDARD_LIMITS.RULES_SUMMARY (2000). Used by getLimitValidationConfig in the handler for parameter validation.
  get_network_rules_summary: STANDARD_LIMITS.RULES_SUMMARY,
• src/tools/registry.ts:55-55 (registration)

  Import statement for GetNetworkRulesSummaryHandler from ./handlers/rules.js (resolves to rules.ts).
  GetNetworkRulesSummaryHandler,
• src/tools/index.ts:152-152 (registration)

  Documentation listing get_network_rules_summary as one of the registered Rule tools in the MCP setup.
  * get_network_rules_summary, get_most_active_rules, get_recent_rules