firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:1516-1629 (handler)

  Core handler implementation for the 'create_target_list' tool. Validates inputs, calls Firewalla API, handles errors and returns standardized response.

  export class CreateTargetListHandler extends BaseToolHandler {
    name = 'create_target_list';
    description = 'Create a new target list in Firewalla';
    category = 'rule' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false,
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'target_lists',
          entity_type: 'target_list_creation',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const nameValidation = ParameterValidator.validateRequiredString(
          args?.name,
          'name'
        );
        const ownerValidation = ParameterValidator.validateRequiredString(
          args?.owner,
          'owner'
        );
        const targetsValidation = ParameterValidator.validateArray(
          args?.targets,
          'targets',
          { required: true }
        );
        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([
          nameValidation,
          ownerValidation,
          targetsValidation,
          categoryValidation,
          notesValidation,
        ]);
  
        if (!validationResult.isValid) {
          return createErrorResponse(
            this.name,
            'Parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            validationResult.errors
          );
        }
  
        const targetListData: any = {
          name: nameValidation.sanitizedValue,
          owner: ownerValidation.sanitizedValue,
          targets: targetsValidation.sanitizedValue,
        };
  
        if (categoryValidation.sanitizedValue) {
          targetListData.category = categoryValidation.sanitizedValue;
        }
        if (notesValidation.sanitizedValue) {
          targetListData.notes = notesValidation.sanitizedValue;
        }
  
        const response = await withToolTimeout(
          async () => firewalla.createTargetList(targetListData),
          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 create target list: ${errorMessage}`,
          ErrorType.API_ERROR,
          { name: args?.name, owner: args?.owner }
        );
      }
    }
  }

• src/server.ts:323-371 (schema)

  MCP protocol input schema definition for the create_target_list tool, used in listTools response. Specifies properties, types, descriptions, enums, and required fields.

  {
    name: 'create_target_list',
    description: 'Create a new target list',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Target list name (required, max 24 chars)',
          maxLength: 24,
        },
        owner: {
          type: 'string',
          description: 'Owner: "global" or box GID (required)',
        },
        targets: {
          type: 'array',
          items: {
            type: 'string',
          },
          description:
            'Array of domains, IPs, or CIDR ranges (required)',
        },
        category: {
          type: 'string',
          enum: [
            'ad',
            'edu',
            'games',
            'gamble',
            'intel',
            'p2p',
            'porn',
            'private',
            'social',
            'shopping',
            'video',
            'vpn',
          ],
          description: 'Content category (optional)',
        },
        notes: {
          type: 'string',
          description: 'Additional description (optional)',
        },
      },
      required: ['name', 'owner', 'targets'],
    },
  },

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

  Tool registry where CreateTargetListHandler is instantiated and registered by name in the ToolRegistry during auto-registration.

  // 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 CreateTargetListHandler from rules.ts, enabling its use in registry.

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

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

  The registerHandlers method in ToolRegistry constructor that performs all tool registrations including create_target_list.

  }
  
  /**
   * Automatically registers 28 tool handlers for complete API coverage
   *
   * Registers handlers for the 28-tool architecture: 23 direct API endpoints
   * and 5 convenience wrappers. Each handler implements the ToolHandler interface
   * and maps to actual Firewalla API endpoints.
   *
   * @private
   * @returns {void}
   */
  private registerHandlers(): void {