mcp-wordpress 2.6.3 → 2.7.0

package/src/client/managers/interfaces/ManagerInterfaces.ts

@@ -0,0 +1,171 @@
+/**
+ * Manager Interface Definitions
+ * Defines contracts for manager behaviors to enable composition over inheritance
+ */
+
+import type { WordPressClientConfig } from "@/types/client.js";
+
+/**
+ * Core configuration management interface
+ */
+export interface ConfigurationProvider {
+  readonly config: WordPressClientConfig;
+  
+  /**
+   * Get configuration value by path
+   */
+  getConfigValue<T>(path: string, defaultValue?: T): T | undefined;
+}
+
+/**
+ * Error handling interface for managers
+ */
+export interface ErrorHandler {
+  /**
+   * Handle and transform errors with context
+   */
+  handleError(error: unknown, operation: string): never;
+
+  /**
+   * Log successful operations
+   */
+  logSuccess(operation: string, details?: unknown): void;
+}
+
+/**
+ * Parameter validation interface
+ */
+export interface ParameterValidator {
+  /**
+   * Validate required parameters are present
+   */
+  validateRequired(params: Record<string, unknown>, requiredFields: string[]): void;
+
+  /**
+   * Validate parameter types and formats
+   */
+  validateParameters<T>(params: unknown, schema?: unknown): T;
+
+  /**
+   * Validate string parameters
+   */
+  validateString(value: unknown, fieldName: string, options?: {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+  }): string;
+
+  /**
+   * Validate WordPress ID parameters
+   */
+  validateWordPressId(value: unknown, fieldName?: string): number;
+}
+
+/**
+ * Base manager contract combining common behaviors
+ */
+export interface BaseManagerContract extends ConfigurationProvider, ErrorHandler, ParameterValidator {}
+
+/**
+ * Request management interface
+ */
+export interface RequestHandler {
+  /**
+   * Execute HTTP request with full request lifecycle management
+   */
+  request<T>(method: string, endpoint: string, data?: unknown, options?: unknown): Promise<T>;
+
+  /**
+   * Get request statistics
+   */
+  getStats(): unknown;
+
+  /**
+   * Reset statistics
+   */
+  resetStats(): void;
+}
+
+/**
+ * Authentication management interface
+ */
+export interface AuthenticationProvider {
+  /**
+   * Authenticate with the configured method
+   */
+  authenticate(): Promise<boolean>;
+
+  /**
+   * Check if currently authenticated
+   */
+  isAuthenticated(): boolean;
+
+  /**
+   * Get authentication headers for requests
+   */
+  getAuthHeaders(): Record<string, string>;
+
+  /**
+   * Handle authentication failure
+   */
+  handleAuthFailure(error: unknown): Promise<boolean>;
+}
+
+/**
+ * Manager factory interface for dependency injection
+ */
+export interface ManagerFactory {
+  /**
+   * Create configuration provider
+   */
+  createConfigurationProvider(config: WordPressClientConfig): ConfigurationProvider;
+
+  /**
+   * Create error handler
+   */
+  createErrorHandler(config: WordPressClientConfig): ErrorHandler;
+
+  /**
+   * Create parameter validator
+   */
+  createParameterValidator(): ParameterValidator;
+
+  /**
+   * Create request handler
+   */
+  createRequestHandler(config: WordPressClientConfig, authProvider: AuthenticationProvider): RequestHandler;
+
+  /**
+   * Create authentication provider
+   */
+  createAuthenticationProvider(config: WordPressClientConfig): AuthenticationProvider;
+}
+
+/**
+ * Configuration for manager composition
+ */
+export interface ManagerCompositionConfig {
+  /** WordPress client configuration */
+  clientConfig: WordPressClientConfig;
+  
+  /** Optional custom implementations */
+  customErrorHandler?: ErrorHandler;
+  customValidator?: ParameterValidator;
+  customAuthProvider?: AuthenticationProvider;
+}
+
+/**
+ * Composed manager that uses composition instead of inheritance
+ */
+export interface ComposedManager extends BaseManagerContract, RequestHandler, AuthenticationProvider {
+  /**
+   * Initialize the composed manager
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Cleanup resources
+   */
+  dispose(): void;
+}

