@mseep/mcp-agent-social 1.1.0

package/src/metrics.ts

@@ -0,0 +1,235 @@
+// ABOUTME: Basic performance monitoring and metrics collection
+// ABOUTME: Tracks operation timings, memory usage, and system health
+
+export interface Metric {
+  name: string;
+  value: number;
+  timestamp: Date;
+  tags?: Record<string, string>;
+}
+
+export interface OperationMetrics {
+  count: number;
+  totalDuration: number;
+  minDuration: number;
+  maxDuration: number;
+  averageDuration: number;
+  lastDuration: number;
+  errors: number;
+}
+
+export class MetricsCollector {
+  private static instance: MetricsCollector;
+  private metrics: Map<string, OperationMetrics>;
+  private startTime: number;
+  private sessionCount: number;
+  private activeOperations: Map<string, number>;
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null;
+  private readonly OPERATION_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+  private constructor() {
+    this.metrics = new Map();
+    this.startTime = Date.now();
+    this.sessionCount = 0;
+    this.activeOperations = new Map();
+
+    // Set up periodic cleanup of stale operations
+    this.cleanupInterval = setInterval(() => this.cleanupStaleOperations(), 60000); // Every minute
+    // Allow process to exit even if interval is active (for tests)
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  static getInstance(): MetricsCollector {
+    if (!MetricsCollector.instance) {
+      MetricsCollector.instance = new MetricsCollector();
+    }
+    return MetricsCollector.instance;
+  }
+
+  // Start tracking an operation
+  startOperation(operationName: string): string {
+    const operationId = `${operationName}_${Date.now()}_${Math.random()}`;
+    this.activeOperations.set(operationId, Date.now());
+    return operationId;
+  }
+
+  // End tracking an operation
+  endOperation(operationId: string, success = true): void {
+    const startTime = this.activeOperations.get(operationId);
+    if (!startTime) {
+      return;
+    }
+
+    const duration = Date.now() - startTime;
+    this.activeOperations.delete(operationId);
+
+    // Extract operation name from ID
+    const operationName = operationId.split('_')[0];
+    this.recordOperation(operationName, duration, success);
+  }
+
+  // Cleanup stale operations that have been running too long
+  private cleanupStaleOperations(): void {
+    const now = Date.now();
+    const staleOperations: string[] = [];
+
+    for (const [id, startTime] of this.activeOperations.entries()) {
+      if (now - startTime > this.OPERATION_TIMEOUT) {
+        staleOperations.push(id);
+      }
+    }
+
+    // Remove stale operations and record them as timed out
+    for (const id of staleOperations) {
+      this.activeOperations.delete(id);
+      const operationName = id.split('_')[0];
+      this.recordOperation(operationName, this.OPERATION_TIMEOUT, false, 'timeout');
+    }
+  }
+
+  // Record an operation metric
+  private recordOperation(
+    name: string,
+    duration: number,
+    success: boolean,
+    _reason?: string,
+  ): void {
+    let metrics = this.metrics.get(name);
+    if (!metrics) {
+      metrics = {
+        count: 0,
+        totalDuration: 0,
+        minDuration: Number.POSITIVE_INFINITY,
+        maxDuration: 0,
+        averageDuration: 0,
+        lastDuration: 0,
+        errors: 0,
+      };
+      this.metrics.set(name, metrics);
+    }
+
+    metrics.count++;
+    metrics.totalDuration += duration;
+    metrics.minDuration = Math.min(metrics.minDuration, duration);
+    metrics.maxDuration = Math.max(metrics.maxDuration, duration);
+    metrics.averageDuration = metrics.totalDuration / metrics.count;
+    metrics.lastDuration = duration;
+
+    if (!success) {
+      metrics.errors++;
+    }
+  }
+
+  // Session management metrics
+  incrementSessionCount(): void {
+    this.sessionCount++;
+  }
+
+  decrementSessionCount(): void {
+    this.sessionCount = Math.max(0, this.sessionCount - 1);
+  }
+
+  getSessionCount(): number {
+    return this.sessionCount;
+  }
+
+  // Get metrics for a specific operation
+  getOperationMetrics(operationName: string): OperationMetrics | undefined {
+    return this.metrics.get(operationName);
+  }
+
+  // Get all metrics
+  getAllMetrics(): Record<string, OperationMetrics> {
+    const result: Record<string, OperationMetrics> = {};
+    this.metrics.forEach((value, key) => {
+      result[key] = { ...value };
+    });
+    return result;
+  }
+
+  // Get system metrics
+  getSystemMetrics(): {
+    uptime: number;
+    memoryUsage: ReturnType<typeof process.memoryUsage>;
+    sessionCount: number;
+    activeOperations: number;
+  } {
+    return {
+      uptime: Math.floor((Date.now() - this.startTime) / 1000),
+      memoryUsage: process.memoryUsage(),
+      sessionCount: this.sessionCount,
+      activeOperations: this.activeOperations.size,
+    };
+  }
+
+  // Get formatted summary
+  getSummary(): string {
+    const system = this.getSystemMetrics();
+    const operations = this.getAllMetrics();
+
+    let summary = '=== System Metrics ===\n';
+    summary += `Uptime: ${system.uptime}s\n`;
+    summary += `Memory (RSS): ${Math.round(system.memoryUsage.rss / 1024 / 1024)}MB\n`;
+    summary += `Memory (Heap Used): ${Math.round(system.memoryUsage.heapUsed / 1024 / 1024)}MB\n`;
+    summary += `Active Sessions: ${system.sessionCount}\n`;
+    summary += `Active Operations: ${system.activeOperations}\n\n`;
+
+    summary += '=== Operation Metrics ===\n';
+    for (const [name, metrics] of Object.entries(operations)) {
+      summary += `${name}:\n`;
+      summary += `  Count: ${metrics.count}\n`;
+      summary += `  Avg Duration: ${Math.round(metrics.averageDuration)}ms\n`;
+      summary += `  Min Duration: ${Math.round(metrics.minDuration)}ms\n`;
+      summary += `  Max Duration: ${Math.round(metrics.maxDuration)}ms\n`;
+      summary += `  Error Rate: ${((metrics.errors / metrics.count) * 100).toFixed(2)}%\n`;
+    }
+
+    return summary;
+  }
+
+  // Reset all metrics (useful for testing)
+  reset(): void {
+    this.metrics.clear();
+    this.activeOperations.clear();
+    this.sessionCount = 0;
+
+    // Clear the cleanup interval when resetting
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = setInterval(() => this.cleanupStaleOperations(), 60000);
+      // Allow process to exit even if interval is active (for tests)
+      if (this.cleanupInterval.unref) {
+        this.cleanupInterval.unref();
+      }
+    }
+  }
+
+  // Shutdown the metrics collector (for cleanup)
+  shutdown(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+}
+
+// Export singleton instance
+export const metrics = MetricsCollector.getInstance();
+
+// Helper function for timing async operations
+export async function withMetrics<T>(
+  operationName: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const operationId = metrics.startOperation(operationName);
+  try {
+    const result = await operation();
+    metrics.endOperation(operationId, true);
+    return result;
+  } catch (error) {
+    metrics.endOperation(operationId, false);
+    throw error;
+  }
+}

package/src/middleware/error-handler.ts

@@ -0,0 +1,252 @@
+// ABOUTME: Enhanced error handling with context enrichment and proper MCP error formatting
+// ABOUTME: Provides structured error responses and comprehensive error tracking
+
+import { logger } from '../logger.js';
+
+// Custom error classes for better type safety
+export class McpValidationError extends Error {
+  constructor(
+    message: string,
+    public details?: any,
+  ) {
+    super(message);
+    this.name = 'McpValidationError';
+  }
+}
+
+export class McpAuthenticationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'McpAuthenticationError';
+  }
+}
+
+export class McpRateLimitError extends Error {
+  constructor(
+    message: string,
+    public retryAfter?: number,
+  ) {
+    super(message);
+    this.name = 'McpRateLimitError';
+  }
+}
+
+export class McpTimeoutError extends Error {
+  constructor(
+    message: string,
+    public timeout?: number,
+  ) {
+    super(message);
+    this.name = 'McpTimeoutError';
+  }
+}
+
+export class McpMethodNotFoundError extends Error {
+  constructor(
+    message: string,
+    public method?: string,
+  ) {
+    super(message);
+    this.name = 'McpMethodNotFoundError';
+  }
+}
+
+export interface ErrorContext {
+  sessionId: string;
+  requestId: string;
+  method: string;
+  startTime: number;
+}
+
+export interface McpError {
+  code: number;
+  message: string;
+  data?: any;
+}
+
+export class ErrorHandler {
+  private errorCount = 0;
+  private errorsByType = new Map<string, number>();
+  private errorsByMethod = new Map<string, number>();
+
+  /**
+   * Handle and enrich errors with context
+   */
+  async handleError(error: any, request: any, context: ErrorContext): Promise<Error> {
+    this.errorCount++;
+
+    const errorType = error.constructor.name;
+    this.errorsByType.set(errorType, (this.errorsByType.get(errorType) || 0) + 1);
+    this.errorsByMethod.set(context.method, (this.errorsByMethod.get(context.method) || 0) + 1);
+
+    // Create enriched error
+    const enrichedError = this.createEnrichedError(error, request, context);
+
+    // Log error with context
+    logger.error('Request processing error', {
+      error: enrichedError.message,
+      errorType,
+      method: context.method,
+      sessionId: context.sessionId,
+      requestId: context.requestId,
+      processingTime: Date.now() - context.startTime,
+      originalError: error.message,
+      stack: error.stack,
+    });
+
+    return enrichedError;
+  }
+
+  /**
+   * Create an enriched error with proper MCP formatting
+   */
+  private createEnrichedError(error: any, request: any, context: ErrorContext): Error {
+    let mcpError: McpError;
+
+    // Handle known error types using proper type checking
+    if (error.code && typeof error.code === 'number') {
+      // Already an MCP error
+      mcpError = {
+        code: error.code,
+        message: error.message,
+        data: error.data,
+      };
+    } else if (error instanceof McpValidationError) {
+      mcpError = {
+        code: -32602, // Invalid params
+        message: 'Request validation failed',
+        data: {
+          originalMessage: error.message,
+          details: error.details,
+        },
+      };
+    } else if (error instanceof McpTimeoutError) {
+      mcpError = {
+        code: -32603, // Internal error
+        message: 'Request timed out',
+        data: {
+          timeout: error.timeout,
+          method: context.method,
+        },
+      };
+    } else if (error instanceof McpMethodNotFoundError) {
+      mcpError = {
+        code: -32601, // Method not found
+        message: 'Method not found',
+        data: {
+          method: error.method || request.method,
+        },
+      };
+    } else if (error instanceof McpAuthenticationError) {
+      mcpError = {
+        code: -32600, // Invalid request
+        message: 'Unauthorized request',
+        data: {
+          sessionId: context.sessionId,
+        },
+      };
+    } else if (error instanceof McpRateLimitError) {
+      mcpError = {
+        code: -32603, // Internal error
+        message: 'Rate limit exceeded',
+        data: {
+          retryAfter: error.retryAfter || 60,
+        },
+      };
+    } else {
+      // Generic internal error
+      mcpError = {
+        code: -32603, // Internal error
+        message: 'Internal server error',
+        data: {
+          originalMessage: error.message,
+          type: error.constructor.name,
+        },
+      };
+    }
+
+    // Create final error object
+    const finalError = new Error(mcpError.message);
+    (finalError as any).code = mcpError.code;
+    (finalError as any).data = {
+      ...mcpError.data,
+      context: {
+        sessionId: context.sessionId,
+        requestId: context.requestId,
+        method: context.method,
+        timestamp: new Date().toISOString(),
+        processingTime: Date.now() - context.startTime,
+      },
+    };
+
+    return finalError;
+  }
+
+  /**
+   * Format error for MCP response
+   */
+  formatMcpError(error: any): McpError {
+    return {
+      code: error.code || -32603,
+      message: error.message || 'Internal server error',
+      data: error.data || null,
+    };
+  }
+
+  /**
+   * Check if error is recoverable
+   */
+  isRecoverableError(error: any): boolean {
+    if (!error.code) return false;
+
+    const recoverableCodes = [
+      -32602, // Invalid params - client can fix
+      -32601, // Method not found - client can fix
+      -32600, // Invalid request - client can fix
+    ];
+
+    return recoverableCodes.includes(error.code);
+  }
+
+  /**
+   * Get error statistics
+   */
+  getStats() {
+    return {
+      totalErrors: this.errorCount,
+      errorsByType: Object.fromEntries(this.errorsByType),
+      errorsByMethod: Object.fromEntries(this.errorsByMethod),
+      mostCommonError: this.getMostCommonError(),
+      errorRate: this.errorCount, // This would be divided by total requests in a real system
+    };
+  }
+
+  /**
+   * Get the most common error type
+   */
+  private getMostCommonError(): string | null {
+    if (this.errorsByType.size === 0) return null;
+
+    let maxCount = 0;
+    let mostCommon = '';
+
+    for (const [type, count] of this.errorsByType) {
+      if (count > maxCount) {
+        maxCount = count;
+        mostCommon = type;
+      }
+    }
+
+    return mostCommon;
+  }
+
+  /**
+   * Clear error statistics
+   */
+  clearStats(): void {
+    this.errorCount = 0;
+    this.errorsByType.clear();
+    this.errorsByMethod.clear();
+    logger.info('Error statistics cleared');
+  }
+}

