firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:1634-1749 (handler)

  UpdateTargetListHandler class: defines the tool name, description, category, and implements the execute method which validates parameters (required 'id', optional 'name', 'targets', 'category', 'notes'), constructs updateData from valid params, calls firewalla.updateTargetList(id, updateData), and returns unified response or handles errors.

  export class UpdateTargetListHandler extends BaseToolHandler {
    name = 'update_target_list';
    description = 'Update an existing target list in Firewalla';
    category = 'rule' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false,
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'target_lists',
          entity_type: 'target_list_update',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const idValidation = ParameterValidator.validateRequiredString(
          args?.id,
          'id'
        );
        const nameValidation = ParameterValidator.validateOptionalString(
          args?.name,
          'name'
        );
        const targetsValidation = ParameterValidator.validateArray(
          args?.targets,
          'targets',
          { required: false }
        );
        const categoryValidation = ParameterValidator.validateEnum(
          args?.category,
          'category',
          [
            'ad',
            'edu',
            'games',
            'gamble',
            'intel',
            'p2p',
            'porn',
            'private',
            'social',
            'shopping',
            'video',
            'vpn',
          ],
          false
        );
        const notesValidation = ParameterValidator.validateOptionalString(
          args?.notes,
          'notes'
        );
  
        const validationResult = ParameterValidator.combineValidationResults([
          idValidation,
          nameValidation,
          targetsValidation,
          categoryValidation,
          notesValidation,
        ]);
  
        if (!validationResult.isValid) {
          return createErrorResponse(
            this.name,
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            validationResult.errors
          );
        }
  
        const id = idValidation.sanitizedValue as string;
        const updateData: Record<string, unknown> = {};
  
        if (nameValidation.sanitizedValue !== undefined) {
          updateData.name = nameValidation.sanitizedValue;
        }
        if (targetsValidation.sanitizedValue !== undefined) {
          updateData.targets = targetsValidation.sanitizedValue;
        }
        if (categoryValidation.sanitizedValue !== undefined) {
          updateData.category = categoryValidation.sanitizedValue;
        }
        if (notesValidation.sanitizedValue !== undefined) {
          updateData.notes = notesValidation.sanitizedValue;
        }
  
        const response = await withToolTimeout(
          async () => firewalla.updateTargetList(id, updateData),
          this.name
        );
  
        return this.createUnifiedResponse(response);
      } catch (error: unknown) {
        if (error instanceof TimeoutError) {
          return createTimeoutErrorResponse(this.name, error.duration, 10000);
        }
  
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        return createErrorResponse(
          this.name,
          `Failed to update target list: ${errorMessage}`,
          ErrorType.API_ERROR,
          { id: args?.id }
        );
      }
    }

• src/server.ts:373-418 (schema)

  MCP tool registration in server.ts defines the inputSchema for update_target_list: required 'id' string, optional 'name' (maxLength 24), 'targets' array of strings, 'category' enum of content types, 'notes' string.

  name: 'update_target_list',
  description: 'Update an existing target list',
  inputSchema: {
    type: 'object',
    properties: {
      id: {
        type: 'string',
        description: 'Target list ID (required)',
      },
      name: {
        type: 'string',
        description: 'Updated target list name (max 24 chars)',
        maxLength: 24,
      },
      targets: {
        type: 'array',
        items: {
          type: 'string',
        },
        description: 'Updated array of domains, IPs, or CIDR ranges',
      },
      category: {
        type: 'string',
        enum: [
          'ad',
          'edu',
          'games',
          'gamble',
          'intel',
          'p2p',
          'porn',
          'private',
          'social',
          'shopping',
          'video',
          'vpn',
        ],
        description: 'Updated content category',
      },
      notes: {
        type: 'string',
        description: 'Updated description',
      },
    },
    required: ['id'],
  },

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

  ToolRegistry registers the UpdateTargetListHandler instance by name 'update_target_list' during initialization in registerHandlers() method.

  this.register(new UpdateTargetListHandler());