firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/rules.ts:639-770 (handler)

  Core handler implementation for 'get_target_lists' tool. Extends BaseToolHandler, defines name, description, and execute method that validates parameters, calls firewalla.getTargetLists API, processes response with per-list target limiting to 500, and returns unified response format.

  export class GetTargetListsHandler extends BaseToolHandler {
    name = 'get_target_lists';
    description =
      'Access security target lists (CloudFlare, CrowdSec) with domains and IPs. Requires limit parameter. Data cached for 1 hour for performance.';
    category = 'rule' as const;
  
    constructor() {
      super({
        enableGeoEnrichment: false, // No IP fields in target lists metadata
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'target_lists',
          entity_type: 'security_target_lists',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      // Pre-flight parameter validation - do this before timeout wrapper
      const limitValidation = ParameterValidator.validateNumber(
        args?.limit,
        'limit',
        {
          required: true,
          ...getLimitValidationConfig(this.name),
        }
      );
  
      if (!limitValidation.isValid) {
        return createErrorResponse(
          this.name,
          'Parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          limitValidation.errors
        );
      }
  
      const limit = limitValidation.sanitizedValue! as number;
      const listType = args?.list_type as string | undefined;
  
      // Validate list_type parameter if provided
      if (listType !== undefined) {
        const validTypes = ['cloudflare', 'crowdsec', 'all'];
        if (!validTypes.includes(listType)) {
          return createErrorResponse(
            this.name,
            'Invalid list_type parameter',
            ErrorType.VALIDATION_ERROR,
            undefined,
            [`list_type must be one of: ${validTypes.join(', ')}`]
          );
        }
      }
  
      // Use timeout wrapper only for the API call and response processing
      return withToolTimeout(async () => {
        const listsResponse = await firewalla.getTargetLists(listType, limit);
  
        const startTime = Date.now();
  
        const unifiedResponseData = {
          total_lists: SafeAccess.safeArrayAccess(
            listsResponse.results,
            arr => arr.length,
            0
          ),
          limit_applied: limit,
          categories: Array.from(
            new Set(
              SafeAccess.safeArrayMap(listsResponse.results, (l: any) =>
                SafeAccess.getNestedValue(l, 'category', undefined)
              ).filter(Boolean)
            )
          ),
          target_lists: SafeAccess.safeArrayMap(
            listsResponse.results,
            (list: any) => ({
              id: SafeAccess.getNestedValue(list, 'id', 'unknown'),
              name: SafeAccess.getNestedValue(list, 'name', 'Unknown List'),
              owner: SafeAccess.getNestedValue(list, 'owner', 'unknown'),
              category: SafeAccess.getNestedValue(list, 'category', 'unknown'),
              entry_count: SafeAccess.safeArrayAccess(
                SafeAccess.getNestedValue(list, 'targets', []),
                arr => arr.length,
                0
              ),
              // Target List Buffer Strategy: Per-list target limiting
              //
              // Problem: Some target lists (especially threat intelligence feeds)
              // can contain 10,000+ targets, leading to:
              // - Excessive response payload sizes
              // - JSON serialization performance issues
              // - Client-side rendering problems
              //
              // Solution: Limit to 500 targets per list while preserving total count.
              // This balances:
              // - Useful data visibility (500 targets shows patterns/types)
              // - Response performance (manageable payload size)
              // - Client usability (reasonable display limits)
              //
              // The 500 limit was chosen as 5x the original 100 limit to provide
              // better visibility into large lists while maintaining performance.
              targets: SafeAccess.safeArrayAccess(
                SafeAccess.getNestedValue(list, 'targets', []),
                arr => arr.slice(0, 500), // Per-list target buffer limit
                []
              ),
              last_updated: safeUnixToISOString(
                SafeAccess.getNestedValue(list, 'lastUpdated', undefined) as
                  | number
                  | undefined,
                undefined
              ),
              notes: SafeAccess.getNestedValue(list, 'notes', ''),
            })
          ),
        };
  
        const executionTime = Date.now() - startTime;
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      }, this.name);
    }
  }

• src/server.ts:293-307 (schema)

  MCP tool schema definition in server ListTools response, specifying inputSchema with required 'limit' parameter (1-1000).

  name: 'get_target_lists',
  description: 'Retrieve all target lists from Firewalla',
  inputSchema: {
    type: 'object',
    properties: {
      limit: {
        type: 'number',
        description:
          'Maximum number of target lists to return (required)',
        minimum: 1,
        maximum: 1000,
      },
    },
    required: ['limit'],
  },

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

  ToolRegistry registers the GetTargetListsHandler instance during construction in registerHandlers() method. Also imported from './handlers/rules.js' at line 50.

  this.register(new GetTargetListsHandler());

• src/server.ts:833-833 (registration)

  FirewallaMCPServer calls setupTools which uses ToolRegistry to connect all handlers including get_target_lists to the MCP Server.

  setupTools(this.server, this.firewalla);

• src/config/limits.ts:87-87 (helper)

  Limit configuration for get_target_lists tool set to STANDARD_LIMITS.BASIC_QUERY (1000), used in ParameterValidator.getLimitValidationConfig.

  get_target_lists: STANDARD_LIMITS.BASIC_QUERY,