mcp-wordpress 1.1.7 → 1.2.2

package/src/server/ToolRegistry.ts

@@ -0,0 +1,194 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WordPressClient } from '../client/api.js';
+import { getErrorMessage } from '../utils/error.js';
+import * as Tools from '../tools/index.js';
+import { z } from 'zod';
+
+/**
+ * Interface for tool definition
+ */
+export interface ToolDefinition {
+  name: string;
+  description?: string;
+  parameters?: Array<{
+    name: string;
+    type: string;
+    description?: string;
+    required?: boolean;
+  }>;
+  handler: (client: WordPressClient, args: any) => Promise<any>;
+}
+
+/**
+ * Registry for managing MCP tools
+ * Handles tool registration, parameter validation, and execution
+ */
+export class ToolRegistry {
+  private server: McpServer;
+  private wordpressClients: Map<string, WordPressClient>;
+
+  constructor(server: McpServer, wordpressClients: Map<string, WordPressClient>) {
+    this.server = server;
+    this.wordpressClients = wordpressClients;
+  }
+
+  /**
+   * Register all available tools with the MCP server
+   */
+  public registerAllTools(): void {
+    // Register all tools from the tools directory
+    Object.values(Tools).forEach((ToolClass) => {
+      let toolInstance: any;
+      
+      // Cache and Performance tools need the clients map
+      if (ToolClass.name === 'CacheTools' || ToolClass.name === 'PerformanceTools') {
+        toolInstance = new ToolClass(this.wordpressClients);
+      } else {
+        toolInstance = new (ToolClass as new () => any)();
+      }
+      
+      const tools = toolInstance.getTools();
+
+      tools.forEach((tool: ToolDefinition) => {
+        this.registerTool(tool);
+      });
+    });
+  }
+
+  /**
+   * Register a single tool with parameter validation and execution handling
+   */
+  private registerTool(tool: ToolDefinition): void {
+    // Create base parameter schema with site parameter
+    const baseSchema = {
+      site: z
+        .string()
+        .optional()
+        .describe(
+          'The ID of the WordPress site to target (from mcp-wordpress.config.json). Required if multiple sites are configured.'
+        )
+    };
+
+    // Merge with tool-specific parameters
+    const parameterSchema = this.buildParameterSchema(tool, baseSchema);
+
+    // Make site parameter required if multiple sites are configured
+    if (this.wordpressClients.size > 1) {
+      parameterSchema.site = parameterSchema.site.describe(
+        'The ID of the WordPress site to target (from mcp-wordpress.config.json). Required when multiple sites are configured.'
+      );
+    }
+
+    this.server.tool(
+      tool.name,
+      tool.description || `WordPress tool: ${tool.name}`,
+      parameterSchema,
+      async (args: any) => {
+        try {
+          const siteId = args.site || 'default';
+          const client = this.wordpressClients.get(siteId);
+
+          if (!client) {
+            const availableSites = Array.from(this.wordpressClients.keys()).join(', ');
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: `Error: Site with ID '${siteId}' not found. Available sites: ${availableSites}`
+                }
+              ],
+              isError: true
+            };
+          }
+
+          // Call the tool handler with the client and parameters
+          const result = await tool.handler(client, args);
+
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: typeof result === 'string' ? result : JSON.stringify(result, null, 2)
+              }
+            ]
+          };
+        } catch (error) {
+          if (this.isAuthenticationError(error)) {
+            return {
+              content: [
+                {
+                  type: 'text' as const,
+                  text: `Authentication failed for site '${args.site || 'default'}'. Please check your credentials.`
+                }
+              ],
+              isError: true
+            };
+          }
+
+          return {
+            content: [
+              {
+                type: 'text' as const,
+                text: `Error: ${getErrorMessage(error)}`
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+    );
+  }
+
+  /**
+   * Build Zod parameter schema from tool definition
+   */
+  private buildParameterSchema(tool: ToolDefinition, baseSchema: any): any {
+    return tool.parameters?.reduce(
+      (schema: any, param: any) => {
+        let zodType = this.getZodTypeForParameter(param);
+
+        if (param.description) {
+          zodType = zodType.describe(param.description);
+        }
+
+        if (!param.required) {
+          zodType = zodType.optional();
+        }
+
+        schema[param.name] = zodType;
+        return schema;
+      },
+      { ...baseSchema }
+    ) || baseSchema;
+  }
+
+  /**
+   * Get appropriate Zod type for parameter definition
+   */
+  private getZodTypeForParameter(param: any): z.ZodType {
+    switch (param.type) {
+    case 'string':
+      return z.string();
+    case 'number':
+      return z.number();
+    case 'boolean':
+      return z.boolean();
+    case 'array':
+      return z.array(z.string());
+    case 'object':
+      return z.record(z.any());
+    default:
+      return z.string();
+    }
+  }
+
+  /**
+   * Check if error is authentication-related
+   */
+  private isAuthenticationError(error: any): boolean {
+    if (error?.response?.status && [401, 403].includes(error.response.status)) {
+      return true;
+    }
+    return error?.code === 'WORDPRESS_AUTH_ERROR';
+  }
+}

package/src/tools/BaseToolManager.ts

@@ -0,0 +1,66 @@
+/**
+ * Base utility class for tool managers to reduce code duplication
+ */
+
+import { getErrorMessage } from '../utils/error.js';
+
+export class BaseToolUtils {
+  /**
+   * Validate required parameters
+   */
+  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}`);
+      }
+    }
+  }
+
+  /**
+   * Validate ID parameter
+   */
+  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`);
+    }
+    return numId;
+  }
+
+  /**
+   * Handle errors consistently across all tools
+   */
+  static handleError(error: unknown, operation: string): string {
+    const errorMessage = getErrorMessage(error);
+    return `Error in ${operation}: ${errorMessage}`;
+  }
+
+  /**
+   * Cache key generation helper
+   */
+  static generateCacheKey(
+    operation: string,
+    params: Record<string, unknown>
+  ): string {
+    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}`;
+  }
+
+  /**
+   * Format consistent response messages
+   */
+  static formatSuccessMessage(operation: string, details?: string): string {
+    return details
+      ? `${operation}: ${details}`
+      : `${operation} completed successfully`;
+  }
+}

package/src/tools/cache.ts

@@ -0,0 +1,259 @@
+/**
+ * Cache management tools for WordPress MCP Server
+ * Provides cache inspection, clearing, and warming capabilities
+ */
+
+import type { WordPressClient } from '../client/api.js';
+import { CachedWordPressClient } from '../client/CachedWordPressClient.js';
+import { toolWrapper } from '../utils/toolWrapper.js';
+
+/**
+ * Cache management tools class
+ */
+export class CacheTools {
+  constructor(private clients: Map<string, WordPressClient>) {}
+
+  /**
+   * Get cache management tools
+   */
+  getTools() {
+    return [
+      {
+        name: 'wp_cache_stats',
+        description: 'Get cache statistics for a WordPress site.',
+        parameters: [
+          {
+            name: 'site',
+            type: 'string',
+            description: 'Site ID to get cache stats for. If not provided, uses default site or fails if multiple sites configured.'
+          }
+        ],
+        handler: this.handleGetCacheStats.bind(this)
+      },
+      {
+        name: 'wp_cache_clear',
+        description: 'Clear cache for a WordPress site.',
+        parameters: [
+          {
+            name: 'site',
+            type: 'string',
+            description: 'Site ID to clear cache for.'
+          },
+          {
+            name: 'pattern',
+            type: 'string',
+            description: 'Optional pattern to clear specific cache entries (e.g., "posts", "categories").'
+          }
+        ],
+        handler: this.handleClearCache.bind(this)
+      },
+      {
+        name: 'wp_cache_warm',
+        description: 'Pre-warm cache with essential WordPress data.',
+        parameters: [
+          {
+            name: 'site',
+            type: 'string',
+            description: 'Site ID to warm cache for.'
+          }
+        ],
+        handler: this.handleWarmCache.bind(this)
+      },
+      {
+        name: 'wp_cache_info',
+        description: 'Get detailed cache configuration and status information.',
+        parameters: [
+          {
+            name: 'site',
+            type: 'string',
+            description: 'Site ID to get cache info for.'
+          }
+        ],
+        handler: this.handleGetCacheInfo.bind(this)
+      }
+    ];
+  }
+
+  /**
+   * Get cache statistics
+   */
+  async handleGetCacheStats(params: { site?: string }) {
+    return toolWrapper(async () => {
+      const client = this.resolveClient(params.site);
+      
+      if (!(client instanceof CachedWordPressClient)) {
+        return {
+          caching_enabled: false,
+          message: 'Caching is disabled for this site. Set DISABLE_CACHE=false to enable caching.'
+        };
+      }
+
+      const stats = client.getCacheStats();
+      
+      return {
+        caching_enabled: true,
+        cache_stats: {
+          hits: stats.cache.hits,
+          misses: stats.cache.misses,
+          hit_rate: Math.round(stats.cache.hitRate * 100) + '%',
+          total_entries: stats.cache.totalSize,
+          evictions: stats.cache.evictions
+        },
+        invalidation_stats: {
+          queue_size: stats.invalidation.queueSize,
+          rules_count: stats.invalidation.rulesCount,
+          processing: stats.invalidation.processing
+        }
+      };
+    });
+  }
+
+  /**
+   * Clear cache
+   */
+  async handleClearCache(params: { site?: string; pattern?: string }) {
+    return toolWrapper(async () => {
+      const client = this.resolveClient(params.site);
+      
+      if (!(client instanceof CachedWordPressClient)) {
+        return {
+          success: false,
+          message: 'Caching is not enabled for this site.'
+        };
+      }
+
+      let cleared: number;
+      
+      if (params.pattern) {
+        cleared = client.clearCachePattern(params.pattern);
+        return {
+          success: true,
+          message: `Cleared ${cleared} cache entries matching pattern "${params.pattern}".`,
+          cleared_entries: cleared,
+          pattern: params.pattern
+        };
+      } else {
+        cleared = client.clearCache();
+        return {
+          success: true,
+          message: `Cleared all cache entries (${cleared} total).`,
+          cleared_entries: cleared
+        };
+      }
+    });
+  }
+
+  /**
+   * Warm cache with essential data
+   */
+  async handleWarmCache(params: { site?: string }) {
+    return toolWrapper(async () => {
+      const client = this.resolveClient(params.site);
+      
+      if (!(client instanceof CachedWordPressClient)) {
+        return {
+          success: false,
+          message: 'Caching is not enabled for this site.'
+        };
+      }
+
+      await client.warmCache();
+      
+      const stats = client.getCacheStats();
+      
+      return {
+        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'
+        ]
+      };
+    });
+  }
+
+  /**
+   * Get detailed cache information
+   */
+  async handleGetCacheInfo(params: { site?: string }) {
+    return toolWrapper(async () => {
+      const client = this.resolveClient(params.site);
+      
+      if (!(client instanceof CachedWordPressClient)) {
+        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.'
+        };
+      }
+
+      const stats = client.getCacheStats();
+      
+      return {
+        caching_enabled: true,
+        cache_configuration: {
+          max_size: 'Configured in SecurityConfig.cache.maxSize',
+          default_ttl: 'Configured in SecurityConfig.cache.defaultTTL',
+          lru_enabled: 'Configured in SecurityConfig.cache.enableLRU',
+          stats_enabled: 'Configured in SecurityConfig.cache.enableStats'
+        },
+        ttl_presets: {
+          static_data: '4 hours (site settings, user roles)',
+          semi_static_data: '2 hours (categories, tags, user profiles)',
+          dynamic_data: '15 minutes (posts, pages, comments)',
+          session_data: '30 minutes (authentication, current user)',
+          realtime_data: '1 minute (real-time data)'
+        },
+        current_stats: {
+          total_entries: stats.cache.totalSize,
+          hit_rate: Math.round(stats.cache.hitRate * 100) + '%',
+          hits: stats.cache.hits,
+          misses: stats.cache.misses,
+          evictions: stats.cache.evictions
+        },
+        invalidation_info: {
+          queue_size: stats.invalidation.queueSize,
+          rules_registered: stats.invalidation.rulesCount,
+          currently_processing: stats.invalidation.processing
+        },
+        performance_benefits: [
+          'Reduced API calls to WordPress',
+          'Faster response times for repeated requests',
+          'Better rate limit utilization',
+          'Improved user experience'
+        ]
+      };
+    });
+  }
+
+  /**
+   * Resolve client from site parameter
+   */
+  private resolveClient(siteId?: string): WordPressClient {
+    if (!siteId) {
+      if (this.clients.size === 1) {
+        return Array.from(this.clients.values())[0];
+      } else if (this.clients.size === 0) {
+        throw new Error('No WordPress sites configured.');
+      } else {
+        throw new Error(
+          `Multiple sites configured. Please specify --site parameter. Available sites: ${Array.from(this.clients.keys()).join(', ')}`
+        );
+      }
+    }
+
+    const client = this.clients.get(siteId);
+    if (!client) {
+      throw new Error(
+        `Site "${siteId}" not found. Available sites: ${Array.from(this.clients.keys()).join(', ')}`
+      );
+    }
+
+    return client;
+  }
+}
+
+export default CacheTools;

package/src/tools/index.ts

@@ -1,7 +1,9 @@
 export { default as AuthTools } from './auth.js';
+export { default as CacheTools } from './cache.js';
 export { default as CommentTools } from './comments.js';
 export { default as MediaTools } from './media.js';
 export { default as PageTools } from './pages.js';
+export { default as PerformanceTools } from './performance.js';
 export { default as PostTools } from './posts.js';
 export { default as SiteTools } from './site.js';
 export { default as TaxonomyTools } from './taxonomies.js';