firewalla-mcp-server

Instructions

Implementation Reference

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

  GetSpecificAlarmHandler class: core implementation executing the tool logic. Validates alarm_id, calls firewalla.getSpecificAlarm(alarmId), applies geo-enrichment, handles errors including not found, formats 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)

  Tool registration: GetSpecificAlarmHandler is instantiated and registered in the ToolRegistry.

  this.register(new GetSpecificAlarmHandler());

• src/server.ts:132-146 (schema)

  MCP input schema definition for get_specific_alarm tool in ListTools response.

  {
    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'],
    },
  },