firewalla-mcp-server

Instructions

Implementation Reference

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

  Core handler implementation. Validates inputs (limit up to 2000, rule_type, active_only), calls firewalla.getNetworkRules(), processes rules into summary statistics (counts by action/direction/status/target_type, hit stats, age stats), returns structured ToolResponse.
  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/server.ts:807-827 (schema)

  MCP protocol input schema definition for the tool, specifying parameters active_only (boolean, default true) and rule_type (string). Used in listTools response.
  { name: 'get_network_rules_summary', description: 'Get overview statistics and counts of network rules by category (convenience wrapper)', inputSchema: { type: 'object', properties: { active_only: { type: 'boolean', description: 'Only include active rules in summary (default: true)', default: true, }, rule_type: { type: 'string', description: 'Filter by rule type', }, }, required: [], }, },
• src/tools/registry.ts:175-175 (registration)

  Tool handler registration in ToolRegistry constructor. Instantiates and registers GetNetworkRulesSummaryHandler.
  this.register(new GetNetworkRulesSummaryHandler()); // wrapper around get_network_rules
• src/config/limits.ts:88-88 (schema)

  Parameter limit configuration (max 2000 rules for analysis) used by getLimitValidationConfig in the handler for input validation.
  get_network_rules_summary: STANDARD_LIMITS.RULES_SUMMARY,
• src/tools/registry.ts:55-56 (registration)

  Import of the GetNetworkRulesSummaryHandler class from rules.ts, enabling its registration.
  GetNetworkRulesSummaryHandler, } from './handlers/rules.js';