firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:320-515 (handler)

  The PauseRuleHandler class that implements the core logic of the 'pause_rule' tool. Defines the tool name, description, and category. The execute method handles parameter validation (rule_id required, duration optional default 60), checks if rule exists and is not already paused using checkRuleStatus helper, calls firewalla.pauseRule(ruleId, duration), and returns unified response or detailed error.

  export class PauseRuleHandler extends BaseToolHandler {
    name = 'pause_rule';
    description =
      'Temporarily disable a specific firewall rule. Requires rule_id parameter. Optional duration parameter (default 60 minutes).';
    category = 'rule' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // No IP fields in rule operations
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'rule_operations',
          entity_type: 'rule_pause_operation',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        // Parameter validation with enhanced rule ID format checking
        const ruleIdValidation = ParameterValidator.validateRuleId(
          args?.rule_id,
          'rule_id'
        );
        const durationValidation = ParameterValidator.validateNumber(
          args?.duration,
          'duration',
          {
            defaultValue: 60,
            ...VALIDATION_CONFIG.DURATION_MINUTES,
          }
        );
  
        const validationResult = ParameterValidator.combineValidationResults([
          ruleIdValidation,
          durationValidation,
        ]);
  
        if (!validationResult.isValid) {
          return createErrorResponse(
            this.name,
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            validationResult.errors
          );
        }
  
        const ruleId = ruleIdValidation.sanitizedValue as string;
        const duration = durationValidation.sanitizedValue as number;
  
        // Check rule status before attempting to pause it
        const statusCheck = await checkRuleStatus(ruleId, this.name, firewalla);
  
        if (!statusCheck.exists) {
          return statusCheck.errorResponse!;
        }
  
        // Prevent redundant pause operations
        if (statusCheck.isPaused) {
          const resumeInfo = statusCheck.resumeAt
            ? ` (scheduled to resume at ${statusCheck.resumeAt})`
            : '';
  
          return createErrorResponse(
            this.name,
            `Rule is already paused${resumeInfo}`,
            ErrorType.API_ERROR,
            {
              rule_id: ruleId,
              current_status: statusCheck.status,
              already_paused: true,
              resume_at: statusCheck.resumeAt,
              requested_duration_minutes: duration,
            },
            [
              'Rule is already in a paused state',
              statusCheck.resumeAt
                ? `Rule will automatically resume at ${statusCheck.resumeAt}`
                : 'Use resume_rule to manually reactivate the rule',
              'Use get_network_rules to check current rule status',
              'If you want to extend the pause duration, resume first then pause again',
            ]
          );
        }
  
        // Warn if rule is not currently active
        if (!statusCheck.isActive) {
          logger.warn(
            `Rule ${ruleId} has status '${statusCheck.status}' - pausing may not have the expected effect`,
            {
              tool: 'pause_rule',
              rule_id: ruleId,
              current_status: statusCheck.status,
              warning: 'rule_not_active',
            }
          );
        }
  
        const result = await withToolTimeout(
          async () => firewalla.pauseRule(ruleId, duration),
          this.name
        );
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          success: SafeAccess.getNestedValue(result as any, 'success', false),
          message: SafeAccess.getNestedValue(
            result,
            'message',
            'Rule pause completed'
          ),
          rule_id: ruleId,
          duration_minutes: duration,
          action: 'pause_rule',
        };
  
        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';
  
        // Provide enhanced error context based on common failure scenarios
        let errorType = ErrorType.API_ERROR;
        const suggestions: string[] = [];
        const context: Record<string, any> = {
          rule_id: args?.rule_id,
          duration: args?.duration || 60,
          operation: 'pause_rule',
        };
  
        // Analyze error message for specific guidance
        if (errorMessage.includes('not found') || errorMessage.includes('404')) {
          errorType = ErrorType.API_ERROR;
          suggestions.push(
            'Verify the rule_id exists by searching rules first: search_rules query:"id:your_rule_id"',
            'Check if the rule was recently deleted or modified',
            'Ensure you have permission to access this rule'
          );
        } else if (
          errorMessage.includes('permission') ||
          errorMessage.includes('401') ||
          errorMessage.includes('403')
        ) {
          errorType = ErrorType.AUTHENTICATION_ERROR;
          suggestions.push(
            'Verify your Firewalla MSP API credentials are valid',
            'Check if your API token has rule management permissions',
            'Ensure the rule belongs to a box you have access to'
          );
        } else if (
          errorMessage.includes('already paused') ||
          errorMessage.includes('inactive')
        ) {
          errorType = ErrorType.API_ERROR;
          suggestions.push(
            'Rule may already be paused - check rule status first',
            'Use resume_rule if the rule needs to be reactivated',
            'Check rule status with get_network_rules to verify current state'
          );
        } else {
          suggestions.push(
            'Verify network connectivity to Firewalla API',
            'Check if the Firewalla box is online and accessible',
            'Try with a different rule_id to test functionality',
            'See the Error Handling Guide: /docs/error-handling-guide.md'
          );
        }
  
        return createErrorResponse(
          this.name,
          `Failed to pause rule: ${errorMessage}`,
          errorType,
          context,
          suggestions
        );
      }
    }

