mcp-wordpress 1.1.2

package/src/utils/debug.ts

@@ -0,0 +1,258 @@
+/**
+ * Debug Utility for MCP Server
+ * 
+ * This module provides debug logging that only outputs when DEBUG mode is enabled.
+ * This prevents console.log from interfering with MCP STDIO communication.
+ */
+
+import type { DebugInfo } from '../types/index.js';
+
+// Log levels
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+// Logger interface
+export interface Logger {
+  log(...args: any[]): void;
+  info(...args: any[]): void;
+  warn(...args: any[]): void;
+  error(...args: any[]): void;
+}
+
+// Enhanced logger with structured logging
+export interface StructuredLogger extends Logger {
+  logStructured(info: DebugInfo): void;
+  child(context: Record<string, any>): StructuredLogger;
+}
+
+// Check if debug mode is enabled
+const isDebugMode = (): boolean => 
+  process.env.DEBUG === 'true' || 
+  process.env.NODE_ENV === 'development';
+
+// Get current timestamp
+const getTimestamp = (): string => new Date().toISOString();
+
+// Format log message with timestamp and level
+const formatMessage = (level: LogLevel, args: any[]): string => {
+  const timestamp = getTimestamp();
+  const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+  return `${prefix} ${args.map(arg => 
+    typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg)
+  ).join(' ')}`;
+};
+
+// Handle circular references in objects
+const safeStringify = (obj: any): string => {
+  try {
+    return JSON.stringify(obj, (key, value) => {
+      if (value instanceof Error) {
+        return {
+          name: value.name,
+          message: value.message,
+          stack: value.stack
+        };
+      }
+      return value;
+    }, 2);
+  } catch (error) {
+    return '[Object with circular reference]';
+  }
+};
+
+/**
+ * Debug logger that only outputs in debug mode
+ */
+export const debug: Logger = {
+  log: (...args: any[]): void => {
+    if (isDebugMode()) {
+      console.error(formatMessage('debug', args)); // Use stderr for debug to avoid STDIO interference
+    }
+  },
+  
+  info: (...args: any[]): void => {
+    if (isDebugMode()) {
+      console.error(formatMessage('info', args));
+    }
+  },
+  
+  warn: (...args: any[]): void => {
+    if (isDebugMode()) {
+      console.error(formatMessage('warn', args));
+    }
+  },
+  
+  error: (...args: any[]): void => {
+    if (isDebugMode()) {
+      console.error(formatMessage('error', args));
+    }
+  }
+};
+
+/**
+ * Silent logger for production use
+ */
+export const silent: Logger = {
+  log: (): void => {},
+  warn: (): void => {},
+  error: (): void => {},
+  info: (): void => {}
+};
+
+/**
+ * Enhanced structured logger
+ */
+class StructuredLoggerImpl implements StructuredLogger {
+  private context: Record<string, any>;
+  private enabled: boolean;
+
+  constructor(context: Record<string, any> = {}, enabled = isDebugMode()) {
+    this.context = context;
+    this.enabled = enabled;
+  }
+
+  private output(level: LogLevel, args: any[]): void {
+    if (!this.enabled) return;
+
+    const debugInfo: DebugInfo = {
+      timestamp: Date.now(),
+      level,
+      message: args.map(arg => 
+        typeof arg === 'object' ? safeStringify(arg) : String(arg)
+      ).join(' '),
+      ...(Object.keys(this.context).length > 0 && { context: this.context })
+    };
+
+    console.error(safeStringify(debugInfo));
+  }
+
+  log(...args: any[]): void {
+    this.output('debug', args);
+  }
+
+  info(...args: any[]): void {
+    this.output('info', args);
+  }
+
+  warn(...args: any[]): void {
+    this.output('warn', args);
+  }
+
+  error(...args: any[]): void {
+    this.output('error', args);
+  }
+
+  logStructured(info: DebugInfo): void {
+    if (!this.enabled) return;
+    
+    const enhancedInfo: DebugInfo = {
+      ...info,
+      context: { ...this.context, ...info.context }
+    };
+    
+    console.error(safeStringify(enhancedInfo));
+  }
+
+  child(context: Record<string, any>): StructuredLogger {
+    return new StructuredLoggerImpl(
+      { ...this.context, ...context },
+      this.enabled
+    );
+  }
+}
+
+/**
+ * Create a structured logger instance
+ */
+export const createStructuredLogger = (context: Record<string, any> = {}): StructuredLogger => {
+  return new StructuredLoggerImpl(context);
+};
+
+/**
+ * Default logger instance
+ */
+export const logger: Logger = debug;
+
+/**
+ * Create a logger with context
+ */
+export const createLogger = (context: Record<string, any> = {}): StructuredLogger => {
+  return createStructuredLogger(context);
+};
+
+/**
+ * Performance measurement utility
+ */
+export interface PerformanceTimer {
+  end(): number;
+  endWithLog(message?: string): number;
+}
+
+export const startTimer = (label?: string): PerformanceTimer => {
+  const start = Date.now();
+  
+  return {
+    end(): number {
+      return Date.now() - start;
+    },
+    
+    endWithLog(message = 'Operation'): number {
+      const duration = Date.now() - start;
+      debug.info(`${message} completed in ${duration}ms${label ? ` [${label}]` : ''}`);
+      return duration;
+    }
+  };
+};
+
+/**
+ * Log error with stack trace
+ */
+export const logError = (error: Error | string, context?: Record<string, any>): void => {
+  if (typeof error === 'string') {
+    debug.error(error, context);
+  } else {
+    debug.error(`${error.name}: ${error.message}`, {
+      stack: error.stack,
+      ...context
+    });
+  }
+};
+
+/**
+ * Conditional logging
+ */
+export const logIf = (condition: boolean, level: LogLevel = 'debug') => {
+  if (!condition) return silent;
+  
+  const loggers = {
+    log: debug.log,
+    info: debug.info,
+    warn: debug.warn,
+    error: debug.error
+  };
+  
+  return loggers[level as keyof typeof loggers] || debug.log;
+};
+
+/**
+ * Type-safe environment variable getter
+ */
+export const getEnvVar = (key: string, defaultValue?: string): string | undefined => {
+  const value = process.env[key];
+  if (value === undefined && defaultValue !== undefined) {
+    debug.warn(`Environment variable ${key} not found, using default: ${defaultValue}`);
+    return defaultValue;
+  }
+  return value;
+};
+
+/**
+ * Validate required environment variables
+ */
+export const validateEnvVars = (required: string[]): void => {
+  const missing = required.filter(key => !process.env[key]);
+  if (missing.length > 0) {
+    const error = new Error(`Missing required environment variables: ${missing.join(', ')}`);
+    logError(error);
+    throw error;
+  }
+};

