firewalla-mcp-server
Version:
Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client
203 lines • 7.45 kB
TypeScript
/**
* @fileoverview Token usage optimization utilities for Firewalla MCP Server
*
* Provides comprehensive response optimization for MCP protocol communication including:
* - **Intelligent Truncation**: Smart text shortening with word boundary preservation
* - **Response Summarization**: Field-level optimization for different data types
* - **Token Management**: Sophisticated token counting and size estimation
* - **Auto-optimization**: Automatic response size management with configurable limits
* - **Performance Monitoring**: Optimization statistics and compression metrics
*
* The optimization system reduces token usage while preserving essential information,
* ensuring Claude can process large datasets within MCP protocol constraints.
*
* @version 1.0.0
* @author Alex Mittell <mittell@me.com> (https://github.com/amittell)
* @since 2025-06-21
*/
/**
* Interface for objects that can be optimized and summarized
*/
export type OptimizableObject = Record<string, unknown>;
/**
* Interface for optimization statistics
*/
export interface OptimizationStats {
originalSize: number;
optimizedSize: number;
compressionRatio: number;
tokensSaved: number;
}
/**
* Default truncation limits for different text types
*/
declare const DEFAULT_TRUNCATION_LIMITS: {
readonly MESSAGE: 80;
readonly DEVICE_NAME: 30;
readonly REMOTE_NAME: 30;
readonly TARGET_VALUE: 60;
readonly NOTES: 60;
readonly VENDOR_NAME: 20;
readonly GENERIC_TEXT: 100;
readonly FLOW_DEVICE_NAME: 25;
};
/**
* Current truncation limits (configurable)
*/
export declare let TRUNCATION_LIMITS: {
MESSAGE: 80;
DEVICE_NAME: 30;
REMOTE_NAME: 30;
TARGET_VALUE: 60;
NOTES: 60;
VENDOR_NAME: 20;
GENERIC_TEXT: 100;
FLOW_DEVICE_NAME: 25;
};
/**
* Configure truncation limits for different deployment scenarios
*/
export declare function setTruncationLimits(limits: Partial<typeof DEFAULT_TRUNCATION_LIMITS>): void;
/**
* Reset truncation limits to defaults
*/
export declare function resetTruncationLimits(): void;
/**
* Base response interface with optional pagination metadata
*/
export interface BaseResponse {
count: number;
results: OptimizableObject[];
next_cursor?: string;
}
/**
* Optimized response interface with truncation metadata
*/
export interface OptimizedResponse extends BaseResponse {
truncated?: boolean;
truncation_note?: string;
}
/**
* Optimization configuration interface
*/
export interface OptimizationConfig {
/** Maximum response size in characters */
maxResponseSize: number;
/** Enable automatic truncation */
autoTruncate: boolean;
/** Truncation strategy */
truncationStrategy: 'head' | 'tail' | 'middle' | 'summary';
/** Summary mode configuration */
summaryMode: {
/** Maximum items in summary */
maxItems: number;
/** Fields to include in summary */
includeFields: string[];
/** Fields to exclude from summary */
excludeFields: string[];
};
}
/**
* Default optimization configuration
*/
export declare const DEFAULT_OPTIMIZATION_CONFIG: OptimizationConfig;
/**
* Calculate approximate token count for text
* Sophisticated estimation accounting for word boundaries, punctuation, and content characteristics
*
* @param text - The text to estimate token count for
* @returns The estimated token count
*/
export declare function estimateTokenCount(text: string): number;
/**
* Truncate text to specified length with smart truncation
*
* @param text - The text to truncate
* @param maxLength - The maximum length to truncate to
* @param strategy - The truncation strategy to use
* @returns The truncated text
*/
export declare function truncateText(text: string, maxLength: number, strategy?: 'ellipsis' | 'word'): string;
/**
* Create summary version of object by removing verbose fields
*
* @param obj - The object to summarize
* @param config - The summary mode configuration
* @returns The summarized object
*/
export declare function summarizeObject(obj: Record<string, unknown>, config: OptimizationConfig['summaryMode']): OptimizableObject;
/**
* Optimize alarm response for token efficiency
*
* @param response - The alarm response to optimize
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function optimizeAlarmResponse(response: BaseResponse, config: OptimizationConfig): OptimizedResponse;
/**
* Optimize flow response for token efficiency
*
* @param response - The flow response to optimize
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function optimizeFlowResponse(response: BaseResponse, config: OptimizationConfig): OptimizedResponse;
/**
* Optimize rule response for token efficiency
*
* @param response - The rule response to optimize
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function optimizeRuleResponse(response: BaseResponse, config: OptimizationConfig): OptimizedResponse;
/**
* Optimize device response for token efficiency
*
* @param response - The device response to optimize
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function optimizeDeviceResponse(response: BaseResponse, config: OptimizationConfig): OptimizedResponse;
/**
* Auto-optimize response based on size and type
*
* @param response - The response to optimize
* @param responseType - The type of response
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function autoOptimizeResponse(response: OptimizableObject, responseType: string, config?: OptimizationConfig): OptimizableObject;
/**
* Generic optimization for unknown response types
*
* @param response - The response to optimize
* @param config - The optimization configuration
* @returns The optimized response
*/
export declare function genericOptimization(response: BaseResponse, config: OptimizationConfig): OptimizedResponse;
/**
* Calculate optimization statistics
*
* @param original - The original response
* @param optimized - The optimized response
* @returns Statistics about the optimization
*/
export declare function getOptimizationStats(original: OptimizableObject, optimized: OptimizableObject): OptimizationStats;
/**
* Create optimization summary for debugging
*
* @param stats - The optimization statistics
* @returns A human-readable optimization summary
*/
export declare function createOptimizationSummary(stats: ReturnType<typeof getOptimizationStats>): string;
/**
* Method decorator that automatically optimizes the response of an asynchronous method based on the specified response type and optional configuration.
*
* Applies response truncation, summarization, and token management strategies to reduce payload size. If debug mode is enabled, logs optimization statistics to standard error.
*
* @param responseType - The type of response to optimize (e.g., 'alarms', 'flows', 'rules', 'devices')
* @param config - Optional optimization configuration to override defaults
*/
export declare function optimizeResponse(responseType: string, config?: Partial<OptimizationConfig>): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
export {};
//# sourceMappingURL=index.d.ts.map