converse-mcp-server 1.0.1

package/src/utils/logger.js

@@ -0,0 +1,450 @@
+/**
+ * Logger Utility
+ *
+ * Structured logging system with different log levels and development/production modes.
+ * Provides consistent logging interface across all modules with proper error handling.
+ */
+
+import { inspect } from 'util';
+
+/**
+ * Check if console output should be suppressed
+ * @returns {boolean} True if console output should be suppressed
+ */
+function shouldSuppressConsole() {
+  return process.env.LOG_LEVEL === 'silent' || 
+         process.env.NODE_ENV === 'test' ||
+         process.env.MCP_TRANSPORT === 'stdio';
+}
+
+/**
+ * Log levels in order of severity (lower number = higher severity)
+ */
+const LOG_LEVELS = {
+  silent: -1,
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+  trace: 4
+};
+
+/**
+ * Logger configuration
+ */
+let loggerConfig = {
+  level: process.env.LOG_LEVEL || 'info',
+  isDevelopment: process.env.NODE_ENV === 'development',
+  enableColors: process.env.NODE_ENV !== 'production',
+  enableTimestamps: true,
+  enableStackTrace: process.env.NODE_ENV === 'development'
+};
+
+/**
+ * ANSI color codes for console output
+ */
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m'
+};
+
+/**
+ * Log level color mapping
+ */
+const LEVEL_COLORS = {
+  error: COLORS.red,
+  warn: COLORS.yellow,
+  info: COLORS.green,
+  debug: COLORS.blue,
+  trace: COLORS.gray
+};
+
+/**
+ * Format timestamp for log entries
+ * @returns {string} Formatted timestamp
+ */
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+
+/**
+ * Format log level for display
+ * @param {string} level - Log level
+ * @returns {string} Formatted log level
+ */
+function formatLevel(level) {
+  const upperLevel = level.toUpperCase().padEnd(5);
+  if (loggerConfig.enableColors) {
+    const color = LEVEL_COLORS[level] || COLORS.white;
+    return `${color}${upperLevel}${COLORS.reset}`;
+  }
+  return upperLevel;
+}
+
+/**
+ * Format context information
+ * @param {string} module - Module name
+ * @param {string} operation - Operation name
+ * @returns {string} Formatted context
+ */
+function formatContext(module, operation) {
+  if (!module && !operation) return '';
+  
+  const context = [module, operation].filter(Boolean).join(':');
+  if (loggerConfig.enableColors) {
+    return `${COLORS.dim}[${context}]${COLORS.reset}`;
+  }
+  return `[${context}]`;
+}
+
+/**
+ * Format error objects for logging
+ * @param {Error} error - Error object
+ * @returns {object} Formatted error information
+ */
+function formatError(error) {
+  if (!(error instanceof Error)) {
+    return { error: error };
+  }
+
+  const errorInfo = {
+    name: error.name,
+    message: error.message,
+    code: error.code,
+    details: error.details
+  };
+
+  if (loggerConfig.enableStackTrace && error.stack) {
+    errorInfo.stack = error.stack;
+  }
+
+  return errorInfo;
+}
+
+/**
+ * Format log data for output
+ * @param {any} data - Data to format
+ * @returns {string} Formatted data
+ */
+function formatData(data) {
+  if (data === null || data === undefined) {
+    return '';
+  }
+
+  if (typeof data === 'string') {
+    return data;
+  }
+
+  if (data instanceof Error) {
+    const errorInfo = formatError(data);
+    if (loggerConfig.isDevelopment) {
+      return inspect(errorInfo, { depth: 3, colors: loggerConfig.enableColors });
+    }
+    return JSON.stringify(errorInfo);
+  }
+
+  if (typeof data === 'object') {
+    if (loggerConfig.isDevelopment) {
+      return inspect(data, { depth: 2, colors: loggerConfig.enableColors });
+    }
+    return JSON.stringify(data);
+  }
+
+  return String(data);
+}
+
+/**
+ * Check if log level should be output
+ * @param {string} level - Log level to check
+ * @returns {boolean} True if should log
+ */
+function shouldLog(level) {
+  const currentLevel = LOG_LEVELS[loggerConfig.level] || LOG_LEVELS.info;
+  const messageLevel = LOG_LEVELS[level] || LOG_LEVELS.info;
+  return messageLevel <= currentLevel;
+}
+
+/**
+ * Core logging function
+ * @param {string} level - Log level
+ * @param {string} message - Log message
+ * @param {object} metadata - Additional metadata
+ */
+function log(level, message, metadata = {}) {
+  if (!shouldLog(level)) {
+    return;
+  }
+
+  const timestamp = loggerConfig.enableTimestamps ? formatTimestamp() : null;
+  const formattedLevel = formatLevel(level);
+  const context = formatContext(metadata.module, metadata.operation);
+  
+  // Build log parts
+  const parts = [
+    timestamp,
+    formattedLevel,
+    context,
+    message
+  ].filter(Boolean);
+
+  // Output main log line
+  const logLine = parts.join(' ');
+  
+  if (!shouldSuppressConsole()) {
+    if (level === 'error') {
+      console.error(logLine);
+    } else {
+      console.log(logLine);
+    }
+  }
+
+  // Output additional data if provided
+  if (metadata.data !== undefined) {
+    const formattedData = formatData(metadata.data);
+    if (formattedData) {
+      if (!shouldSuppressConsole()) {
+        if (level === 'error') {
+          console.error(formattedData);
+        } else {
+          console.log(formattedData);
+        }
+      }
+    }
+  }
+
+  // Output error details if provided
+  if (metadata.error && metadata.error instanceof Error) {
+    const errorInfo = formatError(metadata.error);
+    const formattedError = formatData(errorInfo);
+    if (level === 'error') {
+      if (!shouldSuppressConsole()) {
+        console.error(formattedError);
+      }
+    } else {
+      if (!shouldSuppressConsole()) {
+        console.log(formattedError);
+      }
+    }
+  }
+}
+
+/**
+ * Create logger instance for a specific module
+ * @param {string} moduleName - Name of the module
+ * @returns {object} Logger instance
+ */
+export function createLogger(moduleName) {
+  return {
+    /**
+     * Log error message
+     * @param {string} message - Error message
+     * @param {object} metadata - Additional metadata
+     */
+    error(message, metadata = {}) {
+      log('error', message, { ...metadata, module: moduleName });
+    },
+
+    /**
+     * Log warning message
+     * @param {string} message - Warning message
+     * @param {object} metadata - Additional metadata
+     */
+    warn(message, metadata = {}) {
+      log('warn', message, { ...metadata, module: moduleName });
+    },
+
+    /**
+     * Log info message
+     * @param {string} message - Info message
+     * @param {object} metadata - Additional metadata
+     */
+    info(message, metadata = {}) {
+      log('info', message, { ...metadata, module: moduleName });
+    },
+
+    /**
+     * Log debug message
+     * @param {string} message - Debug message
+     * @param {object} metadata - Additional metadata
+     */
+    debug(message, metadata = {}) {
+      log('debug', message, { ...metadata, module: moduleName });
+    },
+
+    /**
+     * Log trace message
+     * @param {string} message - Trace message
+     * @param {object} metadata - Additional metadata
+     */
+    trace(message, metadata = {}) {
+      log('trace', message, { ...metadata, module: moduleName });
+    },
+
+    /**
+     * Log with custom operation context
+     * @param {string} operation - Operation name
+     * @returns {object} Logger with operation context
+     */
+    operation(operation) {
+      return {
+        error: (message, metadata = {}) => log('error', message, { ...metadata, module: moduleName, operation }),
+        warn: (message, metadata = {}) => log('warn', message, { ...metadata, module: moduleName, operation }),
+        info: (message, metadata = {}) => log('info', message, { ...metadata, module: moduleName, operation }),
+        debug: (message, metadata = {}) => log('debug', message, { ...metadata, module: moduleName, operation }),
+        trace: (message, metadata = {}) => log('trace', message, { ...metadata, module: moduleName, operation })
+      };
+    }
+  };
+}
+
+/**
+ * Configure logger settings
+ * @param {object} config - Logger configuration
+ */
+export function configureLogger(config) {
+  loggerConfig = { ...loggerConfig, ...config };
+}
+
+/**
+ * Get current logger configuration
+ * @returns {object} Current configuration
+ */
+export function getLoggerConfig() {
+  return { ...loggerConfig };
+}
+
+/**
+ * Global logger instance
+ */
+export const logger = createLogger('global');
+
+/**
+ * Create structured error for logging
+ * @param {string} message - Error message
+ * @param {string} code - Error code
+ * @param {object} details - Error details
+ * @param {Error} originalError - Original error
+ * @returns {Error} Structured error
+ */
+export function createStructuredError(message, code = 'UNKNOWN_ERROR', details = {}, originalError = null) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  
+  if (originalError) {
+    error.originalError = originalError;
+    error.cause = originalError;
+  }
+  
+  return error;
+}
+
+/**
+ * Log performance timing
+ * @param {string} operation - Operation name
+ * @param {number} startTime - Start time in milliseconds
+ * @param {object} metadata - Additional metadata
+ */
+export function logTiming(operation, startTime, metadata = {}) {
+  const duration = Date.now() - startTime;
+  
+  if (duration > 1000) {
+    logger.warn(`Slow operation: ${operation}`, { 
+      ...metadata, 
+      data: { duration: `${duration}ms` } 
+    });
+  } else if (duration > 100) {
+    logger.info(`Operation completed: ${operation}`, { 
+      ...metadata, 
+      data: { duration: `${duration}ms` } 
+    });
+  } else {
+    logger.debug(`Operation completed: ${operation}`, { 
+      ...metadata, 
+      data: { duration: `${duration}ms` } 
+    });
+  }
+}
+
+/**
+ * Performance timer utility
+ * @param {string} operation - Operation name
+ * @param {string} module - Module name
+ * @returns {function} Function to end timing
+ */
+export function startTimer(operation, module = 'timer') {
+  const startTime = Date.now();
+  const moduleLogger = createLogger(module);
+  
+  moduleLogger.debug(`Starting: ${operation}`);
+  
+  return (result = 'completed', metadata = {}) => {
+    const duration = Date.now() - startTime;
+    moduleLogger.debug(`${result}: ${operation}`, { 
+      ...metadata, 
+      data: { duration: `${duration}ms` } 
+    });
+    return duration;
+  };
+}
+
+/**
+ * Log function entry and exit (for debugging)
+ * @param {string} functionName - Function name
+ * @param {string} module - Module name
+ * @returns {function} Function to end logging
+ */
+export function logFunction(functionName, module = 'function') {
+  const moduleLogger = createLogger(module);
+  const startTime = Date.now();
+  
+  moduleLogger.trace(`Entering: ${functionName}`);
+  
+  return (result = 'completed', error = null) => {
+    const duration = Date.now() - startTime;
+    
+    if (error) {
+      moduleLogger.trace(`Exiting with error: ${functionName}`, { 
+        data: { duration: `${duration}ms` },
+        error 
+      });
+    } else {
+      moduleLogger.trace(`Exiting: ${functionName}`, { 
+        data: { duration: `${duration}ms`, result } 
+      });
+    }
+  };
+}
+
+/**
+ * Express error for consistent error logging across modules
+ */
+export class LoggedError extends Error {
+  constructor(message, code = 'LOGGED_ERROR', details = {}, logger = null) {
+    super(message);
+    this.name = 'LoggedError';
+    this.code = code;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+    
+    // Log the error immediately
+    if (logger) {
+      logger.error(`${this.name}: ${message}`, { 
+        data: { code, details } 
+      });
+    } else {
+      global.logger?.error(`${this.name}: ${message}`, { 
+        data: { code, details } 
+      });
+    }
+  }
+}

