firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/analytics.ts:580-788 (handler)

  GetRecentFlowActivityHandler class: core implementation that fetches up to 50 recent network flows (last 10-20 min), analyzes protocols/regions/blocked flows, and returns formatted snapshot for immediate network activity assessment.

  export class GetRecentFlowActivityHandler extends BaseToolHandler {
    name = 'get_recent_flow_activity';
    description =
      'Get recent network flow activity snapshot (last 10-20 minutes of traffic). Returns up to 50 most recent flows for immediate analysis. IMPORTANT: This is NOT historical trend data - it shows current activity only. Use for "what\'s happening now" questions, not daily/weekly patterns. Ideal for: current security assessment, immediate network state, recent protocol distribution.';
    category = 'analytics' as const;
  
    private static readonly MAX_FLOWS = 50;
    private static readonly FLOWS_PER_PAGE = 50;
    private static readonly MAX_PAGES = Math.ceil(
      GetRecentFlowActivityHandler.MAX_FLOWS /
        GetRecentFlowActivityHandler.FLOWS_PER_PAGE
    );
  
    constructor() {
      super({
        enableGeoEnrichment: false, // Disabled to stay within token limits
        enableFieldNormalization: true,
        additionalMeta: {
          data_source: 'recent_flow_activity',
          entity_type: 'current_network_snapshot',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
          time_scope: 'recent_activity_only',
          max_flows: GetRecentFlowActivityHandler.MAX_FLOWS,
        },
      });
    }
  
    async execute(
      _args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      try {
        const startTime = Date.now();
        const allFlows: any[] = [];
        let cursor: string | undefined;
        let pagesProcessed = 0;
  
        // Fetch up to 2000 flows in 4 pages of 500 each
        while (
          pagesProcessed < GetRecentFlowActivityHandler.MAX_PAGES &&
          allFlows.length < GetRecentFlowActivityHandler.MAX_FLOWS
        ) {
          const currentCursor = cursor;
          const pageData = await withToolTimeout(
            async () =>
              firewalla.getFlowData(
                undefined, // No query filter - get all recent flows
                undefined, // No groupBy - we want individual flows
                'ts:desc', // Most recent first
                GetRecentFlowActivityHandler.FLOWS_PER_PAGE,
                currentCursor
              ),
            this.name
          );
  
          if (!pageData?.results || !Array.isArray(pageData.results)) {
            break; // No more data or invalid response
          }
  
          allFlows.push(...pageData.results);
          cursor = pageData.next_cursor;
          pagesProcessed++;
  
          // Break if no more pages available or we hit our limit
          if (
            !cursor ||
            allFlows.length >= GetRecentFlowActivityHandler.MAX_FLOWS
          ) {
            break;
          }
        }
  
        // Limit to exactly MAX_FLOWS if we got more
        const flows = allFlows.slice(0, GetRecentFlowActivityHandler.MAX_FLOWS);
  
        if (flows.length === 0) {
          return this.createUnifiedResponse(
            {
              flows_analyzed: 0,
              time_span_minutes: 0,
              activity_summary: 'No recent flows found',
              flows: [],
              limitations: {
                data_scope: 'Current activity snapshot only',
                not_suitable_for: [
                  'Historical analysis',
                  'Daily patterns',
                  'Trend analysis',
                ],
                time_frame: 'Last 10-20 minutes for high-volume networks',
              },
            },
            {
              executionTimeMs: Date.now() - startTime,
            }
          );
        }
  
        // Calculate time span of the flows
        const oldestFlow = flows[flows.length - 1];
        const newestFlow = flows[0];
        const timeSpanSeconds = (newestFlow.ts || 0) - (oldestFlow.ts || 0);
        const timeSpanMinutes = Math.round(timeSpanSeconds / 60);
  
        // Analyze the flows for summary statistics
        const protocolCounts = new Map<string, number>();
        const regionCounts = new Map<string, number>();
        const blockedCount = flows.filter(f => f.block).length;
        const allowedCount = flows.length - blockedCount;
  
        flows.forEach(flow => {
          const protocol = flow.protocol || 'unknown';
          const region = flow.region || flow.country || 'unknown';
  
          protocolCounts.set(protocol, (protocolCounts.get(protocol) || 0) + 1);
          regionCounts.set(region, (regionCounts.get(region) || 0) + 1);
        });
  
        // Convert maps to sorted arrays for top protocols/regions
        const topProtocols = Array.from(protocolCounts.entries())
          .sort((a, b) => b[1] - a[1])
          .slice(0, 5)
          .map(([protocol, count]) => ({
            protocol,
            count,
            percentage: Math.round((count / flows.length) * 100),
          }));
  
        const topRegions = Array.from(regionCounts.entries())
          .sort((a, b) => b[1] - a[1])
          .slice(0, 5)
          .map(([region, count]) => ({
            region,
            count,
            percentage: Math.round((count / flows.length) * 100),
          }));
  
        const unifiedResponseData = {
          flows_analyzed: flows.length,
          pages_fetched: pagesProcessed,
          time_span_minutes: timeSpanMinutes,
          data_period: `Last ${timeSpanMinutes} minutes`,
          activity_summary: {
            total_flows: flows.length,
            blocked_flows: blockedCount,
            allowed_flows: allowedCount,
            blocked_percentage: Math.round((blockedCount / flows.length) * 100),
            top_protocols: topProtocols,
            top_regions: topRegions,
          },
          flows: flows.map(flow => ({
            timestamp: flow.ts,
            timestamp_iso: safeUnixToISOString(flow.ts, 'Never'),
            protocol: flow.protocol,
            direction: flow.direction,
            blocked: flow.block,
            source_ip: flow.source?.ip,
            destination_ip: flow.destination?.ip,
            region: flow.region || flow.country,
            category: flow.category,
            domain: flow.domain,
            bytes: flow.total || 0,
            block_reason: flow.blockedby,
          })),
          limitations: {
            data_scope: 'Recent activity snapshot only - NOT historical trends',
            sample_size: `${flows.length} flows from last ${timeSpanMinutes} minutes`,
            not_suitable_for: [
              'Daily/weekly/monthly analysis',
              'Historical trend identification',
              'Peak usage time analysis',
              'Long-term pattern detection',
            ],
            suitable_for: [
              'Current network state assessment',
              'Immediate security analysis',
              'Recent protocol distribution',
              'Active threat detection',
              'Real-time activity monitoring',
            ],
            performance_note:
              flows.length >= GetRecentFlowActivityHandler.MAX_FLOWS
                ? `Limited to ${GetRecentFlowActivityHandler.MAX_FLOWS} flows for performance`
                : 'All available recent flows included',
          },
        };
  
        const executionTime = Date.now() - startTime;
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error';
        return this.createErrorResponse(
          `Failed to get recent flow activity: ${errorMessage}`,
          ErrorType.API_ERROR,
          {
            max_flows: GetRecentFlowActivityHandler.MAX_FLOWS,
            flows_per_page: GetRecentFlowActivityHandler.FLOWS_PER_PAGE,
            troubleshooting:
              'Check if Firewalla API is accessible and credentials are valid',
          }
        );
      }
    }
  }

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

  Tool registration in ToolRegistry constructor: instantiates and registers the handler with the MCP tool registry.

  this.register(new GetRecentFlowActivityHandler());

• src/server.ts:604-612 (schema)

  MCP protocol tool schema: defines name, detailed description emphasizing current snapshot use-case, and empty input schema (no parameters required).

    name: 'get_recent_flow_activity',
    description:
      'Get recent network flow activity snapshot (last 10-20 minutes). Returns up to 50 most recent flows for immediate analysis. CRITICAL: This is a quick snapshot tool only. Use this for: "what\'s happening right now?", current security threats, immediate network issues. DO NOT use for: historical analysis (use search_flows), getting more than 50 flows (use search_flows with limit), daily/weekly patterns (use search_flows with time queries like "ts:>24h"). For comprehensive analysis, always prefer search_flows.',
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
    },
  },