firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/security.ts:486-596 (handler)

  The GetSpecificAlarmHandler class defines the tool 'get_specific_alarm'. The execute method validates the alarm_id parameter, calls firewalla.getSpecificAlarm(alarmId), applies geographic enrichment, and returns a unified response.
  export class GetSpecificAlarmHandler extends BaseToolHandler { name = 'get_specific_alarm'; description = 'Get detailed information for a specific alarm by alarm ID. Requires alarm_id parameter obtained from get_active_alarms or search_alarms (aid field is automatically normalized). Features improved ID resolution that automatically tries multiple ID formats to handle API inconsistencies.'; category = 'security' as const; constructor() { super({ enableGeoEnrichment: true, enableFieldNormalization: true, additionalMeta: { data_source: 'specific_alarm', entity_type: 'security_alarm_detail', supports_geographic_enrichment: true, supports_field_normalization: true, standardization_version: '2.0.0', }, }); } async execute( args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { const alarmIdValidation = ParameterValidator.validateAlarmId( args?.alarm_id, 'alarm_id' ); if (!alarmIdValidation.isValid) { return this.createErrorResponse( 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, alarmIdValidation.errors ); } const rawAlarmId = alarmIdValidation.sanitizedValue as string; const alarmId = validateAlarmId(rawAlarmId); const response = await withToolTimeout( async () => firewalla.getSpecificAlarm(alarmId), 'get_specific_alarm' ); // Check if alarm exists if (!response || !response.results || response.results.length === 0) { return this.createErrorResponse( `Alarm with ID '${alarmId}' not found. Please verify the alarm ID is correct and the alarm has not been deleted.`, ErrorType.API_ERROR, { alarm_id: alarmId, suggestion: 'Use get_active_alarms to list available alarms and their IDs', } ); } const startTime = Date.now(); // Apply geographic enrichment to the alarm data const enrichedAlarm = await this.enrichGeoIfNeeded(response, [ 'src', 'dst', 'device.ip', 'remote.ip', ]); const unifiedResponseData = { alarm: enrichedAlarm, retrieved_at: getCurrentTimestamp(), }; const executionTime = Date.now() - startTime; return this.createUnifiedResponse(unifiedResponseData, { executionTimeMs: executionTime, }); } catch (error: unknown) { if (error instanceof TimeoutError) { return createTimeoutErrorResponse( 'get_specific_alarm', error.duration, 10000 ); } const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; // Check for specific API error patterns if (errorMessage.includes('404') || errorMessage.includes('not found')) { return this.createErrorResponse( `Alarm not found: ${args?.alarm_id}. The alarm may have been deleted or the ID may be incorrect.`, ErrorType.API_ERROR, { alarm_id: args?.alarm_id, suggestion: 'Use get_active_alarms to list available alarms and their IDs', } ); } return this.createErrorResponse( `Failed to get specific alarm: ${errorMessage}`, ErrorType.API_ERROR ); } } }
• src/tools/registry.ts:134-134 (registration)

  Registers the GetSpecificAlarmHandler instance in the central ToolRegistry during construction.
  this.register(new GetSpecificAlarmHandler());
• src/server.ts:133-146 (schema)

  Defines the input schema for the 'get_specific_alarm' tool exposed via ListToolsRequestSchema, specifying alarm_id as required string.
  name: 'get_specific_alarm', description: 'Get detailed information for a specific Firewalla alarm', inputSchema: { type: 'object', properties: { alarm_id: { type: 'string', description: 'Alarm ID (required for API call)', }, }, required: ['alarm_id'], }, },
• src/tools/registry.ts:37-37 (registration)

  Imports the GetSpecificAlarmHandler from './handlers/security.js' for use in registry.
  GetSpecificAlarmHandler,
• src/tools/handlers/security.ts:511-523 (schema)

  Runtime input validation for alarm_id using ParameterValidator.validateAlarmId in the handler's execute method.
  const alarmIdValidation = ParameterValidator.validateAlarmId( args?.alarm_id, 'alarm_id' ); if (!alarmIdValidation.isValid) { return this.createErrorResponse( 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, alarmIdValidation.errors ); }