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,