package/src/utils/tokenLimiter.js

@@ -0,0 +1,217 @@
+/**
+ * Token Limiter Utility
+ *
+ * Implements token limiting for MCP tool responses to prevent excessive output.
+ * Based on the Python implementation's token limiting functionality.
+ */
+
+import { createLogger } from './logger.js';
+
+const logger = createLogger('tokenLimiter');
+
+/**
+ * Simple token estimation based on character count
+ * Rough approximation: 1 token ≈ 4 characters for English text
+ * @param {string} text - Text to estimate tokens for
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  if (!text || typeof text !== 'string') {
+    return 0;
+  }
+  // Average of 4 characters per token for English text
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Truncates text to fit within token limit while preserving structure
+ * @param {string} text - Text to truncate
+ * @param {number} maxTokens - Maximum allowed tokens
+ * @returns {object} Object with truncated text and metadata
+ */
+function truncateToTokenLimit(text, maxTokens) {
+  if (!text || typeof text !== 'string') {
+    return {
+      content: text || '',
+      truncated: false,
+      originalTokens: 0,
+      finalTokens: 0,
+      truncationReason: null
+    };
+  }
+
+  const originalTokens = estimateTokens(text);
+  
+  if (originalTokens <= maxTokens) {
+    return {
+      content: text,
+      truncated: false,
+      originalTokens,
+      finalTokens: originalTokens,
+      truncationReason: null
+    };
+  }
+
+  // Calculate maximum characters to keep (with some buffer for safety)
+  const maxChars = Math.floor(maxTokens * 3.8); // Slightly less than 4 chars per token
+  
+  // Find a good truncation point (prefer complete sentences or paragraphs)
+  let truncationPoint = maxChars;
+  const text_substring = text.substring(0, maxChars + 200); // Look ahead a bit
+  
+  // Try to find sentence endings
+  const sentenceEndings = ['. ', '.\n', '!\n', '?\n', '! ', '? '];
+  let bestTruncation = maxChars;
+  
+  for (const ending of sentenceEndings) {
+    const lastIndex = text_substring.lastIndexOf(ending);
+    if (lastIndex > maxChars * 0.8 && lastIndex < maxChars) {
+      bestTruncation = lastIndex + ending.length;
+      break;
+    }
+  }
+  
+  // If no good sentence ending, try paragraph breaks
+  if (bestTruncation === maxChars) {
+    const paragraphBreak = text_substring.lastIndexOf('\n\n');
+    if (paragraphBreak > maxChars * 0.8 && paragraphBreak < maxChars) {
+      bestTruncation = paragraphBreak + 2;
+    }
+  }
+  
+  // If still no good break, try line breaks
+  if (bestTruncation === maxChars) {
+    const lineBreak = text_substring.lastIndexOf('\n');
+    if (lineBreak > maxChars * 0.9 && lineBreak < maxChars) {
+      bestTruncation = lineBreak + 1;
+    }
+  }
+  
+  const truncatedText = text.substring(0, bestTruncation);
+  const finalTokens = estimateTokens(truncatedText);
+  
+  const truncationMessage = `\n\n[Response truncated due to length. Original: ~${originalTokens} tokens, Truncated: ~${finalTokens} tokens, Limit: ${maxTokens} tokens]`;
+  
+  return {
+    content: truncatedText + truncationMessage,
+    truncated: true,
+    originalTokens,
+    finalTokens: finalTokens + estimateTokens(truncationMessage),
+    truncationReason: 'Exceeded maximum token limit'
+  };
+}
+
+/**
+ * Validates and applies token limits to MCP tool responses
+ * @param {any} response - The response content to validate
+ * @param {number} maxTokens - Maximum allowed tokens
+ * @returns {object} Processed response with token limiting applied
+ */
+export function applyTokenLimit(response, maxTokens) {
+  if (!maxTokens || maxTokens <= 0) {
+    return {
+      content: response,
+      metadata: {
+        tokenLimitApplied: false,
+        originalTokens: 0,
+        finalTokens: 0
+      }
+    };
+  }
+
+  // Handle different response types
+  let textContent = '';
+  let originalResponse = response;
+  
+  if (typeof response === 'string') {
+    textContent = response;
+  } else if (response && typeof response === 'object') {
+    // Handle structured responses (like consensus tool)
+    if (response.content && typeof response.content === 'string') {
+      textContent = response.content;
+    } else {
+      // For complex objects, serialize to JSON for token counting
+      textContent = JSON.stringify(response, null, 2);
+    }
+  } else {
+    // Convert other types to string
+    textContent = String(response);
+  }
+
+  const result = truncateToTokenLimit(textContent, maxTokens);
+  
+  if (result.truncated) {
+    logger.warn('Response truncated due to token limit', {
+      originalTokens: result.originalTokens,
+      finalTokens: result.finalTokens,
+      maxTokens,
+      truncationRatio: (result.finalTokens / result.originalTokens).toFixed(3)
+    });
+  }
+
+  // Return the processed response
+  if (typeof originalResponse === 'string') {
+    return {
+      content: result.content,
+      metadata: {
+        tokenLimitApplied: result.truncated,
+        originalTokens: result.originalTokens,
+        finalTokens: result.finalTokens,
+        truncationReason: result.truncationReason
+      }
+    };
+  } else if (originalResponse && typeof originalResponse === 'object') {
+    // For structured responses, update the content field
+    return {
+      ...originalResponse,
+      content: result.content,
+      metadata: {
+        ...originalResponse.metadata,
+        tokenLimitApplied: result.truncated,
+        originalTokens: result.originalTokens,
+        finalTokens: result.finalTokens,
+        truncationReason: result.truncationReason
+      }
+    };
+  } else {
+    return {
+      content: result.content,
+      metadata: {
+        tokenLimitApplied: result.truncated,
+        originalTokens: result.originalTokens,
+        finalTokens: result.finalTokens,
+        truncationReason: result.truncationReason
+      }
+    };
+  }
+}
+
+/**
+ * Gets the configured token limit from environment or config
+ * @param {object} config - Configuration object
+ * @returns {number} Maximum token limit
+ */
+export function getTokenLimit(config) {
+  if (config && config.mcp && config.mcp.max_mcp_output_tokens) {
+    return config.mcp.max_mcp_output_tokens;
+  }
+  
+  // Fallback to environment variable
+  const envLimit = process.env.MAX_MCP_OUTPUT_TOKENS;
+  if (envLimit) {
+    const limit = parseInt(envLimit, 10);
+    if (!isNaN(limit) && limit > 0) {
+      return limit;
+    }
+  }
+  
+  // Default limit
+  return 25000;
+}
+
+/**
+ * Estimates token count for a given text (exported for testing)
+ * @param {string} text - Text to estimate
+ * @returns {number} Estimated token count
+ */
+export { estimateTokens };