package/src/utils/error.ts

@@ -0,0 +1,88 @@
+/**
+ * Error handling utilities
+ */
+
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  
+  if (typeof error === 'string') {
+    return error;
+  }
+  
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String(error.message);
+  }
+  
+  return 'Unknown error occurred';
+}
+
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+export function logAndReturn<T>(error: unknown, defaultValue: T): T {
+  console.error('Error occurred:', getErrorMessage(error));
+  return defaultValue;
+}
+
+/**
+ * Enhanced error handler for consistent tool error handling
+ */
+export function handleToolError(error: unknown, operation: string, context?: Record<string, unknown>): never {
+  console.error(`Error in ${operation}:`, error);
+  
+  if (context) {
+    console.error('Context:', context);
+  }
+
+  const message = getErrorMessage(error);
+  
+  // Provide more specific error messages based on error content
+  if (message.includes('ECONNREFUSED') || message.includes('ENOTFOUND')) {
+    throw new Error(`Connection failed during ${operation}. Please check your WordPress site URL and network connection.`);
+  }
+
+  if (message.includes('401') || message.includes('Unauthorized')) {
+    throw new Error(`Authentication failed during ${operation}. Please check your WordPress credentials.`);
+  }
+
+  if (message.includes('403') || message.includes('Forbidden')) {
+    throw new Error(`Permission denied during ${operation}. Please check your user permissions.`);
+  }
+
+  if (message.includes('429') || message.includes('Too Many Requests')) {
+    throw new Error(`Rate limit exceeded during ${operation}. Please try again later.`);
+  }
+
+  throw new Error(`Failed to ${operation}: ${message}`);
+}
+
+/**
+ * Validates required parameters
+ */
+export function validateRequired(params: Record<string, unknown>, required: string[]): void {
+  const missing = required.filter(key => !params[key]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required parameters: ${missing.join(', ')}`);
+  }
+}
+
+/**
+ * Validates site parameter for multi-site configurations
+ */
+export function validateSite(site: string | undefined, availableSites: string[]): string {
+  if (!site) {
+    if (availableSites.length === 1) {
+      return availableSites[0];
+    }
+    throw new Error(`Site parameter is required when multiple sites are configured. Available sites: ${availableSites.join(', ')}`);
+  }
+
+  if (!availableSites.includes(site)) {
+    throw new Error(`Site '${site}' not found. Available sites: ${availableSites.join(', ')}`);
+  }
+
+  return site;
+}

package/src/utils/toolWrapper.ts

@@ -0,0 +1,105 @@
+/**
+ * Tool Wrapper Utility
+ * Standardizes error handling and reduces repetitive try-catch blocks
+ */
+
+import { getErrorMessage } from "./error.js";
+
+/**
+ * Wrapper for tool methods that standardizes error handling
+ */
+export function withErrorHandling<T extends any[], R>(
+  operation: string,
+  fn: (...args: T) => Promise<R>
+): (...args: T) => Promise<R> {
+  return async (...args: T): Promise<R> => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      throw new Error(`${operation}: ${getErrorMessage(error)}`);
+    }
+  };
+}
+
+/**
+ * Wrapper for tool methods with validation
+ */
+export function withValidation<T extends any[], R>(
+  operation: string,
+  validator: (...args: T) => void,
+  fn: (...args: T) => Promise<R>
+): (...args: T) => Promise<R> {
+  return async (...args: T): Promise<R> => {
+    try {
+      validator(...args);
+      return await fn(...args);
+    } catch (error) {
+      throw new Error(`${operation}: ${getErrorMessage(error)}`);
+    }
+  };
+}
+
+/**
+ * Common validation functions
+ */
+export const validators = {
+  requireSite: (client: any, params: any) => {
+    if (!client) {
+      throw new Error("WordPress client is required");
+    }
+  },
+
+  requireId: (params: { id?: number | string }) => {
+    if (!params.id) {
+      throw new Error("ID parameter is required");
+    }
+  },
+
+  requireNonEmpty: (value: any, fieldName: string) => {
+    if (!value || (typeof value === 'string' && value.trim() === '')) {
+      throw new Error(`${fieldName} cannot be empty`);
+    }
+  },
+
+  requireFields: (params: any, fields: string[]) => {
+    for (const field of fields) {
+      if (params[field] === undefined || params[field] === null) {
+        throw new Error(`${field} is required`);
+      }
+    }
+  }
+};
+
+/**
+ * Decorator for class methods to add error handling
+ */
+export function errorHandler(operation: string) {
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: any[]) {
+      try {
+        return await originalMethod.apply(this, args);
+      } catch (error) {
+        throw new Error(`${operation}: ${getErrorMessage(error)}`);
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Helper to format success responses consistently
+ */
+export function formatSuccessResponse(content: string): string {
+  return content;
+}
+
+/**
+ * Helper to format error responses consistently
+ */
+export function formatErrorResponse(operation: string, error: any): never {
+  const message = getErrorMessage(error);
+  throw new Error(`${operation}: ${message}`);
+}