@myatkyawthu/mcp-connect 0.1.1

package/src/utils/configValidation.js

@@ -0,0 +1,381 @@
+/**
+ * Comprehensive configuration validation for MCP-Connect
+ */
+
+/**
+ * @typedef {Object} ValidationError
+ * @property {string} field - The field that has an error
+ * @property {string} message - Error message
+ * @property {any} [value] - The invalid value
+ * @property {string} [suggestion] - Suggestion for fixing the error
+ */
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} isValid - Whether the configuration is valid
+ * @property {ValidationError[]} errors - Array of validation errors
+ * @property {ValidationError[]} warnings - Array of validation warnings
+ */
+
+/**
+ * JSON Schema-like validation for MCP configuration
+ */
+export class ConfigValidator {
+  constructor() {
+    /** @type {ValidationError[]} */
+    this.errors = [];
+    /** @type {ValidationError[]} */
+    this.warnings = [];
+  }
+
+  /**
+   * Validate MCP configuration
+   * @param {any} config - Configuration to validate
+   * @returns {ValidationResult} Validation result
+   */
+  validate(config) {
+    this.errors = [];
+    this.warnings = [];
+
+    // Basic structure validation
+    this.validateBasicStructure(config);
+
+    if (this.errors.length === 0) {
+      // Detailed field validation
+      this.validateName(config.name);
+      this.validateVersion(config.version);
+      this.validateDescription(config.description);
+      this.validateTools(config.tools);
+    }
+
+    return {
+      isValid: this.errors.length === 0,
+      errors: this.errors,
+      warnings: this.warnings,
+    };
+  }
+
+  /**
+   * Add validation error
+   * @param {string} field - Field name
+   * @param {string} message - Error message
+   * @param {any} [value] - Invalid value
+   * @param {string} [suggestion] - Suggestion for fix
+   */
+  addError(field, message, value, suggestion) {
+    this.errors.push({ field, message, value, suggestion });
+  }
+
+  /**
+   * Add validation warning
+   * @param {string} field - Field name
+   * @param {string} message - Warning message
+   * @param {any} [value] - Value that triggered warning
+   * @param {string} [suggestion] - Suggestion for improvement
+   */
+  addWarning(field, message, value, suggestion) {
+    this.warnings.push({ field, message, value, suggestion });
+  }
+
+  /**
+   * Validate basic configuration structure
+   * @param {any} config - Configuration to validate
+   */
+  validateBasicStructure(config) {
+    if (!config || typeof config !== "object") {
+      this.addError("config", "Configuration must be an object", config, "Use defineMCP({ ... })");
+      return;
+    }
+
+    if (Array.isArray(config)) {
+      this.addError("config", "Configuration cannot be an array", config, "Use defineMCP({ ... }) instead of [...]");
+      return;
+    }
+
+    // Check for required fields
+    const requiredFields = ["name", "version", "tools"];
+    for (const field of requiredFields) {
+      if (!(field in config)) {
+        this.addError(field, `Required field "${field}" is missing`, undefined, `Add ${field}: "..."`);
+      }
+    }
+  }
+
+  /**
+   * Validate name field
+   * @param {any} name - Name to validate
+   */
+  validateName(name) {
+    if (name === undefined) return; // Already handled in basic structure
+
+    if (typeof name !== "string") {
+      this.addError("name", "Name must be a string", name, 'Use name: "My App"');
+      return;
+    }
+
+    if (name.trim() === "") {
+      this.addError("name", "Name cannot be empty", name, 'Use name: "My App"');
+      return;
+    }
+
+    if (name.length > 100) {
+      this.addWarning("name", "Name is very long (>100 chars)", name, "Consider a shorter name");
+    }
+
+    if (!/^[a-zA-Z0-9\s\-_\.]+$/.test(name)) {
+      this.addWarning("name", "Name contains special characters", name, "Use only letters, numbers, spaces, hyphens, underscores, and dots");
+    }
+  }
+
+  /**
+   * Validate version field
+   * @param {any} version - Version to validate
+   */
+  validateVersion(version) {
+    if (version === undefined) return; // Already handled in basic structure
+
+    if (typeof version !== "string") {
+      this.addError("version", "Version must be a string", version, 'Use version: "1.0.0"');
+      return;
+    }
+
+    if (version.trim() === "") {
+      this.addError("version", "Version cannot be empty", version, 'Use version: "1.0.0"');
+      return;
+    }
+
+    // Check for semantic versioning
+    const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9\-\.]+)?(\+[a-zA-Z0-9\-\.]+)?$/;
+    if (!semverRegex.test(version)) {
+      this.addWarning("version", "Version doesn't follow semantic versioning", version, 'Use format: "1.0.0"');
+    }
+  }
+
+  /**
+   * Validate description field
+   * @param {any} description - Description to validate
+   */
+  validateDescription(description) {
+    if (description === undefined) return; // Optional field
+
+    if (typeof description !== "string") {
+      this.addError("description", "Description must be a string", description, 'Use description: "My app description"');
+      return;
+    }
+
+    if (description.length > 500) {
+      this.addWarning("description", "Description is very long (>500 chars)", description, "Consider a shorter description");
+    }
+  }
+
+
+
+  /**
+   * Validate tools array
+   * @param {any} tools - Tools to validate
+   */
+  validateTools(tools) {
+    if (tools === undefined) return; // Already handled in basic structure
+
+    if (!Array.isArray(tools)) {
+      this.addError("tools", "Tools must be an array", tools, "Use tools: [...]");
+      return;
+    }
+
+    if (tools.length === 0) {
+      this.addError("tools", "At least one tool must be defined", tools, 'Add tools: [["myTool", handler]]');
+      return;
+    }
+
+    if (tools.length > 50) {
+      this.addWarning("tools", "Large number of tools (>50)", tools, "Consider grouping related functionality");
+    }
+
+    // Validate each tool
+    const toolNames = new Set();
+    tools.forEach((tool, index) => {
+      this.validateTool(tool, index, toolNames);
+    });
+  }
+
+  /**
+   * Validate individual tool
+   * @param {any} tool - Tool to validate
+   * @param {number} index - Tool index
+   * @param {Set<string>} toolNames - Set of existing tool names
+   */
+  validateTool(tool, index, toolNames) {
+    const fieldPrefix = `tools[${index}]`;
+
+    if (Array.isArray(tool)) {
+      // Tuple format: [name, handler]
+      if (tool.length !== 2) {
+        this.addError(fieldPrefix, "Tuple format must have exactly 2 elements [name, handler]", tool, '["toolName", handlerFunction]');
+        return;
+      }
+
+      const [name, handler] = tool;
+      this.validateToolName(name, `${fieldPrefix}.name`, toolNames);
+      this.validateToolHandler(handler, `${fieldPrefix}.handler`);
+    } else if (typeof tool === "object" && tool !== null) {
+      // Object format: { name, handler, description?, schema? }
+      this.validateToolName(tool.name, `${fieldPrefix}.name`, toolNames);
+      this.validateToolHandler(tool.handler, `${fieldPrefix}.handler`);
+      this.validateToolDescription(tool.description, `${fieldPrefix}.description`);
+      this.validateToolSchema(tool.schema, `${fieldPrefix}.schema`);
+
+      // Check for unknown properties
+      const knownProps = ["name", "handler", "description", "schema"];
+      const unknownProps = Object.keys(tool).filter(prop => !knownProps.includes(prop));
+      if (unknownProps.length > 0) {
+        this.addWarning(fieldPrefix, `Unknown properties: ${unknownProps.join(", ")}`, unknownProps, "Remove unknown properties");
+      }
+    } else {
+      this.addError(fieldPrefix, "Tool must be [name, handler] or {name, handler, ...}", tool, '["toolName", handler] or {name: "toolName", handler}');
+    }
+  }
+
+  /**
+   * Validate tool name
+   * @param {any} name - Tool name to validate
+   * @param {string} fieldPath - Field path for error reporting
+   * @param {Set<string>} toolNames - Set of existing tool names
+   */
+  validateToolName(name, fieldPath, toolNames) {
+    if (typeof name !== "string") {
+      this.addError(fieldPath, "Tool name must be a string", name, '"myToolName"');
+      return;
+    }
+
+    if (name.trim() === "") {
+      this.addError(fieldPath, "Tool name cannot be empty", name, '"myToolName"');
+      return;
+    }
+
+    const trimmedName = name.trim();
+    if (toolNames.has(trimmedName)) {
+      this.addError(fieldPath, `Duplicate tool name "${trimmedName}"`, name, "Each tool must have a unique name");
+      return;
+    }
+    toolNames.add(trimmedName);
+
+    // Validate name format
+    if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(trimmedName)) {
+      this.addWarning(fieldPath, "Tool name should start with letter and contain only letters, numbers, underscores", name, '"myToolName" or "my_tool_name"');
+    }
+
+    if (trimmedName.length > 50) {
+      this.addWarning(fieldPath, "Tool name is very long (>50 chars)", name, "Consider a shorter name");
+    }
+  }
+
+  /**
+   * Validate tool handler function
+   * @param {any} handler - Handler to validate
+   * @param {string} fieldPath - Field path for error reporting
+   */
+  validateToolHandler(handler, fieldPath) {
+    if (typeof handler !== "function") {
+      this.addError(fieldPath, "Tool handler must be a function", typeof handler, "async (args) => { ... }");
+      return;
+    }
+
+    // Check if it's an async function or returns a promise
+    const isAsync = handler.constructor.name === "AsyncFunction";
+    const handlerString = handler.toString();
+
+    if (!isAsync && !handlerString.includes("Promise") && !handlerString.includes("await")) {
+      this.addWarning(fieldPath, "Consider making tool handler async", undefined, "async (args) => { ... }");
+    }
+  }
+
+  /**
+   * Validate tool description
+   * @param {any} description - Description to validate
+   * @param {string} fieldPath - Field path for error reporting
+   */
+  validateToolDescription(description, fieldPath) {
+    if (description === undefined) return; // Optional
+
+    if (typeof description !== "string") {
+      this.addError(fieldPath, "Tool description must be a string", description, '"Description of what this tool does"');
+      return;
+    }
+
+    if (description.length > 200) {
+      this.addWarning(fieldPath, "Tool description is very long (>200 chars)", description, "Consider a shorter description");
+    }
+  }
+
+  /**
+   * Validate tool schema
+   * @param {any} schema - Schema to validate
+   * @param {string} fieldPath - Field path for error reporting
+   */
+  validateToolSchema(schema, fieldPath) {
+    if (schema === undefined) return; // Optional
+
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+      this.addError(fieldPath, "Tool schema must be an object", schema, "{ type: 'object', properties: {...} }");
+      return;
+    }
+
+    // Basic JSON Schema validation
+    if (schema.type && typeof schema.type !== "string") {
+      this.addError(`${fieldPath}.type`, "Schema type must be a string", schema.type, '"object"');
+    }
+
+    if (schema.properties && (typeof schema.properties !== "object" || Array.isArray(schema.properties))) {
+      this.addError(`${fieldPath}.properties`, "Schema properties must be an object", schema.properties, "{ prop1: { type: 'string' } }");
+    }
+
+    if (schema.required && !Array.isArray(schema.required)) {
+      this.addError(`${fieldPath}.required`, "Schema required must be an array", schema.required, '["prop1", "prop2"]');
+    }
+  }
+}
+
+/**
+ * Validate MCP configuration with detailed error reporting
+ * @param {any} config - Configuration to validate
+ * @returns {ValidationResult} Validation result
+ */
+export function validateConfig(config) {
+  const validator = new ConfigValidator();
+  return validator.validate(config);
+}
+
+/**
+ * Format validation errors for user-friendly display
+ * @param {ValidationResult} result - Validation result to format
+ * @returns {string} Formatted error message
+ */
+export function formatValidationErrors(result) {
+  const lines = [];
+
+  if (result.errors.length > 0) {
+    lines.push("❌ Configuration Errors:");
+    result.errors.forEach((error, index) => {
+      lines.push(`  ${index + 1}. ${error.field}: ${error.message}`);
+      if (error.value !== undefined) {
+        lines.push(`     Current value: ${JSON.stringify(error.value)}`);
+      }
+      if (error.suggestion) {
+        lines.push(`     Suggestion: ${error.suggestion}`);
+      }
+    });
+  }
+
+  if (result.warnings.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("⚠️  Configuration Warnings:");
+    result.warnings.forEach((warning, index) => {
+      lines.push(`  ${index + 1}. ${warning.field}: ${warning.message}`);
+      if (warning.suggestion) {
+        lines.push(`     Suggestion: ${warning.suggestion}`);
+      }
+    });
+  }
+
+  return lines.join("\n");
+}

