firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/search.ts:1109-1295 (handler)

  The SearchDevicesHandler class provides the core execution logic for the 'search_devices' tool. It validates input parameters using validateCommonSearchParameters, calls the Firewalla search API via createSearchTools(firewalla).search_devices, processes device data with SafeAccess and geographic enrichment, and returns a standardized response with metadata.

  export class SearchDevicesHandler extends BaseToolHandler {
    name = 'search_devices';
    description = `Network device searching with comprehensive filtering for status, usage patterns, and network properties. Data cached for 5 minutes, use force_refresh=true for real-time device status.
  
  Search through network devices to monitor connectivity, identify issues, and analyze usage patterns.
  
  REQUIRED PARAMETERS:
  - query: Search query string using device field syntax
  
  OPTIONAL PARAMETERS:
  - limit: Maximum number of results to return (default: 200, max: 500)
  - force_refresh: Bypass cache for real-time status (default: false)
  - cursor: Pagination cursor from previous response
  - time_range: Time window for search (start/end timestamps)
  - sort_by: Field to sort results by
  - group_by: Field to group results by for aggregation
  - aggregate: Enable aggregation statistics
  
  QUERY EXAMPLES:
  - Status filtering: "online:true", "online:false", "last_seen:>=yesterday"
  - Device identification: "mac_vendor:Apple", "name:*iPhone*", "ip:192.168.1.*"
  - Network properties: "network_id:main", "dhcp:true", "static_ip:true"
  - Usage patterns: "bandwidth_usage:>1000000", "active_connections:>10"
  - Device types: "device_type:smartphone", "os_type:iOS", "manufacturer:Samsung"
  
  CACHE CONTROL:
  - Default: 5-minute cache for optimal performance
  - Real-time: Use force_refresh=true for device troubleshooting
  - Cache info included in responses for timing awareness
  
  NETWORK MONITORING:
  - Offline devices: "online:false AND last_seen:>=24h" (recently offline)
  - Heavy bandwidth users: "bandwidth_usage:>5000000 AND online:true"
  - Unknown devices: "name:unknown OR mac_vendor:unknown"
  - Mobile devices: "device_type:smartphone OR device_type:tablet"
  - IoT devices: "device_category:IoT OR manufacturer:smart_*"
  
  TROUBLESHOOTING:
  - Connection issues: "online:false AND dhcp_errors:>0"
  - Security concerns: "new_device:true AND trust_level:low"
  - Performance problems: "packet_loss:>5 OR latency:>100"
  
  PAGINATION:
  - Use cursor-based pagination for large device lists
  - Supports up to 10,000 devices per query
  - Include offline devices with include_offline:true
  
  FIELD CONSISTENCY:
  - Device names normalized to remove unknown/null inconsistencies
  - IP addresses validated and standardized
  - Timestamps converted to ISO format for consistency
  
  See the Data Normalization Guide for field details.`;
    category = 'search' as const;
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      const searchArgs = args as SearchDevicesArgs;
      try {
        // Validate common search parameters
        const validation = validateCommonSearchParameters(
          searchArgs,
          this.name,
          'devices'
        );
  
        if (!validation.isValid) {
          return validation.response;
        }
  
        // Validate that both cursor and offset are not provided simultaneously
        if (searchArgs.cursor !== undefined && searchArgs.offset !== undefined) {
          return createErrorResponse(
            this.name,
            'Cannot provide both cursor and offset parameters simultaneously',
            ErrorType.VALIDATION_ERROR,
            {
              provided_cursor: searchArgs.cursor,
              provided_offset: searchArgs.offset,
              documentation:
                'Use either cursor-based pagination (cursor) or offset-based pagination (offset), but not both',
            },
            ['cursor and offset parameters are mutually exclusive']
          );
        }
  
        // Validate force_refresh parameter if provided
        const forceRefreshValidation = ParameterValidator.validateBoolean(
          searchArgs.force_refresh,
          'force_refresh',
          false
        );
  
        if (!forceRefreshValidation.isValid) {
          return createErrorResponse(
            this.name,
            'Force refresh parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            forceRefreshValidation.errors
          );
        }
  
        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,
          time_range: searchArgs.time_range,
          force_refresh: forceRefreshValidation.sanitizedValue as boolean,
        };
  
        const result = await withToolTimeout(
          async () => searchTools.search_devices(searchParams),
          this.name
        );
  
        // Process and enrich device data with geographic information
        const deviceData = await this.enrichGeoIfNeeded(
          SafeAccess.safeArrayMap((result as any).results, (device: Device) => ({
            id: SafeAccess.getNestedValue(device as any, 'id', 'unknown'),
            name: SafeAccess.getNestedValue(
              device as any,
              'name',
              'Unknown Device'
            ),
            ip: SafeAccess.getNestedValue(device as any, 'ip', 'unknown'),
            online: SafeAccess.getNestedValue(device as any, 'online', false),
            macVendor: SafeAccess.getNestedValue(
              device as any,
              'macVendor',
              'unknown'
            ),
            lastSeen: SafeAccess.getNestedValue(device as any, 'lastSeen', 0),
          })),
          ['ip'] // Enrich the device IP addresses
        );
  
        const unifiedResponseData = {
          devices: deviceData,
          count: deviceData.length,
          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: {
              time_range: !!searchArgs.time_range,
              force_refresh: !!searchArgs.force_refresh,
              cursor_pagination: !!searchArgs.cursor,
              offset_pagination: !!searchArgs.offset,
            },
          },
        };
  
        // 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 devices: ${errorMessage}`,
          ErrorType.SEARCH_ERROR
        );
      }
    }
  }

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

  Registration of the SearchDevicesHandler instance in the ToolRegistry's registerHandlers method, listed among convenience wrapper tools.

  // Convenience Wrappers (5 handlers)
  this.register(new GetBandwidthUsageHandler()); // wrapper around get_device_status
  this.register(new GetOfflineDevicesHandler()); // wrapper around get_device_status
  this.register(new SearchDevicesHandler()); // 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:743-775 (schema)

  Input schema definition for the 'search_devices' tool provided in the server's listTools response, specifying parameters, types, descriptions, and validation constraints.

  {
    name: 'search_devices',
    description:
      'Search devices by name, IP, MAC or status (convenience wrapper with client-side filtering)',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description:
            'Search query using Firewalla syntax. Supported fields: mac:AA:BB:CC:DD:EE:FF, ip:192.168.1.*, name:*iPhone*, online:true/false, vendor:Apple, gid:box_id, network.name:*, group.name:*. Examples: "online:false AND vendor:Apple", "ip:192.168.1.* AND name:*laptop*", "mac:AA:* OR name:*phone*"',
        },
        status: {
          type: 'string',
          enum: ['online', 'offline', 'any'],
          default: 'any',
          description: 'Filter by online status',
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 500,
          default: 50,
          description: 'Maximum number of devices to return',
        },
        box: {
          type: 'string',
          description: 'Filter devices under a specific Firewalla box',
        },
      },
      required: [],
    },
  },

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

  Import statement for SearchDevicesHandler from the handlers/search module, enabling its use in the registry.

    SearchFlowsHandler,
    SearchAlarmsHandler,
    SearchRulesHandler,
    SearchDevicesHandler,
    SearchTargetListsHandler,
  } from './handlers/search.js';

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

  Shared validation helper function used by SearchDevicesHandler (and other search tools) to validate common search parameters like query syntax, limits, and fields specific to 'devices' entity type.

  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,
    };
  }