mcp-wordpress 1.5.2 → 2.0.0

package/src/utils/enhancedError.ts

@@ -0,0 +1,248 @@
+import { getErrorMessage } from "./error.js";
+
+export interface ErrorContext {
+  operation: string;
+  parameters?: Record<string, any>;
+  suggestions?: string[];
+  troubleshooting?: string[];
+}
+
+/**
+ * Enhanced error handling with helpful messages and suggestions
+ */
+export class EnhancedError extends Error {
+  public suggestions: string[];
+  public troubleshooting: string[];
+  public context: ErrorContext;
+
+  constructor(message: string, context: ErrorContext) {
+    super(message);
+    this.name = "EnhancedError";
+    this.context = context;
+    this.suggestions = context.suggestions || [];
+    this.troubleshooting = context.troubleshooting || [];
+  }
+
+  /**
+   * Format error message with suggestions
+   */
+  toString(): string {
+    let message = `❌ ${this.message}`;
+
+    if (this.suggestions.length > 0) {
+      message += `\n\n💡 **Suggestions:**\n`;
+      this.suggestions.forEach((suggestion) => {
+        message += `• ${suggestion}\n`;
+      });
+    }
+
+    if (this.troubleshooting.length > 0) {
+      message += `\n🔧 **Troubleshooting:**\n`;
+      this.troubleshooting.forEach((step) => {
+        message += `• ${step}\n`;
+      });
+    }
+
+    return message;
+  }
+}
+
+/**
+ * Common error handlers with context-aware suggestions
+ */
+export class ErrorHandlers {
+  /**
+   * Handle post not found errors
+   */
+  static postNotFound(postId: number, originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError(`Post with ID ${postId} not found`, {
+      operation: "get_post",
+      parameters: { postId },
+      suggestions: [
+        "Check if the post ID is correct",
+        "Verify the post exists and is published",
+        "Try listing posts first with wp_list_posts to see available posts",
+        "Check if you have permission to view this post",
+      ],
+      troubleshooting: [
+        "Use wp_list_posts to see all available posts",
+        "Check the post status - it might be draft, private, or trashed",
+        "Verify your user permissions for viewing posts",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+
+  /**
+   * Handle authentication errors
+   */
+  static authenticationFailed(originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError("Authentication failed", {
+      operation: "authenticate",
+      suggestions: [
+        "Check your WordPress credentials (username and app password)",
+        "Verify the WordPress site URL is correct",
+        "Ensure application passwords are enabled on your WordPress site",
+        "Try regenerating your application password",
+      ],
+      troubleshooting: [
+        "Go to your WordPress admin → Users → Profile → Application Passwords",
+        "Create a new application password with a descriptive name",
+        "Make sure the WordPress site URL ends with wp-json/wp/v2",
+        "Check if your site has any security plugins blocking REST API",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+
+  /**
+   * Handle site parameter missing errors
+   */
+  static siteParameterMissing(availableSites: string[]): EnhancedError {
+    return new EnhancedError("Multiple sites configured - site parameter required", {
+      operation: "site_selection",
+      suggestions: [
+        "Add --site parameter to specify which site to use",
+        `Available sites: ${availableSites.join(", ")}`,
+        'Example: wp_list_posts --site="your-site-id"',
+      ],
+      troubleshooting: [
+        "Check your mcp-wordpress.config.json for configured sites",
+        "Use the site ID from your configuration file",
+        "Site IDs are defined in the 'id' field of each site config",
+      ],
+    });
+  }
+
+  /**
+   * Handle site not found errors
+   */
+  static siteNotFound(siteId: string, availableSites: string[]): EnhancedError {
+    return new EnhancedError(`Site with ID '${siteId}' not found`, {
+      operation: "site_selection",
+      parameters: { siteId },
+      suggestions: [
+        `Available sites: ${availableSites.join(", ")}`,
+        "Check the spelling of the site ID",
+        "Verify the site is configured in mcp-wordpress.config.json",
+      ],
+      troubleshooting: [
+        "Open mcp-wordpress.config.json to see configured sites",
+        "Check the 'id' field for each site configuration",
+        "Ensure the site ID matches exactly (case-sensitive)",
+      ],
+    });
+  }
+
+  /**
+   * Handle permission errors
+   */
+  static permissionDenied(operation: string, originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError(`Permission denied for ${operation}`, {
+      operation,
+      suggestions: [
+        "Check if your user has the required permissions",
+        "Verify you're logged in with the correct user account",
+        "Contact your WordPress administrator for permission changes",
+      ],
+      troubleshooting: [
+        "Check your user role in WordPress admin → Users",
+        "Verify the required capabilities for this operation",
+        "Try using an administrator account",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+
+  /**
+   * Handle network/connection errors
+   */
+  static connectionError(originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError("Failed to connect to WordPress site", {
+      operation: "connection",
+      suggestions: [
+        "Check your internet connection",
+        "Verify the WordPress site URL is correct and accessible",
+        "Check if the site is temporarily down",
+      ],
+      troubleshooting: [
+        "Try accessing the site in your browser",
+        "Check if the REST API is enabled: visit yoursite.com/wp-json/",
+        "Verify there are no firewall or security plugins blocking access",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+
+  /**
+   * Handle validation errors
+   */
+  static validationError(field: string, value: any, expectedType: string): EnhancedError {
+    return new EnhancedError(`Invalid ${field}: expected ${expectedType}, got ${typeof value}`, {
+      operation: "validation",
+      parameters: { field, value, expectedType },
+      suggestions: [
+        `Provide a valid ${expectedType} for ${field}`,
+        "Check the parameter format and type",
+        "Refer to the tool documentation for correct parameter format",
+      ],
+      troubleshooting: [
+        "Review the tool's parameter requirements",
+        "Check for typos in parameter names",
+        "Ensure parameter values match the expected type",
+      ],
+    });
+  }
+
+  /**
+   * Handle rate limiting errors
+   */
+  static rateLimitExceeded(originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError("Rate limit exceeded", {
+      operation: "rate_limit",
+      suggestions: [
+        "Wait a few minutes before trying again",
+        "Reduce the frequency of requests",
+        "Use pagination for large operations",
+      ],
+      troubleshooting: [
+        "Check your WordPress hosting plan limits",
+        "Consider upgrading your hosting plan for higher limits",
+        "Implement delays between requests",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+
+  /**
+   * Generic error handler with basic suggestions
+   */
+  static generic(operation: string, originalError: any): EnhancedError {
+    const errorMessage = getErrorMessage(originalError);
+
+    return new EnhancedError(`Failed to ${operation}`, {
+      operation,
+      suggestions: [
+        "Check your WordPress credentials and permissions",
+        "Verify the site is accessible and functioning",
+        "Try the operation again after a brief wait",
+      ],
+      troubleshooting: [
+        "Test your connection with a simpler operation first",
+        "Check WordPress admin for any issues",
+        "Review the WordPress error logs",
+        `Original error: ${errorMessage}`,
+      ],
+    });
+  }
+}

package/src/utils/streaming.ts

@@ -0,0 +1,428 @@
+/**
+ * Streaming utilities for handling large result sets
+ * Implements streaming responses for better performance and memory usage
+ */
+
+// Node.js streaming imports removed - not currently used but available for future enhancement
+
+export interface StreamingOptions {
+  batchSize?: number;
+  delay?: number;
+  transformItem?: (item: any) => any;
+  filterItem?: (item: any) => boolean;
+}
+
+export interface StreamingResult<T> {
+  data: T[];
+  hasMore: boolean;
+  cursor?: string | undefined;
+  total?: number | undefined;
+  processed: number;
+}
+
+/**
+ * Creates a streaming response for large datasets
+ */
+export class DataStreamer<T> {
+  private batchSize: number;
+  private delay: number;
+  private transformItem: ((item: T) => any) | undefined;
+  private filterItem: ((item: T) => boolean) | undefined;
+
+  constructor(options: StreamingOptions = {}) {
+    this.batchSize = options.batchSize || 50;
+    this.delay = options.delay || 0;
+    this.transformItem = options.transformItem || undefined;
+    this.filterItem = options.filterItem || undefined;
+  }
+
+  /**
+   * Processes data in batches with streaming
+   */
+  async *streamBatches<U>(
+    data: T[],
+    processor: (batch: T[]) => Promise<U[]>,
+  ): AsyncGenerator<StreamingResult<U>, void, unknown> {
+    const total = data.length;
+    let processed = 0;
+
+    for (let i = 0; i < data.length; i += this.batchSize) {
+      const batch = data.slice(i, i + this.batchSize);
+
+      // Apply filtering if provided
+      const filteredBatch = this.filterItem ? batch.filter(this.filterItem) : batch;
+
+      // Process the batch
+      const processedBatch = await processor(filteredBatch);
+
+      // Apply transformation if provided
+      const transformedBatch = this.transformItem
+        ? processedBatch.map((item: any) => this.transformItem!(item))
+        : processedBatch;
+
+      processed += batch.length;
+      const hasMore = processed < total;
+
+      yield {
+        data: transformedBatch,
+        hasMore,
+        cursor: hasMore ? String(i + this.batchSize) : undefined,
+        total,
+        processed,
+      };
+
+      // Add delay between batches if specified
+      if (this.delay > 0 && hasMore) {
+        await new Promise((resolve) => setTimeout(resolve, this.delay));
+      }
+    }
+  }
+
+  /**
+   * Processes large datasets with pagination
+   */
+  async *streamPages<U>(
+    fetcher: (page: number, perPage: number) => Promise<{ data: T[]; hasMore: boolean }>,
+    processor: (items: T[]) => Promise<U[]>,
+  ): AsyncGenerator<StreamingResult<U>, void, unknown> {
+    let page = 1;
+    let totalProcessed = 0;
+
+    while (true) {
+      const result = await fetcher(page, this.batchSize);
+
+      if (result.data.length === 0) {
+        break;
+      }
+
+      // Apply filtering if provided
+      const filteredData = this.filterItem ? result.data.filter(this.filterItem) : result.data;
+
+      // Process the data
+      const processedData = await processor(filteredData);
+
+      // Apply transformation if provided
+      const transformedData = this.transformItem
+        ? processedData.map((item: any) => this.transformItem!(item))
+        : processedData;
+
+      totalProcessed += result.data.length;
+
+      yield {
+        data: transformedData,
+        hasMore: result.hasMore,
+        cursor: result.hasMore ? String(page + 1) : undefined,
+        total: undefined, // Unknown for paginated results
+        processed: totalProcessed,
+      };
+
+      if (!result.hasMore) {
+        break;
+      }
+
+      page++;
+
+      // Add delay between pages if specified
+      if (this.delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, this.delay));
+      }
+    }
+  }
+}
+
+/**
+ * Streaming formatter for WordPress data
+ */
+export class WordPressDataStreamer {
+  /**
+   * Streams WordPress posts with author and taxonomy information
+   */
+  static async *streamPosts(
+    posts: any[],
+    options: {
+      includeAuthor?: boolean;
+      includeCategories?: boolean;
+      includeTags?: boolean;
+      batchSize?: number;
+    } = {},
+  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
+    const streamer = new DataStreamer<any>({
+      batchSize: options.batchSize || 20,
+      transformItem: (post) => ({
+        id: post.id,
+        title: post.title?.rendered || "Untitled",
+        excerpt: post.excerpt?.rendered
+          ? post.excerpt.rendered.replace(/<[^>]*>/g, "").substring(0, 150) + "..."
+          : "No excerpt",
+        status: post.status,
+        date: new Date(post.date).toLocaleDateString(),
+        link: post.link,
+        author: options.includeAuthor ? post.author : undefined,
+        categories: options.includeCategories ? post.categories : undefined,
+        tags: options.includeTags ? post.tags : undefined,
+      }),
+      filterItem: (post) => post.status !== "trash", // Filter out trashed posts
+    });
+
+    const processor = async (batch: any[]) => {
+      // Simulate processing time for large datasets
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      return batch;
+    };
+
+    for await (const result of streamer.streamBatches(posts, processor)) {
+      yield result;
+    }
+  }
+
+  /**
+   * Streams WordPress users with role information
+   */
+  static async *streamUsers(
+    users: any[],
+    options: {
+      includeRoles?: boolean;
+      includeCapabilities?: boolean;
+      batchSize?: number;
+    } = {},
+  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
+    const streamer = new DataStreamer<any>({
+      batchSize: options.batchSize || 30,
+      transformItem: (user) => ({
+        id: user.id,
+        name: user.name || "No name",
+        username: user.slug || "unknown",
+        email: user.email || "No email",
+        roles: options.includeRoles ? user.roles : undefined,
+        capabilities: options.includeCapabilities ? Object.keys(user.capabilities || {}) : undefined,
+        registeredDate: user.registered_date ? new Date(user.registered_date).toLocaleDateString() : "Unknown",
+      }),
+    });
+
+    const processor = async (batch: any[]) => {
+      // Add user processing logic here if needed
+      return batch;
+    };
+
+    for await (const result of streamer.streamBatches(users, processor)) {
+      yield result;
+    }
+  }
+
+  /**
+   * Streams WordPress comments with moderation status
+   */
+  static async *streamComments(
+    comments: any[],
+    options: {
+      includeAuthor?: boolean;
+      includePost?: boolean;
+      batchSize?: number;
+    } = {},
+  ): AsyncGenerator<StreamingResult<any>, void, unknown> {
+    const streamer = new DataStreamer<any>({
+      batchSize: options.batchSize || 40,
+      transformItem: (comment) => ({
+        id: comment.id,
+        content: comment.content?.rendered
+          ? comment.content.rendered.replace(/<[^>]*>/g, "").substring(0, 200) + "..."
+          : "No content",
+        status: comment.status,
+        date: new Date(comment.date).toLocaleDateString(),
+        author: options.includeAuthor
+          ? {
+              name: comment.author_name,
+              email: comment.author_email,
+              url: comment.author_url,
+            }
+          : undefined,
+        post: options.includePost ? comment.post : undefined,
+      }),
+      filterItem: (comment) => comment.status !== "spam", // Filter out spam comments
+    });
+
+    const processor = async (batch: any[]) => {
+      // Add comment processing logic here if needed
+      return batch;
+    };
+
+    for await (const result of streamer.streamBatches(comments, processor)) {
+      yield result;
+    }
+  }
+}
+
+/**
+ * Utility functions for streaming responses
+ */
+export class StreamingUtils {
+  /**
+   * Formats streaming results for display
+   */
+  static formatStreamingResponse(
+    results: StreamingResult<any>[],
+    type: "posts" | "users" | "comments" | "media" = "posts",
+  ): string {
+    const allData = results.flatMap((result) => result.data);
+    const totalProcessed = results[results.length - 1]?.processed || 0;
+    const hasMore = results[results.length - 1]?.hasMore || false;
+
+    const typeEmojis = {
+      posts: "📄",
+      users: "👥",
+      comments: "💬",
+      media: "📎",
+    };
+
+    const emoji = typeEmojis[type];
+    const typeName = type.charAt(0).toUpperCase() + type.slice(1);
+
+    let response = `${emoji} **${typeName} Results** (Streamed)\n\n`;
+    response += `📊 **Summary**: ${allData.length} items displayed, ${totalProcessed} processed total\n`;
+
+    if (hasMore) {
+      response += `⏳ **Status**: More data available (streaming in progress)\n`;
+    } else {
+      response += `✅ **Status**: Complete\n`;
+    }
+
+    response += `🕐 **Retrieved**: ${new Date().toLocaleString()}\n\n`;
+
+    // Format individual items
+    allData.forEach((item, index) => {
+      response += `${index + 1}. **${item.title || item.name || item.content?.substring(0, 50) || "Item"}**\n`;
+
+      if (item.excerpt) response += `   📝 ${item.excerpt}\n`;
+      if (item.email) response += `   📧 ${item.email}\n`;
+      if (item.status) response += `   🏷️ Status: ${item.status}\n`;
+      if (item.date) response += `   📅 Date: ${item.date}\n`;
+
+      response += "\n";
+    });
+
+    return response;
+  }
+
+  /**
+   * Implements progressive loading for large datasets
+   */
+  static async loadProgressively<T>(
+    fetcher: (offset: number, limit: number) => Promise<T[]>,
+    options: {
+      initialLoad?: number;
+      batchSize?: number;
+      maxItems?: number;
+      onProgress?: (loaded: number, total?: number) => void;
+    } = {},
+  ): Promise<T[]> {
+    const initialLoad = options.initialLoad || 50;
+    const batchSize = options.batchSize || 25;
+    const maxItems = options.maxItems || 1000;
+
+    const results: T[] = [];
+    let offset = 0;
+    let hasMore = true;
+
+    // Initial load
+    const initialBatch = await fetcher(offset, initialLoad);
+    results.push(...initialBatch);
+    offset += initialLoad;
+
+    if (options.onProgress) {
+      options.onProgress(results.length);
+    }
+
+    // Progressive loading
+    while (hasMore && results.length < maxItems) {
+      const batch = await fetcher(offset, batchSize);
+
+      if (batch.length === 0) {
+        hasMore = false;
+        break;
+      }
+
+      results.push(...batch);
+      offset += batchSize;
+
+      if (options.onProgress) {
+        options.onProgress(results.length, maxItems);
+      }
+
+      // Small delay to prevent overwhelming the server
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+
+    return results.slice(0, maxItems);
+  }
+}
+
+/**
+ * Memory-efficient data processor
+ */
+export class MemoryEfficientProcessor {
+  /**
+   * Processes large datasets with memory monitoring
+   */
+  static async processLargeDataset<T, U>(
+    dataProvider: () => AsyncGenerator<T[], void, unknown>,
+    processor: (items: T[]) => Promise<U[]>,
+    options: {
+      maxMemoryUsage?: number; // in MB
+      batchSize?: number;
+      onProgress?: (processed: number) => void;
+    } = {},
+  ): Promise<U[]> {
+    const maxMemory = options.maxMemoryUsage || 100; // 100MB default
+    const batchSize = options.batchSize || 50;
+    const results: U[] = [];
+    let processed = 0;
+
+    for await (const batch of dataProvider()) {
+      // Check memory usage
+      const memoryUsage = process.memoryUsage();
+      const memoryUsageMB = memoryUsage.heapUsed / 1024 / 1024;
+
+      if (memoryUsageMB > maxMemory) {
+        // If memory usage is too high, process in smaller batches
+        const smallerBatches = this.chunkArray(batch, Math.floor(batchSize / 2));
+
+        for (const smallBatch of smallerBatches) {
+          const processed_batch = await processor(smallBatch);
+          results.push(...processed_batch);
+          processed += smallBatch.length;
+
+          if (options.onProgress) {
+            options.onProgress(processed);
+          }
+
+          // Force garbage collection if available
+          if (global.gc) {
+            global.gc();
+          }
+        }
+      } else {
+        // Normal processing
+        const processed_batch = await processor(batch);
+        results.push(...processed_batch);
+        processed += batch.length;
+
+        if (options.onProgress) {
+          options.onProgress(processed);
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Helper method to split arrays into chunks
+   */
+  private static chunkArray<T>(array: T[], chunkSize: number): T[][] {
+    const chunks: T[][] = [];
+    for (let i = 0; i < array.length; i += chunkSize) {
+      chunks.push(array.slice(i, i + chunkSize));
+    }
+    return chunks;
+  }
+}