package/src/utils/logger.js

@@ -0,0 +1,290 @@
+/**
+ * Enhanced structured logger for MCP-Connect
+ */
+
+/**
+ * @typedef {'debug'|'info'|'warn'|'error'} LogLevel
+ */
+
+/**
+ * @typedef {Object} LogContext
+ * @property {string} timestamp - ISO timestamp
+ * @property {LogLevel} level - Log level
+ * @property {string} message - Log message
+ * @property {any} [data] - Additional data
+ * @property {number} [duration] - Duration in milliseconds
+ * @property {string} [toolName] - Tool name
+ * @property {string} [requestId] - Request ID
+ */
+
+/**
+ * @typedef {Object} LogMeta
+ * @property {number} [duration] - Duration in milliseconds
+ * @property {string} [toolName] - Tool name
+ * @property {string} [requestId] - Request ID
+ */
+
+class MCPLogger {
+  constructor() {
+    /** @type {LogLevel} */
+    this.logLevel = 'info';
+    /** @type {boolean} */
+    this.debugMode = process.env.MCP_DEBUG === "1" || process.env.MCP_DEBUG === "true";
+    /** @type {boolean} */
+    this.performanceTracking = process.env.MCP_PERF === "1" || process.env.MCP_PERF === "true" || this.debugMode;
+
+    // Set log level based on environment
+    if (this.debugMode) {
+      this.logLevel = "debug";
+    } else if (process.env.MCP_LOG_LEVEL) {
+      this.logLevel = /** @type {LogLevel} */ (process.env.MCP_LOG_LEVEL);
+    } else {
+      this.logLevel = "info";
+    }
+  }
+
+  /**
+   * Check if we should log at this level
+   * @param {LogLevel} level - Log level to check
+   * @returns {boolean} Whether to log
+   */
+  shouldLog(level) {
+    /** @type {Record<LogLevel, number>} */
+    const levels = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+    };
+    return levels[level] >= levels[this.logLevel];
+  }
+
+  /**
+   * Format log message
+   * @param {LogContext} context - Log context
+   * @returns {string} Formatted log message
+   */
+  formatLog(context) {
+    const { timestamp, level, message, duration, toolName, requestId } = context;
+
+    let logMessage = `[MCP-${level.toUpperCase()}] ${timestamp} ${message}`;
+
+    if (toolName) {
+      logMessage += ` [tool:${toolName}]`;
+    }
+
+    if (requestId) {
+      logMessage += ` [req:${requestId}]`;
+    }
+
+    if (duration !== undefined) {
+      logMessage += ` (${duration}ms)`;
+    }
+
+    return logMessage;
+  }
+
+  /**
+   * Internal log method
+   * @param {LogLevel} level - Log level
+   * @param {string} message - Log message
+   * @param {any} [data] - Additional data
+   * @param {LogMeta} [meta] - Metadata
+   */
+  log(level, message, data, meta) {
+    if (!this.shouldLog(level)) return;
+
+    /** @type {LogContext} */
+    const context = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      data,
+      ...meta,
+    };
+
+    const logMessage = this.formatLog(context);
+
+    // Output to stderr (MCP requirement - stdout is reserved for JSON protocol)
+    const output = console.error;
+
+    if (data && this.debugMode) {
+      output(logMessage);
+      output("Data:", typeof data === "string" ? data : JSON.stringify(data, null, 2));
+    } else {
+      output(logMessage);
+    }
+  }
+
+  /**
+   * Log debug message
+   * @param {string} message - Debug message
+   * @param {any} [data] - Additional data
+   * @param {LogMeta} [meta] - Metadata
+   */
+  debug(message, data, meta) {
+    this.log("debug", message, data, meta);
+  }
+
+  /**
+   * Log info message
+   * @param {string} message - Info message
+   * @param {any} [data] - Additional data
+   * @param {LogMeta} [meta] - Metadata
+   */
+  info(message, data, meta) {
+    this.log("info", message, data, meta);
+  }
+
+  /**
+   * Log warning message
+   * @param {string} message - Warning message
+   * @param {any} [data] - Additional data
+   * @param {LogMeta} [meta] - Metadata
+   */
+  warn(message, data, meta) {
+    this.log("warn", message, data, meta);
+  }
+
+  /**
+   * Log error message
+   * @param {string} message - Error message
+   * @param {any} [error] - Error object or data
+   * @param {LogMeta} [meta] - Metadata
+   */
+  error(message, error, meta) {
+    this.log("error", message, error, meta);
+  }
+
+  /**
+   * Start performance timer
+   * @param {string} operation - Operation name
+   * @returns {Function} Function to call when operation completes
+   */
+  startTimer(operation) {
+    if (!this.performanceTracking) {
+      return () => { }; // No-op if performance tracking disabled
+    }
+
+    const startTime = Date.now();
+    return () => {
+      const duration = Date.now() - startTime;
+      this.debug(`${operation} completed`, undefined, { duration });
+      return duration;
+    };
+  }
+
+  /**
+   * Time an async operation
+   * @template T
+   * @param {string} operation - Operation name
+   * @param {Promise<T>} promise - Promise to time
+   * @param {string} [toolName] - Tool name
+   * @returns {Promise<T>} The original promise
+   */
+  timeAsync(operation, promise, toolName) {
+    if (!this.performanceTracking) {
+      return promise;
+    }
+
+    const startTime = Date.now();
+    return promise
+      .then((result) => {
+        const duration = Date.now() - startTime;
+        this.info(`${operation} completed successfully`, undefined, { duration, toolName });
+        return result;
+      })
+      .catch((error) => {
+        const duration = Date.now() - startTime;
+        this.error(`${operation} failed`, error, { duration, toolName });
+        throw error;
+      });
+  }
+
+  /**
+   * Trace MCP request
+   * @param {string} method - MCP method
+   * @param {any} [params] - Request parameters
+   * @param {string} [requestId] - Request ID
+   */
+  traceRequest(method, params, requestId) {
+    this.debug(`MCP Request: ${method}`, params, { requestId });
+  }
+
+  /**
+   * Trace MCP response
+   * @param {string} method - MCP method
+   * @param {any} [result] - Response result
+   * @param {string} [requestId] - Request ID
+   */
+  traceResponse(method, result, requestId) {
+    this.debug(`MCP Response: ${method}`, result, { requestId });
+  }
+
+  /**
+   * Trace MCP error
+   * @param {string} method - MCP method
+   * @param {any} error - Error object
+   * @param {string} [requestId] - Request ID
+   */
+  traceError(method, error, requestId) {
+    this.error(`MCP Error: ${method}`, error, { requestId });
+  }
+
+  /**
+   * Log server startup
+   * @param {string} serverName - Server name
+   * @param {string} transport - Transport type
+   * @param {number} toolCount - Number of tools
+   */
+  serverStarted(serverName, transport, toolCount) {
+    this.info(`MCP server "${serverName}" started`, {
+      transport,
+      toolCount,
+      debugMode: this.debugMode,
+      performanceTracking: this.performanceTracking,
+    });
+  }
+
+  /**
+   * Log server shutdown
+   * @param {string} reason - Shutdown reason
+   */
+  serverShutdown(reason) {
+    this.info(`MCP server shutting down: ${reason}`);
+  }
+
+  /**
+   * Log tool execution start
+   * @param {string} toolName - Tool name
+   * @param {any} args - Tool arguments
+   * @param {string} [requestId] - Request ID
+   */
+  toolExecutionStart(toolName, args, requestId) {
+    this.debug(`Tool execution started: ${toolName}`, this.debugMode ? args : undefined, { toolName, requestId });
+  }
+
+  /**
+   * Log tool execution completion
+   * @param {string} toolName - Tool name
+   * @param {number} duration - Execution duration
+   * @param {string} [requestId] - Request ID
+   */
+  toolExecutionEnd(toolName, duration, requestId) {
+    this.info(`Tool execution completed: ${toolName}`, undefined, { toolName, duration, requestId });
+  }
+
+  /**
+   * Log tool execution error
+   * @param {string} toolName - Tool name
+   * @param {any} error - Error object
+   * @param {number} duration - Execution duration
+   * @param {string} [requestId] - Request ID
+   */
+  toolExecutionError(toolName, error, duration, requestId) {
+    this.error(`Tool execution failed: ${toolName}`, error, { toolName, duration, requestId });
+  }
+}
+
+// Export singleton instance
+export const logger = new MCPLogger();