mcp-wordpress 2.4.2 → 2.5.0

package/src/tools/BaseToolManager.ts

@@ -1,66 +1,319 @@
 /**
- * Base utility class for tool managers to reduce code duplication
+ * Base utility class for tool managers with enhanced type safety
  */
 
 import { getErrorMessage } from "../utils/error.js";
+import { WordPressId, createWordPressId, DeepReadonly, Result, createSuccess, createError } from "../types/enhanced.js";
+
+interface EnhancedError extends Error {
+  originalError?: unknown;
+  operation?: string;
+  context?: Record<string, unknown> | undefined;
+  timestamp?: Date;
+}
+
+export interface ParameterValidationRule<T = unknown> {
+  readonly key: string;
+  readonly required: boolean;
+  readonly type?: string;
+  readonly validator?: (value: unknown) => value is T;
+  readonly transformer?: (value: unknown) => T;
+  readonly errorMessage?: string;
+}
+
+export interface CacheKeyOptions {
+  readonly namespace?: string;
+  readonly includeTimestamp?: boolean;
+  readonly customHasher?: (params: Record<string, unknown>) => string;
+}
 
 export class BaseToolUtils {
   /**
-   * Validate required parameters
+   * Validate required parameters with enhanced type safety
+   */
+  static validateParams<T extends Record<string, unknown>>(
+    params: unknown,
+    rules: readonly ParameterValidationRule[]
+  ): Result<T, Error> {
+    if (!params || typeof params !== 'object' || Array.isArray(params)) {
+      return createError(new ValidationError('Parameters must be a non-null object', 'params', params));
+    }
+
+    const typedParams = params as Record<string, unknown>;
+    const errors: Error[] = [];
+
+    for (const rule of rules) {
+      const value = typedParams[rule.key];
+      const exists = rule.key in typedParams;
+
+      // Check required fields
+      if (rule.required && (!exists || value === undefined || value === null)) {
+        errors.push(new ValidationError(
+          rule.errorMessage || `Missing required parameter: ${rule.key}`,
+          rule.key,
+          value
+        ));
+        continue;
+      }
+
+      // Skip optional fields that don't exist
+      if (!rule.required && !exists) {
+        continue;
+      }
+
+      // Type validation
+      if (rule.type && typeof value !== rule.type) {
+        errors.push(new ValidationError(
+          `Parameter ${rule.key} must be of type ${rule.type}, got ${typeof value}`,
+          rule.key,
+          value
+        ));
+        continue;
+      }
+
+      // Custom validation
+      if (rule.validator && !rule.validator(value)) {
+        errors.push(new ValidationError(
+          rule.errorMessage || `Parameter ${rule.key} failed validation`,
+          rule.key,
+          value
+        ));
+        continue;
+      }
+
+      // Transform value if transformer provided
+      if (rule.transformer) {
+        try {
+          typedParams[rule.key] = rule.transformer(value);
+        } catch (error) {
+          errors.push(new ValidationError(
+            `Failed to transform parameter ${rule.key}: ${getErrorMessage(error)}`,
+            rule.key,
+            value
+          ));
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      return createError(errors[0]); // Return first error for simplicity
+    }
+
+    return createSuccess(typedParams as T);
+  }
+
+  /**
+   * Validate ID parameter with WordPress ID branding
    */
-  static validateParams(params: Record<string, any>, required: string[]): void {
-    for (const field of required) {
-      if (
-        !(field in params) ||
-        params[field] === undefined ||
-        params[field] === null
-      ) {
-        throw new Error(`Missing required parameter: ${field}`);
+  static validateId(id: unknown, name = "id"): Result<WordPressId, Error> {
+    try {
+      const numId = Number(id);
+      if (!Number.isInteger(numId) || numId <= 0) {
+        return createError(new ValidationError(
+          `Invalid ${name}: must be a positive integer`,
+          name,
+          id
+        ));
       }
+      return createSuccess(createWordPressId(numId));
+    } catch (error) {
+      return createError(new ValidationError(
+        `Invalid ${name}: ${getErrorMessage(error)}`,
+        name,
+        id
+      ));
     }
   }
 
   /**
-   * Validate ID parameter
+   * Validate multiple IDs at once
    */
-  static validateId(id: unknown, name = "id"): number {
-    const numId = Number(id);
-    if (!Number.isInteger(numId) || numId <= 0) {
-      throw new Error(`Invalid ${name}: must be a positive integer`);
+  static validateIds(ids: unknown[], name = "ids"): Result<readonly WordPressId[], Error> {
+    const validatedIds: WordPressId[] = [];
+    
+    for (let i = 0; i < ids.length; i++) {
+      const result = this.validateId(ids[i], `${name}[${i}]`);
+      if (!result.success) {
+        return result;
+      }
+      validatedIds.push(result.data);
     }
-    return numId;
+    
+    return createSuccess(validatedIds as readonly WordPressId[]);
   }
 
   /**
-   * Handle errors consistently across all tools
+   * Handle errors consistently with enhanced error context
    */
-  static handleError(error: unknown, operation: string): string {
+  static handleError(error: unknown, operation: string, context?: Record<string, unknown> | undefined): Error {
     const errorMessage = getErrorMessage(error);
-    return `Error in ${operation}: ${errorMessage}`;
+    const enhancedMessage = `Error in ${operation}: ${errorMessage}`;
+    
+    const enhancedError = new Error(enhancedMessage) as EnhancedError;
+    enhancedError.originalError = error;
+    enhancedError.operation = operation;
+    enhancedError.context = context;
+    enhancedError.timestamp = new Date();
+    
+    return enhancedError;
   }
 
   /**
-   * Cache key generation helper
+   * Generate cache keys with enhanced options
    */
   static generateCacheKey(
-    operation: string,
-    params: Record<string, unknown>,
+    operation: string, 
+    params: DeepReadonly<Record<string, unknown>>,
+    options: CacheKeyOptions = {}
   ): string {
+    const {
+      namespace = 'wp',
+      includeTimestamp = false,
+      customHasher
+    } = options;
+
     const site = params.site || "default";
-    const paramStr = Object.entries(params)
-      .filter(([key]) => key !== "site")
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([key, value]) => `${key}:${value}`)
-      .join("|");
-    return `${site}:${operation}:${paramStr}`;
+    
+    let paramStr: string;
+    if (customHasher) {
+      paramStr = customHasher(params as Record<string, unknown>);
+    } else {
+      paramStr = Object.entries(params)
+        .filter(([key]) => key !== "site")
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}:${JSON.stringify(value)}`)
+        .join("|");
+    }
+
+    let cacheKey = `${namespace}:${site}:${operation}:${paramStr}`;
+    
+    if (includeTimestamp) {
+      const timestamp = Math.floor(Date.now() / 1000);
+      cacheKey += `:${timestamp}`;
+    }
+    
+    return cacheKey;
   }
 
   /**
-   * Format consistent response messages
+   * Format consistent success response messages
    */
-  static formatSuccessMessage(operation: string, details?: string): string {
-    return details
-      ? `${operation}: ${details}`
-      : `${operation} completed successfully`;
+  static formatSuccessMessage(operation: string, details?: string, count?: number): string {
+    let message = operation;
+    
+    if (count !== undefined) {
+      message += ` (${count} ${count === 1 ? 'item' : 'items'})`;
+    }
+    
+    if (details) {
+      message += `: ${details}`;
+    } else {
+      message += " completed successfully";
+    }
+    
+    return message;
+  }
+
+  /**
+   * Validate string parameters with enhanced checks
+   */
+  static validateString(
+    value: unknown, 
+    name: string,
+    options: {
+      readonly required?: boolean;
+      readonly minLength?: number;
+      readonly maxLength?: number;
+      readonly pattern?: RegExp;
+      readonly allowEmpty?: boolean;
+    } = {}
+  ): Result<string, Error> {
+    const { required = true, minLength, maxLength, pattern, allowEmpty = false } = options;
+
+    if (value === undefined || value === null) {
+      if (required) {
+        return createError(new ValidationError(`${name} is required`, name, value));
+      }
+      return createSuccess('');
+    }
+
+    if (typeof value !== 'string') {
+      return createError(new ValidationError(`${name} must be a string`, name, value));
+    }
+
+    if (!allowEmpty && value.trim().length === 0) {
+      return createError(new ValidationError(`${name} cannot be empty`, name, value));
+    }
+
+    if (minLength !== undefined && value.length < minLength) {
+      return createError(new ValidationError(
+        `${name} must be at least ${minLength} characters long`, 
+        name, 
+        value
+      ));
+    }
+
+    if (maxLength !== undefined && value.length > maxLength) {
+      return createError(new ValidationError(
+        `${name} must be no more than ${maxLength} characters long`, 
+        name, 
+        value
+      ));
+    }
+
+    if (pattern && !pattern.test(value)) {
+      return createError(new ValidationError(
+        `${name} does not match required pattern`, 
+        name, 
+        value
+      ));
+    }
+
+    return createSuccess(value);
+  }
+
+  /**
+   * Type-safe parameter extraction
+   */
+  static extractParam<T>(
+    params: DeepReadonly<Record<string, unknown>>, 
+    key: string, 
+    defaultValue?: T
+  ): T | undefined {
+    const value = params[key];
+    return value !== undefined ? value as T : defaultValue;
+  }
+
+  /**
+   * Safe array extraction with type validation
+   */
+  static extractArray<T>(
+    params: DeepReadonly<Record<string, unknown>>, 
+    key: string,
+    itemValidator?: (item: unknown) => item is T
+  ): readonly T[] {
+    const value = params[key];
+    
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    if (itemValidator) {
+      return value.filter(itemValidator);
+    }
+
+    return value as readonly T[];
+  }
+}
+
+// Custom ValidationError class for enhanced error handling
+class ValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly field: string,
+    public readonly value: unknown
+  ) {
+    super(message);
+    this.name = 'ValidationError';
   }
 }

package/src/tools/auth.ts

@@ -11,7 +11,12 @@ export class AuthTools {
    * Retrieves the list of authentication tools.
    * @returns An array of MCPTool definitions.
    */
-  public getTools(): any[] {
+  public getTools(): Array<{
+    name: string;
+    description: string;
+    parameters?: Array<{ name: string; type?: string; description?: string; required?: boolean; enum?: string[]; items?: unknown }>;
+    handler: (client: WordPressClient, params: Record<string, unknown>) => Promise<unknown>;
+  }> {
     return [
       {
         name: "wp_test_auth",
@@ -71,7 +76,10 @@ export class AuthTools {
    * @param params - The parameters for the tool request.
    * @returns A promise that resolves to an MCPToolResponse.
    */
-  public async handleTestAuth(client: WordPressClient, params: any): Promise<any> {
+  public async handleTestAuth(
+    client: WordPressClient,
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
     try {
       await client.ping();
       const user = await client.getCurrentUser();
@@ -85,7 +93,7 @@ export class AuthTools {
         `**Roles:** ${user.roles?.join(", ") || "N/A"}\n\n` +
         "Your WordPress connection is working properly.";
 
-      return content;
+      return { content };
     } catch (error) {
       throw new Error(`Authentication test failed: ${getErrorMessage(error)}`);
     }
@@ -98,7 +106,10 @@ export class AuthTools {
    * @param params - The parameters for the tool request.
    * @returns A promise that resolves to an MCPToolResponse.
    */
-  public async handleGetAuthStatus(client: WordPressClient, params: any): Promise<any> {
+  public async handleGetAuthStatus(
+    client: WordPressClient,
+    params: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> {
     try {
       const isAuthenticated = client.isAuthenticated;
       const config = client.config;
@@ -114,7 +125,7 @@ export class AuthTools {
         content += "**Status:** Not connected. Use 'wp_test_auth' to connect and verify credentials.";
       }
 
-      return content;
+      return { content };
     } catch (error) {
       throw new Error(`Failed to get auth status: ${getErrorMessage(error)}`);
     }
@@ -129,13 +140,14 @@ export class AuthTools {
    */
   public async handleSwitchAuthMethod(
     client: WordPressClient,
-    params: {
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
+    const { method: _method, username: _username, password: _password, jwt_token: _jwt_token } = params as {
       method: AuthMethod;
       username?: string;
       password?: string;
       jwt_token?: string;
-    },
-  ): Promise<any> {
+    };
     try {
       // This functionality is not currently supported as the client
       // doesn't have an updateAuthConfig method

package/src/tools/cache.ts

@@ -43,8 +43,7 @@ export class CacheTools {
           {
             name: "pattern",
             type: "string",
-            description:
-              'Optional pattern to clear specific cache entries (e.g., "posts", "categories").',
+            description: 'Optional pattern to clear specific cache entries (e.g., "posts", "categories").',
           },
         ],
         handler: this.handleClearCache.bind(this),
@@ -86,8 +85,7 @@ export class CacheTools {
       if (!(client instanceof CachedWordPressClient)) {
         return {
           caching_enabled: false,
-          message:
-            "Caching is disabled for this site. Set DISABLE_CACHE=false to enable caching.",
+          message: "Caching is disabled for this site. Set DISABLE_CACHE=false to enable caching.",
         };
       }
 
@@ -168,12 +166,7 @@ export class CacheTools {
         success: true,
         message: "Cache warmed with essential WordPress data.",
         cache_entries_after_warming: stats.cache.totalSize,
-        warmed_data: [
-          "Current user information",
-          "Categories",
-          "Tags",
-          "Site settings",
-        ],
+        warmed_data: ["Current user information", "Categories", "Tags", "Site settings"],
       };
     });
   }
@@ -189,8 +182,7 @@ export class CacheTools {
         return {
           caching_enabled: false,
           message: "Caching is disabled for this site.",
-          how_to_enable:
-            "Remove DISABLE_CACHE=true from environment variables or set it to false.",
+          how_to_enable: "Remove DISABLE_CACHE=true from environment variables or set it to false.",
         };
       }
 
@@ -251,9 +243,7 @@ export class CacheTools {
 
     const client = this.clients.get(siteId);
     if (!client) {
-      throw new Error(
-        `Site "${siteId}" not found. Available sites: ${Array.from(this.clients.keys()).join(", ")}`,
-      );
+      throw new Error(`Site "${siteId}" not found. Available sites: ${Array.from(this.clients.keys()).join(", ")}`);
     }
 
     return client;

package/src/tools/comments.ts

@@ -1,9 +1,5 @@
 import { WordPressClient } from "../client/api.js";
-import {
-  CommentQueryParams,
-  CreateCommentRequest,
-  UpdateCommentRequest,
-} from "../types/wordpress.js";
+import { CommentQueryParams, CreateCommentRequest, UpdateCommentRequest } from "../types/wordpress.js";
 import { getErrorMessage } from "../utils/error.js";
 
 /**
@@ -15,7 +11,12 @@ export class CommentTools {
    * Retrieves the list of comment management tools.
    * @returns An array of MCPTool definitions.
    */
-  public getTools(): any[] {
+  public getTools(): Array<{
+    name: string;
+    description: string;
+    parameters?: Array<{ name: string; type?: string; description?: string; required?: boolean; enum?: string[]; items?: unknown }>;
+    handler: (client: WordPressClient, params: Record<string, unknown>) => Promise<unknown>;
+  }> {
     return [
       {
         name: "wp_list_comments",
@@ -24,8 +25,7 @@ export class CommentTools {
           {
             name: "post",
             type: "number",
-            description:
-              "Limit results to comments assigned to a specific post ID.",
+            description: "Limit results to comments assigned to a specific post ID.",
           },
           {
             name: "status",
@@ -115,8 +115,7 @@ export class CommentTools {
           {
             name: "force",
             type: "boolean",
-            description:
-              "If true, the comment will be permanently deleted. Defaults to false (moved to trash).",
+            description: "If true, the comment will be permanently deleted. Defaults to false (moved to trash).",
           },
         ],
         handler: this.handleDeleteComment.bind(this),
@@ -150,12 +149,10 @@ export class CommentTools {
     ];
   }
 
-  public async handleListComments(
-    client: WordPressClient,
-    params: CommentQueryParams,
-  ): Promise<any> {
+  public async handleListComments(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
+    const queryParams = params as CommentQueryParams;
     try {
-      const comments = await client.getComments(params);
+      const comments = await client.getComments(queryParams);
       if (comments.length === 0) {
         return "No comments found matching the criteria.";
       }
@@ -173,12 +170,10 @@ export class CommentTools {
     }
   }
 
-  public async handleGetComment(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleGetComment(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
     try {
-      const comment = await client.getComment(params.id);
+      const { id } = params as { id: number };
+      const comment = await client.getComment(id);
       const content =
         `**Comment Details (ID: ${comment.id})**\n\n` +
         `- **Author:** ${comment.author_name}\n` +
@@ -192,12 +187,10 @@ export class CommentTools {
     }
   }
 
-  public async handleCreateComment(
-    client: WordPressClient,
-    params: CreateCommentRequest,
-  ): Promise<any> {
+  public async handleCreateComment(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
+    const createParams = params as unknown as CreateCommentRequest;
     try {
-      const comment = await client.createComment(params);
+      const comment = await client.createComment(createParams);
       return `✅ Comment created successfully with ID: ${comment.id}`;
     } catch (error) {
       throw new Error(`Failed to create comment: ${getErrorMessage(error)}`);
@@ -206,36 +199,33 @@ export class CommentTools {
 
   public async handleUpdateComment(
     client: WordPressClient,
-    params: UpdateCommentRequest & { id: number },
-  ): Promise<any> {
+    params: Record<string, unknown>,
+  ): Promise<unknown> {
     try {
-      const comment = await client.updateComment(params);
+      const updateParams = params as unknown as UpdateCommentRequest & { id: number };
+      const comment = await client.updateComment(updateParams);
       return `✅ Comment ${comment.id} updated successfully. New status: ${comment.status}.`;
     } catch (error) {
       throw new Error(`Failed to update comment: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleDeleteComment(
-    client: WordPressClient,
-    params: { id: number; force?: boolean },
-  ): Promise<any> {
+  public async handleDeleteComment(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
+    const { id, force } = params as { id: number; force?: boolean };
     try {
-      await client.deleteComment(params.id, params.force);
-      const action = params.force ? "permanently deleted" : "moved to trash";
-      return `✅ Comment ${params.id} has been ${action}.`;
+      await client.deleteComment(id, force);
+      const action = force ? "permanently deleted" : "moved to trash";
+      return `✅ Comment ${id} has been ${action}`;
     } catch (error) {
       throw new Error(`Failed to delete comment: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleApproveComment(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleApproveComment(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
+    const { id } = params as { id: number };
     try {
       const comment = await client.updateComment({
-        id: params.id,
+        id,
         status: "approved",
       });
       return `✅ Comment ${comment.id} has been approved.`;
@@ -244,20 +234,16 @@ export class CommentTools {
     }
   }
 
-  public async handleSpamComment(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleSpamComment(client: WordPressClient, params: Record<string, unknown>): Promise<unknown> {
+    const { id } = params as { id: number };
     try {
       const comment = await client.updateComment({
-        id: params.id,
+        id,
         status: "spam",
       });
       return `✅ Comment ${comment.id} has been marked as spam.`;
     } catch (error) {
-      throw new Error(
-        `Failed to mark comment as spam: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to mark comment as spam: ${getErrorMessage(error)}`);
     }
   }
 }