package/src/middleware/index.ts

@@ -0,0 +1,112 @@
+// ABOUTME: Enhanced middleware for protocol-level validation, error handling, and timeouts
+// ABOUTME: Provides comprehensive request/response processing and error management
+
+import { logger } from '../logger.js';
+import { ErrorHandler } from './error-handler.js';
+import { TimeoutManager } from './timeout.js';
+import { RequestValidator } from './validator.js';
+
+export interface MiddlewareContext {
+  sessionId: string;
+  startTime: number;
+  requestId: string;
+  method: string;
+}
+
+export class ProtocolMiddleware {
+  private validator: RequestValidator;
+  private errorHandler: ErrorHandler;
+  private timeoutManager: TimeoutManager;
+
+  constructor() {
+    this.validator = new RequestValidator();
+    this.errorHandler = new ErrorHandler();
+    this.timeoutManager = new TimeoutManager();
+
+    logger.info('Protocol middleware initialized');
+  }
+
+  /**
+   * Process request through validation and preprocessing
+   */
+  async processRequest(request: any, context: MiddlewareContext): Promise<any> {
+    const startTime = Date.now();
+
+    try {
+      // 1. Validate request structure
+      await this.validator.validateRequest(request);
+
+      // 2. Set up timeout
+      const timeoutPromise = this.timeoutManager.createTimeout(context.method);
+
+      // 3. Process with timeout
+      const processedRequest = await Promise.race([
+        this.doProcessRequest(request, context),
+        timeoutPromise,
+      ]);
+
+      logger.debug('Request processed successfully', {
+        method: context.method,
+        sessionId: context.sessionId,
+        processingTime: Date.now() - startTime,
+      });
+
+      return processedRequest;
+    } catch (error) {
+      const processedError = await this.errorHandler.handleError(error, request, context);
+      throw processedError;
+    }
+  }
+
+  /**
+   * Process response through enrichment and validation
+   */
+  async processResponse(response: any, request: any, context: MiddlewareContext): Promise<any> {
+    try {
+      // Validate response structure
+      await this.validator.validateResponse(response, request.method);
+
+      // Add processing metadata
+      const enrichedResponse = {
+        ...response,
+        _processingTime: Date.now() - context.startTime,
+        _requestId: context.requestId,
+      };
+
+      return enrichedResponse;
+    } catch (error) {
+      const processedError = await this.errorHandler.handleError(error, request, context);
+      throw processedError;
+    }
+  }
+
+  private async doProcessRequest(request: any, context: MiddlewareContext): Promise<any> {
+    // Add request metadata
+    const enrichedRequest = {
+      ...request,
+      _metadata: {
+        requestId: context.requestId,
+        sessionId: context.sessionId,
+        timestamp: new Date().toISOString(),
+        processingStarted: context.startTime,
+      },
+    };
+
+    return enrichedRequest;
+  }
+
+  /**
+   * Get middleware statistics
+   */
+  getStats() {
+    return {
+      validator: this.validator.getStats(),
+      errorHandler: this.errorHandler.getStats(),
+      timeoutManager: this.timeoutManager.getStats(),
+    };
+  }
+}
+
+export { RequestValidator } from './validator.js';
+export { ErrorHandler } from './error-handler.js';
+export { TimeoutManager } from './timeout.js';