package/src/config/Config.ts

@@ -74,6 +74,38 @@ export interface AppConfig {
     readonly isTravis: boolean;
     readonly isCircleCI: boolean;
   };
+
+  // SEO Configuration
+  readonly seo: {
+    readonly enabled: boolean;
+    readonly providers: {
+      readonly searchConsole: boolean;
+      readonly dataForSEO: boolean;
+      readonly ahrefs: boolean;
+    };
+    readonly limits: {
+      readonly bulkOperationSize: number;
+      readonly rateLimitPerMinute: number;
+      readonly maxConcurrentAnalysis: number;
+    };
+    readonly cache: {
+      readonly analysisTTL: number;
+      readonly schemaTTL: number;
+      readonly auditTTL: number;
+      readonly keywordsTTL: number;
+    };
+    readonly metadata: {
+      readonly titleMaxLength: number;
+      readonly descriptionMaxLength: number;
+      readonly descriptionMinLength: number;
+    };
+    readonly analysis: {
+      readonly minWordCount: number;
+      readonly targetKeywordDensity: number;
+      readonly maxKeywordDensity: number;
+      readonly minReadabilityScore: number;
+    };
+  };
 }
 
 /**
@@ -174,6 +206,37 @@ export class Config {
         isTravis: process.env.TRAVIS === "true",
         isCircleCI: process.env.CIRCLECI === "true",
       },
+
+      seo: {
+        enabled: process.env.SEO_ENABLED !== "false",
+        providers: {
+          searchConsole: process.env.SEO_PROVIDER_SEARCH_CONSOLE === "true",
+          dataForSEO: process.env.SEO_PROVIDER_DATAFORSEO === "true",
+          ahrefs: process.env.SEO_PROVIDER_AHREFS === "true",
+        },
+        limits: {
+          bulkOperationSize: parseInt(process.env.SEO_BULK_OPERATION_SIZE || "10", 10),
+          rateLimitPerMinute: parseInt(process.env.SEO_RATE_LIMIT_PER_MINUTE || "30", 10),
+          maxConcurrentAnalysis: parseInt(process.env.SEO_MAX_CONCURRENT_ANALYSIS || "5", 10),
+        },
+        cache: {
+          analysisTTL: parseInt(process.env.SEO_CACHE_ANALYSIS_TTL || "21600", 10), // 6 hours
+          schemaTTL: parseInt(process.env.SEO_CACHE_SCHEMA_TTL || "86400", 10), // 24 hours
+          auditTTL: parseInt(process.env.SEO_CACHE_AUDIT_TTL || "3600", 10), // 1 hour
+          keywordsTTL: parseInt(process.env.SEO_CACHE_KEYWORDS_TTL || "604800", 10), // 7 days
+        },
+        metadata: {
+          titleMaxLength: parseInt(process.env.SEO_TITLE_MAX_LENGTH || "60", 10),
+          descriptionMaxLength: parseInt(process.env.SEO_DESCRIPTION_MAX_LENGTH || "160", 10),
+          descriptionMinLength: parseInt(process.env.SEO_DESCRIPTION_MIN_LENGTH || "155", 10),
+        },
+        analysis: {
+          minWordCount: parseInt(process.env.SEO_MIN_WORD_COUNT || "300", 10),
+          targetKeywordDensity: parseFloat(process.env.SEO_TARGET_KEYWORD_DENSITY || "2.5"),
+          maxKeywordDensity: parseFloat(process.env.SEO_MAX_KEYWORD_DENSITY || "3.5"),
+          minReadabilityScore: parseFloat(process.env.SEO_MIN_READABILITY_SCORE || "60"),
+        },
+      },
     };
   }
 

package/src/config/ConfigurationSchema.ts

@@ -142,12 +142,12 @@ export class ConfigurationValidator {
   static validateMultiSiteConfig(config: unknown): MultiSiteConfigType {
     try {
       return MultiSiteConfigSchema.parse(config);
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const messages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+    } catch (_error) {
+      if (_error instanceof z.ZodError) {
+        const messages = _error.issues.map((err: z.ZodIssue) => `${err.path.join(".")}: ${err.message}`).join("; ");
         throw new Error(`Multi-site configuration validation failed: ${messages}`);
       }
-      throw error;
+      throw _error;
     }
   }
 
@@ -157,12 +157,12 @@ export class ConfigurationValidator {
   static validateEnvironmentConfig(env: Record<string, string | undefined>): EnvironmentConfigType {
     try {
       return EnvironmentConfigSchema.parse(env);
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const messages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+    } catch (_error) {
+      if (_error instanceof z.ZodError) {
+        const messages = _error.issues.map((err: z.ZodIssue) => `${err.path.join(".")}: ${err.message}`).join("; ");
         throw new Error(`Environment configuration validation failed: ${messages}`);
       }
-      throw error;
+      throw _error;
     }
   }
 
@@ -172,12 +172,12 @@ export class ConfigurationValidator {
   static validateMcpConfig(config: unknown): McpConfigType {
     try {
       return McpConfigSchema.parse(config);
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const messages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+    } catch (_error) {
+      if (_error instanceof z.ZodError) {
+        const messages = _error.issues.map((err: z.ZodIssue) => `${err.path.join(".")}: ${err.message}`).join("; ");
         throw new Error(`MCP configuration validation failed: ${messages}`);
       }
-      throw error;
+      throw _error;
     }
   }
 
@@ -187,12 +187,12 @@ export class ConfigurationValidator {
   static validateSiteConfig(config: unknown): SiteType {
     try {
       return SiteSchema.parse(config);
-    } catch (error) {
-      if (error instanceof z.ZodError) {
-        const messages = error.errors.map((err) => `${err.path.join(".")}: ${err.message}`).join("; ");
+    } catch (_error) {
+      if (_error instanceof z.ZodError) {
+        const messages = _error.issues.map((err: z.ZodIssue) => `${err.path.join(".")}: ${err.message}`).join("; ");
         throw new Error(`Site configuration validation failed: ${messages}`);
       }
-      throw error;
+      throw _error;
     }
   }
 
@@ -220,7 +220,7 @@ export class ConfigurationValidator {
     if (result.success) {
       return [];
     }
-    return result.error.errors.map((err) => `${err.path.join(".")}: ${err.message}`);
+    return result.error.issues.map((err: z.ZodIssue) => `${err.path.join(".")}: ${err.message}`);
   }
 }
 

package/src/config/ServerConfiguration.ts

@@ -1,5 +1,5 @@
 import dotenv from "dotenv";
-import * as fs from "fs";
+import { promises as fsPromises } from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { WordPressClient } from "../client/api.js";
@@ -46,10 +46,10 @@ export class ServerConfiguration {
       console.log = () => {};
       // eslint-disable-next-line no-console
       console.error = () => {};
-      dotenv.config({ 
+      dotenv.config({
         path: this.envPath,
         debug: false,
-        override: false
+        override: false,
       });
     } finally {
       // eslint-disable-next-line no-console
@@ -63,7 +63,7 @@ export class ServerConfiguration {
       this.logger.debug("ServerConfiguration initialized", {
         rootDir: this.rootDir,
         envPath: this.envPath,
-        envFileExists: fs.existsSync(this.envPath),
+        // Note: envFileExists check moved to async initialization
       });
     }
   }
@@ -82,18 +82,20 @@ export class ServerConfiguration {
    * Load WordPress client configurations
    * Returns a Map of site ID to WordPressClient instances
    */
