firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/search.ts:1297-1453 (handler)

  SearchTargetListsHandler class implementing the 'search_target_lists' tool. Validates parameters using validateCommonSearchParameters, fetches data via searchTools.search_target_lists, standardizes response with target_lists array containing id, name, category, owner, entry_count, metadata, and query_info.

  export class SearchTargetListsHandler extends BaseToolHandler {
    name = 'search_target_lists';
    description = `Target list searching with comprehensive filtering for categories, ownership, and content analysis.
  
  Search through Firewalla target lists including domains, IPs, and security categories for policy management and analysis.
  
  QUERY EXAMPLES:
  - Category filtering: "category:ad", "category:social_media", "category:malware"
  - Ownership: "owner:global", "owner:custom", "owner:user_defined"
  - Content type: "type:domain", "type:ip", "type:url_pattern"
  - Size filtering: "target_count:>100", "active_targets:>50"
  - Status queries: "enabled:true", "updated:>=2024-01-01"
  
  TARGET LIST MANAGEMENT:
  - Ad blocking lists: "category:ad AND enabled:true"
  - Security lists: "category:malware OR category:phishing OR category:threat"
  - Social media controls: "category:social_media AND owner:custom"
  - Custom domain lists: "owner:user_defined AND type:domain"
  - Large lists analysis: "target_count:>1000 AND category:security"
  
  CONTENT ANALYSIS:
  - Popular categories: group_by:"category" for category distribution
  - List effectiveness: "hit_count:>0 AND enabled:true"
  - Maintenance needed: "updated:<=30d AND enabled:true"
  - Unused lists: "hit_count:0 AND enabled:true"
  
  PERFORMANCE CONSIDERATIONS:
  - Target lists cached for 10 minutes for optimal performance
  - Use specific category filters for faster searches
  - Large lists (>10,000 targets) may have slower response times
  - Aggregate queries provide faster overview statistics
  
  FIELD NORMALIZATION:
  - Categories standardized to lowercase with consistent naming
  - Target counts validated as non-negative numbers
  - Timestamps normalized to ISO format
  - Unknown values replaced with "unknown" for consistency
  
  See the Target List Management guide for configuration details.`;
    category = 'search' as const;
  
    constructor() {
      // Enable field normalization for target lists (no geographic enrichment needed)
      super({
        enableGeoEnrichment: false, // Target lists don't typically contain IP addresses
        enableFieldNormalization: true, // Ensure consistent snake_case field naming across all responses
        additionalMeta: {
          data_source: 'target_lists',
          entity_type: 'target_lists',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      const searchArgs = args as SearchTargetListsArgs;
      try {
        // Validate common search parameters
        const validation = validateCommonSearchParameters(
          searchArgs,
          this.name,
          'target_lists'
        );
  
        if (!validation.isValid) {
          return validation.response;
        }
  
        const searchTools = createSearchTools(firewalla);
        const searchParams: SearchParams = {
          query: searchArgs.query,
          limit: searchArgs.limit,
          offset: searchArgs.offset,
          cursor: searchArgs.cursor,
          sort_by: searchArgs.sort_by,
          sort_order: searchArgs.sort_order,
          group_by: searchArgs.group_by,
          aggregate: searchArgs.aggregate,
        };
  
        const result = await withToolTimeout(
          async () => searchTools.search_target_lists(searchParams),
          this.name
        );
  
        // Create unified response with standardized target list data
        const unifiedResponseData = {
          target_lists: SafeAccess.safeArrayMap(
            result.results,
            (list: TargetList) => ({
              id: SafeAccess.getNestedValue(list as any, 'id', 'unknown'),
              name: SafeAccess.getNestedValue(
                list as any,
                'name',
                'Unknown List'
              ),
              category: SafeAccess.getNestedValue(
                list as any,
                'category',
                'unknown'
              ),
              owner: SafeAccess.getNestedValue(list as any, 'owner', 'unknown'),
              entry_count: SafeAccess.safeArrayAccess(
                list.targets,
                arr => arr.length,
                0
              ),
            })
          ),
          count: SafeAccess.safeArrayAccess(
            (result as any).results,
            arr => arr.length,
            0
          ),
          query_executed: SafeAccess.getNestedValue(result as any, 'query', ''),
          execution_time_ms: SafeAccess.getNestedValue(
            result as any,
            'execution_time_ms',
            0
          ),
          aggregations: SafeAccess.getNestedValue(
            result as any,
            'aggregations',
            null
          ),
          query_info: {
            original_query: searchArgs.query,
            applied_filters: {
              grouping: !!searchArgs.group_by,
              sorting: !!searchArgs.sort_by,
              aggregation: !!searchArgs.aggregate,
            },
          },
        };
  
        // Return unified response
        return this.createUnifiedResponse(unifiedResponseData);
      } 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 search target lists: ${errorMessage}`,
          ErrorType.SEARCH_ERROR
        );
      }
    }
  }

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

  Explicit registration of new SearchTargetListsHandler() instance in ToolRegistry constructor's registerHandlers() method, listed as convenience wrapper with client-side filtering.

  this.register(new SearchTargetListsHandler()); // wrapper with client-side filtering
  this.register(new GetNetworkRulesSummaryHandler()); // wrapper around get_network_rules

• src/server.ts:776-806 (schema)

  JSON Schema definition for 'search_target_lists' tool provided to MCP clients via ListToolsRequestHandler. Defines input parameters: query (search string), category, owner, limit (1-500, default 100).

  {
    name: 'search_target_lists',
    description:
      'Search target lists with client-side filtering (convenience wrapper around get_target_lists)',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description:
            'Search query for target lists. Supported fields: name:*Social*, owner:global/box_gid, category:social/games/ad/porn/etc, targets:*.facebook.com, notes:"description text". Examples: "category:social", "owner:global AND name:*Block*", "targets:*.gaming.com"',
        },
        category: {
          type: 'string',
          description: 'Filter by category',
        },
        owner: {
          type: 'string',
          description: 'Filter by owner (global or box gid)',
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 500,
          default: 100,
          description: 'Maximum number of target lists to return',
        },
      },
      required: [],
    },
  },

• src/tools/index.ts:69-134 (registration)

  setupTools function called from server.ts that initializes ToolRegistry and registers all tools to MCP server by setting CallToolRequestHandler to lookup handlers by name and execute them with FirewallaClient.

  export function setupTools(server: Server, firewalla: FirewallaClient): void {
    // Initialize the tool registry with all 35 handlers
    const toolRegistry = new ToolRegistry();
  
    // Set up the main request handler using the registry
    server.setRequestHandler(CallToolRequestSchema, async request => {
      const { name, arguments: args } = request.params;
  
      const startTime = Date.now();
  
      try {
        // Get handler from the registry
        const handler = toolRegistry.getHandler(name);
        if (!handler) {
          const availableTools = toolRegistry.getToolNames() || [];
          throw new Error(
            `Unknown tool: ${name}. Available tools: ${availableTools.join(', ')}`
          );
        }
  
        // Execute the tool handler with proper error handling
        logger.debug(
          `Executing tool: ${name} with handler: ${handler.constructor.name}`
        );
        const response = await handler.execute(args || {}, firewalla);
  
        // <add success telemetry>
        metrics.count('tool.success');
        metrics.timing('tool.latency_ms', Date.now() - startTime);
        // </add>
  
        return response;
      } catch (error: unknown) {
        // <add error metric>
        metrics.count('tool.error');
        // </add>
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        logger.error(`Tool execution failed for ${name}:`, error as Error);
  
        // Use centralized error handling
        return createErrorResponse(name, errorMessage, ErrorType.UNKNOWN_ERROR, {
          timestamp: getCurrentTimestamp(),
          error_type:
            error instanceof Error ? error.constructor.name : 'UnknownError',
          available_tools: toolRegistry.getToolNames() || [],
        });
      }
    });
  
    const allToolNames = toolRegistry.getToolNames() || [];
    const categories = [
      'security',
      'network',
      'device',
      'rule',
      'analytics',
      'search',
    ];
    const totalCategories = categories.length;
  
    logger.info(
      `MCP tools setup complete. Registry contains ${allToolNames.length} handlers across ${totalCategories} categories.`
    );
    logger.info(`Registered tools: ${allToolNames.join(', ')}`);
  }

• src/tools/handlers/search.ts:155-304 (helper)

  Shared validateCommonSearchParameters helper function used by SearchTargetListsHandler (and other search handlers) for input validation: limit, query syntax validation, field sanitization, cursor format, group_by enum checks.

  function validateCommonSearchParameters(
    args: BaseSearchArgs,
    toolName: string,
    entityType: 'flows' | 'alarms' | 'rules' | 'devices' | 'target_lists'
  ): CommonSearchValidationResult {
    // Validate optional limit parameter with default
    const limitValidation = ParameterValidator.validateNumber(
      args.limit,
      'limit',
      {
        required: false,
        defaultValue: 200,
        ...getLimitValidationConfig(toolName),
      }
    );
  
    if (!limitValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          limitValidation.errors
        ),
      };
    }
  
    // Validate required query parameter
    const queryValidation = ParameterValidator.validateRequiredString(
      args.query,
      'query'
    );
  
    if (!queryValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Query parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          queryValidation.errors
        ),
      };
    }
  
    // Validate query syntax
    const querySyntaxValidation = validateFirewallaQuerySyntax(args.query);
  
    if (!querySyntaxValidation.isValid) {
      const examples = getExampleQueries(entityType);
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Invalid query syntax',
          ErrorType.VALIDATION_ERROR,
          {
            query: args.query,
            syntax_errors: querySyntaxValidation.errors,
            examples: examples.slice(0, 3),
            hint: 'Use field:value syntax with logical operators (AND, OR, NOT)',
          },
          querySyntaxValidation.errors
        ),
      };
    }
  
    // Validate field names in the query
    const fieldValidation = QuerySanitizer.validateQueryFields(
      args.query,
      entityType
    );
  
    if (!fieldValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Query contains invalid field names',
          ErrorType.VALIDATION_ERROR,
          {
            query: args.query,
            documentation:
              entityType === 'alarms'
                ? 'See /docs/error-handling-guide.md for troubleshooting'
                : 'See /docs/query-syntax-guide.md for valid field names',
          },
          fieldValidation.errors
        ),
      };
    }
  
    // Validate cursor format if provided
    if (args.cursor !== undefined) {
      const cursorValidation = ParameterValidator.validateCursor(
        args.cursor,
        'cursor'
      );
      if (!cursorValidation.isValid) {
        return {
          isValid: false,
          response: createErrorResponse(
            toolName,
            'Invalid cursor format',
            ErrorType.VALIDATION_ERROR,
            undefined,
            cursorValidation.errors
          ),
        };
      }
    }
  
    // Validate group_by parameter if provided
    if (args.group_by !== undefined) {
      const groupByValidation = ParameterValidator.validateEnum(
        args.group_by,
        'group_by',
        SEARCH_FIELDS[entityType],
        false
      );
  
      if (!groupByValidation.isValid) {
        return {
          isValid: false,
          response: createErrorResponse(
            toolName,
            'Invalid group_by field',
            ErrorType.VALIDATION_ERROR,
            {
              group_by: args.group_by,
              valid_fields: SEARCH_FIELDS[entityType],
              documentation: 'See /docs/query-syntax-guide.md for valid fields',
            },
            groupByValidation.errors
          ),
        };
      }
    }
  
    return {
      isValid: true,
      limit: args.limit,
      query: args.query,
      cursor: args.cursor,
      groupBy: args.group_by,
    };
  }