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