-  public loadClientConfigurations(mcpConfig?: McpConfigType): {
+  public async loadClientConfigurations(mcpConfig?: McpConfigType): Promise<{
     clients: Map<string, WordPressClient>;
     configs: SiteConfig[];
-  } {
+  }> {
     const configPath = path.resolve(this.rootDir, "mcp-wordpress.config.json");
 
-    if (fs.existsSync(configPath)) {
+    try {
+      await fsPromises.access(configPath);
       if (ConfigHelpers.shouldLogInfo()) {
         this.logger.info("Found multi-site configuration file", { configPath });
       }
-      return this.loadMultiSiteConfig(configPath);
-    } else {
+      return await this.loadMultiSiteConfig(configPath);
+    } catch (_error) {
+      // Config file doesn't exist or is not accessible
       if (ConfigHelpers.shouldLogInfo()) {
         this.logger.info("Multi-site config not found, using environment variables for single-site mode", {
           configPath,
@@ -106,12 +108,12 @@ export class ServerConfiguration {
   /**
    * Load multi-site configuration from JSON file
    */
-  private loadMultiSiteConfig(configPath: string): {
+  private async loadMultiSiteConfig(configPath: string): Promise<{
     clients: Map<string, WordPressClient>;
     configs: SiteConfig[];
-  } {
+  }> {
     try {
-      const configFile = fs.readFileSync(configPath, "utf-8");
+      const configFile = await fsPromises.readFile(configPath, "utf-8");
       const rawConfig = JSON.parse(configFile);
 
       // Validate configuration using Zod schema
@@ -147,10 +149,10 @@ export class ServerConfiguration {
       }
 
       return { clients, configs: validConfigs };
-    } catch (error) {
+    } catch (_error) {
       this.logger.fatal("Failed to load multi-site configuration", {
         configPath,
-        error: getErrorMessage(error),
+        _error: getErrorMessage(_error),
       });
       process.exit(1);
     }
@@ -287,9 +289,9 @@ export class ServerConfiguration {
       }
 
       return { clients, configs: [siteConfig] };
-    } catch (error) {
+    } catch (_error) {
       this.logger.error("Configuration validation failed for single-site mode", {
-        error: getErrorMessage(error),
+        _error: getErrorMessage(_error),
         suggestion: "Please check your environment variables or MCP configuration",
       });
       return { clients: new Map(), configs: [] };

package/src/config/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration Barrel Export
+ * Centralized exports for all configuration management
+ */
+
+// Main Configuration System
+export { Config, ConfigHelpers, config } from './Config.js';
+
+// Configuration Schema and Validation
+export * from './ConfigurationSchema.js';
+
+// Server Configuration (legacy)
+export * from './ServerConfiguration.js';

package/src/docs/DocumentationGenerator.ts

@@ -193,8 +193,8 @@ export class DocumentationGenerator {
           const doc = await this.extractToolDocumentation(toolDef as ToolDefinition, category, className);
           toolDocs.push(doc);
         }
-      } catch (error) {
-        this.logger.warn(`⚠️ Failed to extract documentation for ${className}:`, { error: String(error) });
+      } catch (_error) {
+        this.logger.warn(`⚠️ Failed to extract documentation for ${className}:`, { _error: String(_error) });
       }
     }
 

package/src/dxt-entry.ts

@@ -34,9 +34,9 @@ async function startDXTServer() {
 
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
-  } catch (error) {
-    logger.fatal(`DXT server failed to start: ${error instanceof Error ? error.message : String(error)}`);
-    logger.fatal(`Stack trace: ${error instanceof Error ? error.stack : "No stack trace available"}`);
+  } catch (_error) {
+    logger.fatal(`DXT server failed to start: ${_error instanceof Error ? _error.message : String(_error)}`);
+    logger.fatal(`Stack trace: ${_error instanceof Error ? _error.stack : "No stack trace available"}`);
     process.exit(1);
   }
 }

package/src/index.ts

@@ -9,9 +9,7 @@ import { getErrorMessage } from "./utils/error.js";
 import { LoggerFactory } from "./utils/logger.js";
 import { ConfigHelpers } from "./config/Config.js";
 import { McpConfigType } from "./config/ServerConfiguration.js";
-
-// --- Constants ---
-const SERVER_VERSION = "1.1.8"; // Technical debt resolution and modular architecture
+import { getVersion, getDisplayVersion } from "./utils/version.js";
 
 // --- Main Server Class ---
 class MCPWordPressServer {
@@ -19,42 +17,20 @@ class MCPWordPressServer {
   private wordpressClients: Map<string, WordPressClient> = new Map();
   private initialized: boolean = false;
   private siteConfigs: SiteConfig[] = [];
-  private toolRegistry: ToolRegistry;
+  private toolRegistry!: ToolRegistry;
   private logger = LoggerFactory.server();
 
-  constructor(mcpConfig?: McpConfigType) {
-    this.loadConfiguration(mcpConfig);
-
-    if (this.wordpressClients.size === 0) {
-      // In test environments, don't exit the process
-      if (ConfigHelpers.isCI() || ConfigHelpers.isTest() || (globalThis as Record<string, unknown>).__EXECUTION_CONTEXT__ === "jest") {
-        this.logger.warn("No WordPress sites configured in test environment");
-        // Create a dummy client for testing
-        this.wordpressClients.set("test", {} as WordPressClient);
-      } else {
-        this.logger.fatal("No WordPress sites configured. Server cannot start.", {
-          expectedEnvVars: [
-            "WORDPRESS_SITE_URL",
-            "WORDPRESS_USERNAME", 
-            "WORDPRESS_APP_PASSWORD"
-          ]
-        });
-        process.exit(1);
-      }
-    }
-
+  constructor(private mcpConfig?: McpConfigType) {
+    // Server initialization will happen in run() method
     this.server = new McpServer({
       name: "mcp-wordpress",
-      version: SERVER_VERSION,
+      version: getVersion(),
     });
-
-    this.toolRegistry = new ToolRegistry(this.server, this.wordpressClients);
-    this.setupTools();
   }
 
-  private loadConfiguration(mcpConfig?: McpConfigType) {
+  private async loadConfiguration(mcpConfig?: McpConfigType) {
     const serverConfig = ServerConfiguration.getInstance();
-    const { clients, configs } = serverConfig.loadClientConfigurations(mcpConfig);
+    const { clients, configs } = await serverConfig.loadClientConfigurations(mcpConfig);
 
     this.wordpressClients = clients;
     this.siteConfigs = configs;
@@ -68,24 +44,48 @@ class MCPWordPressServer {
     // Use optimized connection testing with timeouts and concurrency control
     await ConnectionTester.testClientConnections(this.wordpressClients, {
       timeout: ConfigHelpers.getTimeout("test"),
-      maxConcurrent: ConfigHelpers.isCI() ? 2 : 3 // Reduce concurrency in CI
+      maxConcurrent: ConfigHelpers.isCI() ? 2 : 3, // Reduce concurrency in CI
     });
     this.initialized = true;
   }
 
   async run() {
+    // Load configuration asynchronously
+    await this.loadConfiguration(this.mcpConfig);
+
+    if (this.wordpressClients.size === 0) {
+      // In test environments, don't exit the process
+      if (
+        ConfigHelpers.isCI() ||
+        ConfigHelpers.isTest() ||
+        (globalThis as Record<string, unknown>).__EXECUTION_CONTEXT__ === "jest"
+      ) {
+        this.logger.warn("No WordPress sites configured in test environment");
+        // Create a dummy client for testing
+        this.wordpressClients.set("test", {} as WordPressClient);
+      } else {
+        this.logger.fatal("No WordPress sites configured. Server cannot start.", {
+          expectedEnvVars: ["WORDPRESS_SITE_URL", "WORDPRESS_USERNAME", "WORDPRESS_APP_PASSWORD"],
+        });
+        process.exit(1);
+      }
+    }
+
+    this.toolRegistry = new ToolRegistry(this.server, this.wordpressClients);
+    this.setupTools();
+
     // Skip connection testing in DXT environment to prevent timeouts
     const isDXTMode = ConfigHelpers.isDXT() || process.argv[0]?.includes("dxt-entry");
 
     if (!this.initialized && !isDXTMode) {
       this.logger.info("Testing connections to configured WordPress sites...", {
-        siteCount: this.wordpressClients.size
+        siteCount: this.wordpressClients.size,
       });
       try {
         await this.testClientConnections();
-      } catch (error) {
+      } catch (_error) {
         this.logger.warn("Connection test failed - continuing with server startup", {
-          error: getErrorMessage(error)
+          _error: getErrorMessage(_error),
         });
       }
     } else if (isDXTMode) {
@@ -94,8 +94,8 @@ class MCPWordPressServer {
     }
 
     this.logger.info("Starting MCP WordPress Server...", {
-      version: SERVER_VERSION,
-      sites: this.wordpressClients.size
+      version: getDisplayVersion(),
+      sites: this.wordpressClients.size,
     });
 
     // Connect to stdio transport with timeout
@@ -112,14 +112,14 @@ class MCPWordPressServer {
       clearTimeout(connectionTimeout);
 
       this.logger.info("Server started and connected successfully", {
-        sites: this.wordpressClients.size
+        sites: this.wordpressClients.size,
       });
 
       // Keep the process alive
       process.stdin.resume();
-    } catch (error) {
+    } catch (_error) {
       clearTimeout(connectionTimeout);
-      throw error;
+      throw _error;
     }
   }
 
@@ -133,7 +133,7 @@ class MCPWordPressServer {
 // --- Main Execution ---
 async function main() {
   const mainLogger = LoggerFactory.server();
-  
+
   try {
     const mcpServer = new MCPWordPressServer();
     await mcpServer.run();
@@ -145,8 +145,8 @@ async function main() {
 
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
-  } catch (error) {
-    mainLogger.fatal("Failed to start server", { error: getErrorMessage(error) });
+  } catch (_error) {
+    mainLogger.fatal("Failed to start server", { _error: getErrorMessage(_error) });
     process.exit(1);
   }
 }

package/src/performance/MetricsCollector.ts

@@ -178,6 +178,7 @@ export class MetricsCollector {
       averageResponseTime: 0,
       rateLimitHits: 0,
       authFailures: 0,
+      errors: 0,
     };
 
     const responseTimes: number[] = [];
@@ -252,13 +253,16 @@ export class MetricsCollector {
     worstPerforming: string;
   } {
     const sites = Array.from(this.clientInstances.keys());
-    const comparison: Record<string, {
-      responseTime: number;
-      cacheHitRate: number;
-      errorRate: number;
-      requestCount: number;
-      ranking: number;
-    }> = {};
+    const comparison: Record<
+      string,
+      {
+        responseTime: number;
+        cacheHitRate: number;
+        errorRate: number;
+        requestCount: number;
+        ranking: number;
+      }
+    > = {};
     const rankings: Array<{ site: string; score: number }> = [];
 
     for (const siteId of sites) {
@@ -401,9 +405,9 @@ export class MetricsCollector {
         this.updateCacheMetrics();
         this.updateClientMetrics();
         this.logger.debug("Real-time metrics updated");
-      } catch (error) {
+      } catch (_error) {
         this.logger.error("Failed to update real-time metrics", {
-          error: error instanceof Error ? error.message : String(error),
+          _error: _error instanceof Error ? _error.message : String(_error),
         });
       }
     }, interval);
@@ -480,12 +484,12 @@ export class MetricsCollector {
         this.activeRequests.delete(requestId);
 
         return result;
-      } catch (error) {
+      } catch (_error) {
         const responseTime = Date.now() - startTime;
         this.monitor.recordRequest(responseTime, false);
         this.activeRequests.delete(requestId);
 
-        throw error;
+        throw _error;
       }
     };
   }