firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:133-318 (handler)

  Core handler implementation: validates parameters (limit, query), calls Firewalla API getNetworkRules, applies optimization if summary_only, formats unified response with timestamps and safe access.

  export class GetNetworkRulesHandler extends BaseToolHandler {
    name = 'get_network_rules';
    description =
      'Retrieve firewall rules and conditions including target domains, actions, and status. Requires limit parameter. Data is cached for 10 minutes for performance.';
    category = 'rule' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // No IP fields in network rules
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'network_rules',
          entity_type: 'firewall_rules',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          supports_pagination: true,
          supports_filtering: 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),
          }
        );
  
        if (!limitValidation.isValid) {
          return createErrorResponse(
            this.name,
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            limitValidation.errors
          );
        }
  
        const query = args?.query;
        const summaryOnly = (args?.summary_only as boolean) ?? false;
        const limit = limitValidation.sanitizedValue! as number;
  
        const response = await withToolTimeout(
          async () => firewalla.getNetworkRules(query, limit),
          this.name
        );
  
        // Apply additional optimization if summary mode requested
        let optimizedResponse: any = response;
        if (summaryOnly) {
          optimizedResponse = optimizeRuleResponse(response as any, {
            ...DEFAULT_OPTIMIZATION_CONFIG,
            summaryMode: {
              maxItems: limit,
              includeFields: [
                'id',
                'action',
                'target',
                'direction',
                'status',
                'hit',
              ],
              excludeFields: ['notes', 'schedule', 'timeUsage', 'scope'],
            },
          });
        }
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          count: SafeAccess.getNestedValue(optimizedResponse, 'count', 0),
          summary_mode: summaryOnly,
          limit_applied: summaryOnly ? limit : undefined,
          rules: summaryOnly
            ? optimizedResponse.results
            : SafeAccess.safeArrayMap(
                (response.results as any[]).slice(0, limit),
                (rule: any) => ({
                  id: SafeAccess.getNestedValue(rule, 'id', 'unknown'),
                  action: SafeAccess.getNestedValue(rule, 'action', 'unknown'),
                  target: rule.target
                    ? {
                        type: SafeAccess.getNestedValue(
                          rule.target,
                          'type',
                          'unknown'
                        ),
                        value: SafeAccess.getNestedValue(
                          rule.target,
                          'value',
                          'unknown'
                        ),
                        ...(rule.target?.dnsOnly && {
                          dnsOnly: rule.target.dnsOnly,
                        }),
                        ...(rule.target?.port && { port: rule.target.port }),
                      }
                    : { type: 'unknown', value: 'unknown' },
                  direction: SafeAccess.getNestedValue(
                    rule,
                    'direction',
                    'unknown'
                  ),
                  gid: SafeAccess.getNestedValue(rule, 'gid', 'unknown'),
                  group: SafeAccess.getNestedValue(rule, 'group', undefined),
                  scope: SafeAccess.getNestedValue(rule, 'scope', undefined),
                  notes: SafeAccess.getNestedValue(rule, 'notes', ''),
                  status: SafeAccess.getNestedValue(rule, 'status', 'unknown'),
                  hit: SafeAccess.getNestedValue(rule, 'hit', undefined),
                  schedule: SafeAccess.getNestedValue(
                    rule,
                    'schedule',
                    undefined
                  ),
                  timeUsage: SafeAccess.getNestedValue(
                    rule,
                    'timeUsage',
                    undefined
                  ),
                  protocol: SafeAccess.getNestedValue(
                    rule,
                    'protocol',
                    undefined
                  ),
                  created_at: safeUnixToISOString(
                    SafeAccess.getNestedValue(rule, 'ts', undefined) as
                      | number
                      | undefined,
                    undefined
                  ),
                  updated_at: safeUnixToISOString(
                    SafeAccess.getNestedValue(rule, 'updateTs', undefined) as
                      | number
                      | undefined,
                    undefined
                  ),
                  resume_at: safeUnixToISOString(
                    SafeAccess.getNestedValue(rule, 'resumeTs', undefined) as
                      | number
                      | undefined,
                    undefined
                  ),
                })
              ),
          next_cursor: SafeAccess.getNestedValue(
            summaryOnly ? optimizedResponse : response,
            'next_cursor',
            undefined
          ),
          ...(summaryOnly &&
            optimizedResponse.pagination_note && {
              pagination_note: optimizedResponse.pagination_note,
            }),
        };
  
        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: ${errorMessage}`
        );
      }
    }
  }

• src/server.ts:227-244 (schema)

  MCP protocol input schema definition for get_network_rules tool, specifying required 'limit' (1-1000) and optional 'query' parameters.

  name: 'get_network_rules',
  description: 'Retrieve firewall rules and conditions',
  inputSchema: {
    type: 'object',
    properties: {
      limit: {
        type: 'number',
        description: 'Maximum number of rules to return (required)',
        minimum: 1,
        maximum: 1000,
      },
      query: {
        type: 'string',
        description: 'Search conditions for filtering rules',
      },
    },
    required: ['limit'],
  },

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

  Registers the GetNetworkRulesHandler instance in the central ToolRegistry during automatic handler registration.

  this.register(new GetNetworkRulesHandler());

• src/server.ts:833-833 (registration)

  Calls setupTools which uses the ToolRegistry to register all tool handlers (including get_network_rules) with the MCP Server.

  setupTools(this.server, this.firewalla);

• src/config/limits.ts:86-86 (schema)

  Defines validation limits configuration for get_network_rules tool using STANDARD_LIMITS.BASIC_QUERY.

  get_network_rules: STANDARD_LIMITS.BASIC_QUERY,