firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:26-140 (handler)

  GetBoxesHandler class that implements the core logic for the 'get_boxes' tool. Extends BaseToolHandler, defines name and description, and the execute method calls firewalla.getBoxes(groupId), normalizes data, enriches geo if needed, and returns unified response.
  export class GetBoxesHandler extends BaseToolHandler { name = 'get_boxes'; description = 'List all managed Firewalla boxes with status and configuration details.'; category = 'analytics' as const; constructor() { super({ enableGeoEnrichment: false, enableFieldNormalization: false, additionalMeta: { data_source: 'flow_trends', entity_type: 'historical_flow_data', supports_geographic_enrichment: false, supports_field_normalization: false, standardization_version: '2.0.0', }, }); } async execute( _args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { const groupIdValidation = ParameterValidator.validateOptionalString( _args?.group_id, 'group_id' ); if (!groupIdValidation.isValid) { return this.createErrorResponse( 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, groupIdValidation.errors ); } const groupId = groupIdValidation.sanitizedValue; const boxesResponse = await withToolTimeout( async () => firewalla.getBoxes(groupId as string), this.name ); const boxResults = SafeAccess.safeArrayAccess( boxesResponse.results, (arr: any[]) => arr, [] ) as any[]; const normalizedBoxes = batchNormalize(boxResults, { name: (v: any) => sanitizeFieldValue(v, 'Unknown Box').value, model: (v: any) => sanitizeFieldValue(v, 'unknown').value, mode: (v: any) => sanitizeFieldValue(v, 'unknown').value, version: (v: any) => sanitizeFieldValue(v, 'unknown').value, group: (v: any) => (v ? normalizeUnknownFields(v) : null), location: (v: any) => sanitizeFieldValue(v, 'unknown').value, online: (v: any) => Boolean(v), gid: (v: any) => sanitizeFieldValue(v, 'unknown').value, license: (v: any) => sanitizeFieldValue(v, 'unknown').value, publicIP: (v: any) => sanitizeFieldValue(v, 'unknown').value, deviceCount: (v: any) => Number(v) || 0, ruleCount: (v: any) => Number(v) || 0, alarmCount: (v: any) => Number(v) || 0, }); const startTime = Date.now(); const boxData = normalizedBoxes.map((box: any) => { const timestampNormalized = normalizeTimestamps(box); const finalBox = timestampNormalized.data; return { gid: SafeAccess.getNestedValue(finalBox, 'gid', 'unknown'), name: finalBox.name, model: finalBox.model, mode: finalBox.mode, version: finalBox.version, online: SafeAccess.getNestedValue(finalBox, 'online', false), last_seen: SafeAccess.getNestedValue(finalBox, 'lastSeen', 0), license: SafeAccess.getNestedValue(finalBox, 'license', null), public_ip: finalBox.publicIP || finalBox.public_ip || 'unknown', group: finalBox.group, location: finalBox.location, device_count: SafeAccess.getNestedValue(finalBox, 'deviceCount', 0), rule_count: SafeAccess.getNestedValue(finalBox, 'ruleCount', 0), alarm_count: SafeAccess.getNestedValue(finalBox, 'alarmCount', 0), }; }); // Apply geographic enrichment for public IP addresses const enrichedBoxData = await this.enrichGeoIfNeeded(boxData, [ 'public_ip', ]); const unifiedResponseData = { total_boxes: normalizedBoxes.length, boxes: enrichedBoxData, }; 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 boxes: ${errorMessage}`, ErrorType.API_ERROR ); } }
• src/tools/registry.ts:160-176 (registration)

  ToolRegistry registers the GetBoxesHandler instance for the 'get_boxes' tool in its constructor's registerHandlers method.
  // Analytics tools (6 handlers) this.register(new GetBoxesHandler()); this.register(new GetSimpleStatisticsHandler()); this.register(new GetStatisticsByRegionHandler()); this.register(new GetStatisticsByBoxHandler()); this.register(new GetRecentFlowActivityHandler()); this.register(new GetFlowInsightsHandler()); this.register(new GetAlarmTrendsHandler()); this.register(new GetRuleTrendsHandler()); // 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/server.ts:525-537 (schema)

  MCP tool schema definition for 'get_boxes' in the ListToolsRequestSchema handler, specifying optional 'group' parameter.
  name: 'get_boxes', description: 'Retrieve list of Firewalla boxes', inputSchema: { type: 'object', properties: { group: { type: 'string', description: 'Get boxes within a specific group (requires group ID)', }, }, required: [], },