• src/server.ts:247-271 (schema)

  Explicit input schema definition for the pause_rule tool in the MCP server configuration, specifying required parameters (rule_id, box) and optional duration with validation constraints.

  name: 'pause_rule',
  description:
    'Temporarily disable an active firewall rule for a specified duration',
  inputSchema: {
    type: 'object',
    properties: {
      rule_id: {
        type: 'string',
        description: 'Rule ID to pause',
      },
      duration: {
        type: 'number',
        description:
          'Duration in minutes to pause the rule (optional, default: 60, range: 1-1440)',
        minimum: 1,
        maximum: 1440,
        default: 60,
      },
      box: {
        type: 'string',
        description: 'Box GID for context (required by API)',
      },
    },
    required: ['rule_id', 'box'],
  },

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

  Registration of the PauseRuleHandler instance in the ToolRegistry during automatic handler registration in the registerHandlers method.

  // Rule tools (8 handlers)
  this.register(new GetNetworkRulesHandler());
  this.register(new PauseRuleHandler());
  this.register(new ResumeRuleHandler());
  this.register(new GetTargetListsHandler());
  this.register(new GetSpecificTargetListHandler());
  this.register(new CreateTargetListHandler());
  this.register(new UpdateTargetListHandler());
  this.register(new DeleteTargetListHandler());

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

  Import statement for PauseRuleHandler from the rules handlers file, enabling its use in the registry.

  import {
    GetNetworkRulesHandler,
    PauseRuleHandler,
    ResumeRuleHandler,
    GetTargetListsHandler,
    GetSpecificTargetListHandler,
    CreateTargetListHandler,
    UpdateTargetListHandler,
    DeleteTargetListHandler,
    GetNetworkRulesSummaryHandler,
  } from './handlers/rules.js';

• src/tools/handlers/rules.ts:48-131 (helper)

  Helper function used by pause_rule (and resume_rule) to check rule status before operation, preventing redundant pauses and providing detailed error responses.

  async function checkRuleStatus(
    ruleId: string,
    toolName: string,
    firewalla: FirewallaClient
  ): Promise<RuleStatusInfo> {
    try {
      // First check if the rule exists
      const existenceCheck = await validateRuleExists(
        ruleId,
        toolName,
        firewalla
      );
      if (!existenceCheck.exists) {
        return {
          exists: false,
          status: 'not_found',
          isPaused: false,
          isActive: false,
          errorResponse: existenceCheck.errorResponse,
        };
      }
  
      // Get the specific rule details to check its status
      const rulesResponse = await firewalla.getNetworkRules(`id:${ruleId}`, 1);
      const rules = SafeAccess.getNestedValue(
        rulesResponse,
        'results',
        []
      ) as any[];
  
      if (rules.length === 0) {
        return {
          exists: false,
          status: 'not_found',
          isPaused: false,
          isActive: false,
          errorResponse: createErrorResponse(
            toolName,
            'Rule not found in current rule set',
            ErrorType.API_ERROR,
            { rule_id: ruleId }
          ),
        };
      }
  
      const rule = rules[0];
      const status = SafeAccess.getNestedValue(
        rule,
        'status',
        'unknown'
      ) as string;
      const resumeTs = SafeAccess.getNestedValue(rule, 'resumeTs', undefined) as
        | number
        | undefined;
  
      // Determine if rule is paused or active
      const isPaused: boolean =
        status === 'paused' ||
        status === 'disabled' ||
        Boolean(resumeTs && resumeTs > Date.now() / 1000);
      const isActive: boolean = status === 'active' || status === 'enabled';
  
      return {
        exists: true,
        status,
        isPaused,
        isActive,
        resumeAt: resumeTs ? new Date(resumeTs * 1000).toISOString() : undefined,
      };
    } catch (error) {
      return {
        exists: false,
        status: 'error',
        isPaused: false,
        isActive: false,
        errorResponse: createErrorResponse(
          toolName,
          `Failed to check rule status: ${error instanceof Error ? error.message : 'Unknown error'}`,
          ErrorType.API_ERROR,
          { rule_id: ruleId }
        ),
      };
    }
  }