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
310 lines • 12.2 kB
TypeScript
/**
* @fileoverview Base types and interfaces for MCP tool handlers
*
* Provides foundational classes and interfaces for implementing MCP tools that
* interact with Firewalla firewall data. Includes standardized error handling,
* response formatting, and validation patterns for consistent tool behavior.
*
* The base infrastructure ensures all tools follow MCP protocol standards while
* providing consistent error reporting and response structure across the entire
* tool ecosystem.
*
* @version 1.0.0
* @author Alex Mittell <mittell@me.com> (https://github.com/amittell)
* @since 2025-06-21
*/
import type { FirewallaClient } from '../../firewalla/client.js';
import { ErrorType } from '../../validation/error-handler.js';
import { type SanitizationConfig } from '../../validation/parameter-sanitizer.js';
/**
* Base arguments interface for MCP tool execution
*
* Provides type-safe foundation for all tool arguments while maintaining flexibility
* for tool-specific parameter extensions. Tools should extend this interface with
* their specific argument requirements to ensure proper type checking.
*/
export interface BaseToolArgs {
/** @description Optional limit for paginated results (recommended: 1-1000) */
limit?: number;
/** @description Optional offset for paginated results */
offset?: number;
/** @description Optional cursor for cursor-based pagination */
cursor?: string;
/** @description Optional sorting field specification */
sort_by?: string;
/** @description Optional sort order (ascending or descending) */
sort_order?: 'asc' | 'desc';
/** @description Optional grouping field for result aggregation */
group_by?: string;
/** @description Optional flag to enable result aggregation */
aggregate?: boolean;
/** @description Optional flag to force refresh and bypass cache */
force_refresh?: boolean;
[key: string]: unknown;
}
/**
* Common query parameters for search and filtering operations
*/
export interface QueryArgs {
/** @description Query string for filtering results */
query?: string;
/** @description Alternative query field name for compatibility */
queryBy?: string;
/** @description Alternative sort field name for compatibility */
sortBy?: string;
/** @description Alternative group field name for compatibility */
groupBy?: string;
}
/**
* Time range parameters for temporal filtering
*/
export interface TimeRangeArgs {
/** @description Start time for filtering (ISO string or Unix timestamp) */
start_time?: string | number;
/** @description End time for filtering (ISO string or Unix timestamp) */
end_time?: string | number;
/** @description Time range object with start and end */
time_range?: {
start?: string | number;
end?: string | number;
};
}
/**
* Device-specific parameters
*/
export interface DeviceArgs {
/** @description Specific device ID to filter by */
device_id?: string;
/** @description Whether to include offline devices */
include_offline?: boolean;
}
/**
* Geographic filtering parameters
*/
export interface GeographicArgs {
/** @description Geographic filters object */
geographic_filters?: {
countries?: string[];
continents?: string[];
regions?: string[];
cities?: string[];
asns?: string[];
hosting_providers?: string[];
exclude_cloud?: boolean;
exclude_vpn?: boolean;
min_risk_score?: number;
};
}
/**
* Cross-reference and correlation parameters
*/
export interface CorrelationArgs {
/** @description Primary query for correlation */
primary_query?: string;
/** @description Secondary queries for correlation */
secondary_queries?: string[];
/** @description Field to correlate on */
correlation_field?: string;
/** @description Correlation parameters object */
correlation_params?: {
correlationFields?: string[];
correlationType?: 'AND' | 'OR';
temporalWindow?: {
windowSize?: number;
windowUnit?: string;
};
networkScope?: {
includeSubnets?: boolean;
includePorts?: boolean;
};
enableScoring?: boolean;
enableFuzzyMatching?: boolean;
minimumScore?: number;
customWeights?: Record<string, number>;
fuzzyConfig?: {
enabled?: boolean;
stringThreshold?: number;
ipSubnetMatching?: boolean;
numericTolerance?: number;
geographicRadius?: number;
};
};
}
/**
* Box/Group management parameters
*/
export interface BoxArgs {
/** @description Group ID for filtering boxes */
group_id?: string;
}
/**
* Comprehensive tool arguments interface that includes all common parameter patterns
* used across the Firewalla MCP server tool handlers.
*
* This replaces the generic `any` type with specific, type-safe interfaces that
* cover all the parameter patterns observed in the codebase while maintaining
* backward compatibility.
*/
export interface ToolArgs extends BaseToolArgs, QueryArgs, TimeRangeArgs, DeviceArgs, GeographicArgs, CorrelationArgs, BoxArgs {
}
/**
* Standardized response structure for MCP tool execution
*
* All tools must return responses in this format for consistent MCP protocol compliance.
* The content array supports multiple response blocks with different types and formatting.
*/
export interface ToolResponse {
/** @description Array of content blocks containing tool output */
content: Array<{
/** @description Content type (typically 'text' for JSON responses) */
type: string;
/** @description The actual content text (usually JSON.stringify result) */
text: string;
}>;
/** @description Optional flag indicating if the response represents an error condition */
isError?: boolean;
/** @description Additional metadata or context for the response */
[key: string]: unknown;
}
/**
* Interface defining the contract for all MCP tool handlers
*
* Provides the foundation for implementing interactive tools that can be invoked
* by Claude through the MCP protocol to access and manipulate Firewalla data.
*/
export interface ToolHandler {
/**
* Execute the tool with given arguments and return formatted response
*
* @param args - Tool-specific arguments provided by the MCP client
* @param firewalla - Authenticated Firewalla client for API access
* @returns Promise resolving to formatted tool response
*/
execute: (args: ToolArgs, firewalla: FirewallaClient) => Promise<ToolResponse>;
/** @description Unique tool identifier used in MCP tool registration */
name: string;
/** @description Human-readable description of tool functionality */
description: string;
/** @description Tool category for organizational and filtering purposes */
category: 'security' | 'network' | 'device' | 'rule' | 'analytics' | 'search';
}
/**
* Configuration options for BaseToolHandler
*/
export interface BaseToolOptions {
/** Whether to enable geographic enrichment for IP addresses */
enableGeoEnrichment?: boolean;
/** Whether to enable field normalization to snake_case */
enableFieldNormalization?: boolean;
/** Additional metadata to include in responses */
additionalMeta?: Record<string, any>;
}
/**
* Base class for tool handlers with common validation and error handling
*
* Provides standardized implementation patterns for MCP tools including:
* - Unified response formatting with consistent metadata
* - Automatic geographic enrichment for IP addresses
* - Field normalization to snake_case
* - JSON serialization with proper error handling
* - Tool metadata structure validation
* - Common utility methods for response construction
*
* All concrete tool implementations should extend this class to ensure
* uniform behavior across the tool ecosystem.
*
* @abstract
* @implements {ToolHandler}
*/
export declare abstract class BaseToolHandler implements ToolHandler {
/** @description Tool identifier - must be implemented by concrete classes */
abstract name: string;
/** @description Tool description - must be implemented by concrete classes */
abstract description: string;
/** @description Tool category - must be implemented by concrete classes */
abstract category: 'security' | 'network' | 'device' | 'rule' | 'analytics' | 'search';
/** @description Configuration options for this handler */
protected options: BaseToolOptions;
/**
* Constructor with default configuration
*/
constructor(options?: BaseToolOptions);
/**
* Execute the tool logic - must be implemented by concrete classes
*
* @param args - Tool arguments from MCP client
* @param firewalla - Firewalla API client instance
* @returns Promise resolving to tool response
*/
abstract execute(args: ToolArgs, firewalla: FirewallaClient): Promise<ToolResponse>;
/**
* Create a legacy success response (DEPRECATED - Use createUnifiedResponse)
*
* @param data - The data to include in the response
* @returns Formatted success response compliant with MCP protocol
* @protected
* @deprecated Use createUnifiedResponse for new handlers
*/
protected createSuccessResponse(data: any): ToolResponse;
/**
* Create a unified success response with consistent formatting and enrichment
*
* @param data - The data to include in the response
* @param options - Additional options for response generation
* @returns Formatted success response with unified structure
* @protected
*/
protected createUnifiedResponse(data: any, options?: {
executionTimeMs?: number;
requestId?: string;
additionalMeta?: Record<string, any>;
}): Promise<ToolResponse>;
/**
* Helper method for geographic enrichment that can be called by handlers
*
* @param payload - Data to enrich with geographic information
* @param ipFields - Array of IP field names to enrich (defaults to common fields)
* @returns Promise resolving to enriched data
* @protected
*/
protected enrichGeoIfNeeded<T>(payload: T, ipFields?: string[]): Promise<T>;
/**
* Create a standardized error response with diagnostic information
*
* @param message - Human-readable error message
* @param errorType - Specific type of error (defaults to UNKNOWN_ERROR)
* @param details - Optional additional error context or debugging information
* @param validationErrors - Optional array of validation error messages
* @returns Formatted error response with isError flag set
* @protected
*/
protected createErrorResponse(message: string, errorType?: ErrorType, details?: any, validationErrors?: string[]): ToolResponse;
/**
* Sanitize and validate parameters early in the execution pipeline
*
* @param rawArgs - Raw arguments from MCP client
* @param config - Optional sanitization configuration
* @returns Sanitized arguments or error response
* @protected
*/
protected sanitizeParameters(rawArgs: unknown, config?: Partial<SanitizationConfig>): {
sanitizedArgs: ToolArgs;
} | {
errorResponse: ToolResponse;
};
/**
* Execute tool with automatic parameter sanitization
*
* This is a convenience method that automatically sanitizes parameters
* before calling the tool's main execution logic. Tools can override
* this to customize sanitization behavior.
*
* @param rawArgs - Raw arguments from MCP client
* @param firewalla - Firewalla API client instance
* @param config - Optional sanitization configuration
* @returns Promise resolving to tool response
* @protected
*/
protected executeWithSanitization(rawArgs: unknown, firewalla: FirewallaClient, config?: Partial<SanitizationConfig>): Promise<ToolResponse>;
}
//# sourceMappingURL=base.d.ts.map