mcp-wordpress 2.11.13 → 3.0.0

package/docs/DEPRECATIONS.md

@@ -0,0 +1,157 @@
+# Deprecation Guide
+
+This document tracks deprecated APIs and provides migration guidance for the MCP WordPress project.
+
+## Deprecation Policy
+
+- **Deprecation Notice**: APIs are marked with `@deprecated` JSDoc tag
+- **Warning Period**: Deprecated APIs remain functional for at least 2 minor versions
+- **Removal Timeline**: Removal is announced in CHANGELOG.md before the breaking release
+
+## Currently Deprecated APIs
+
+### 1. Legacy Import Modules
+
+#### `src/tools/posts.ts` (Re-export Module)
+
+**Status**: Deprecated since v2.10.0 | **Removal**: v3.0.0
+
+**Reason**: Refactored to modular structure for better maintainability.
+
+**Migration**:
+
+```typescript
+// Before (deprecated)
+import PostTools from "./tools/posts.js";
+import { handleCreatePost } from "./tools/posts.js";
+
+// After (recommended)
+import { PostTools } from "./tools/posts/index.js";
+import { handleCreatePost } from "./tools/posts/PostHandlers.js";
+```
+
+**Note**: The legacy import still works and will continue to work until v3.0.0.
+
+---
+
+#### `src/utils/validation.ts` (Re-export Module)
+
+**Status**: Deprecated since v2.8.0 | **Removal**: v3.0.0
+
+**Reason**: Refactored to modular structure with focused validation modules.
+
+**Migration**:
+
+```typescript
+// Before (deprecated)
+import { validateId, sanitizeHtml, RateLimiter } from "./utils/validation.js";
+
+// After (recommended) - Import from specific modules
+import { validateId } from "./utils/validation/core.js";
+import { sanitizeHtml } from "./utils/validation/security.js";
+import { RateLimiter } from "./utils/validation/rate-limiter.js";
+
+// Or use the new index (also acceptable)
+import { validateId, sanitizeHtml, RateLimiter } from "./utils/validation/index.js";
+```
+
+**Available Modules**:
+
+| Module                       | Exports                                                                       |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `validation/core.js`         | `validateId`, `validateString`, `validateArray`                               |
+| `validation/security.js`     | `validateFilePath`, `validateFileSize`, `validateMimeType`, `sanitizeHtml`    |
+| `validation/network.js`      | `validateUrl`, `validateEmail`, `validateUsername`                            |
+| `validation/wordpress.js`    | `validatePostStatus`, `validateSearchQuery`, `validatePaginationParams`, etc. |
+| `validation/rate-limiter.js` | `RateLimiter`, `authRateLimiter`                                              |
+
+---
+
+#### `src/tools/performance.ts` (Re-export Module)
+
+**Status**: Deprecated since v2.12.0 | **Removal**: v3.0.0
+
+**Reason**: Refactored to modular structure for better maintainability.
+
+**Migration**:
+
+```typescript
+// Before (deprecated)
+import PerformanceTools from "./tools/performance.js";
+
+// After (recommended)
+import { PerformanceTools } from "./tools/performance/index.js";
+import { calculateHealthStatus, formatUptime } from "./tools/performance/PerformanceHelpers.js";
+```
+
+---
+
+### 2. Internal Method Deprecations
+
+#### `VersionManager.loadVersionSync()` (Private Method)
+
+**Status**: Deprecated since v2.5.0 | **Removal**: v3.0.0
+
+**Reason**: Async initialization provides better performance.
+
+**Migration**:
+
+```typescript
+// Before (deprecated pattern)
+const version = VersionManager.getInstance().getVersion(); // May load sync
+
+// After (recommended)
+const manager = VersionManager.getInstance();
+await manager.initialize(); // Async load
+const version = manager.getVersion(); // Uses cached value
+```
+
+---
+
+## Upcoming Deprecations (v2.13.0)
+
+The following items are candidates for deprecation in future releases:
+
+### Legacy Alias Exports
+
+Located in `src/utils/validation.ts`:
+
+- `validateWordPressId` → Use `validateId` from `validation/core.js`
+- `validatePostData` → Use `validatePostParams` from `validation/wordpress.js`
+- `cleanHtml` → Use `sanitizeHtml` from `validation/security.js`
+
+---
+
+## Removed APIs
+
+### v2.0.0 (Breaking Release)
+
+| Removed                      | Replacement                    |
+| ---------------------------- | ------------------------------ |
+| `WordPressClient.connect()`  | `WordPressClient.initialize()` |
+| `config.getEnv()`            | `config().app`                 |
+
+---
+
+## Migration Assistance
+
+If you need help migrating from deprecated APIs:
+
+1. Check this document for migration examples
+2. Review the CHANGELOG.md for version-specific changes
+3. Run `npm run lint` to catch deprecated import warnings
+4. Open an issue on GitHub for migration questions
+
+## Version Support Matrix
+
+| Version  | Status        | Deprecations Active | End of Support   |
+| -------- | ------------- | ------------------- | ---------------- |
+| v2.12.x  | Current       | Yes                 | -                |
+| v2.11.x  | Maintained    | Yes                 | v2.14.0 release  |
+| v2.10.x  | Security Only | Yes                 | v2.13.0 release  |
+| v2.9.x   | End of Life   | N/A                 | Ended            |
+| v3.0.0   | Planned       | Removed             | -                |
+
+---
+
+*Last updated: December 2024*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-wordpress",
-  "version": "2.11.13",
+  "version": "3.0.0",
   "description": "Comprehensive Model Context Protocol server for WordPress management with composition-based architecture, 59 tools, SEO toolkit, performance monitoring, intelligent caching, and production-ready authentication",
   "keywords": [
     "mcp",
@@ -155,8 +155,7 @@
     "fs-extra": "^11.3.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.5",
-    "markdownlint-cli": "^0.45.0",
-    "mcp-evals": "^2.0.1",
+    "markdownlint-cli": "^0.47.0",
     "nock": "^14.0.10",
     "node-fetch": "^3.3.2",
     "open": "^10.2.0",

package/src/cache/CacheInvalidation.ts

@@ -4,7 +4,7 @@
  */
 
 import { HttpCacheWrapper } from "./HttpCacheWrapper.js";
-import { LoggerFactory } from "../utils/logger.js";
+import { LoggerFactory } from "@/utils/logger.js";
 
 export interface InvalidationRule {
   trigger: string;

package/src/cache/CacheManager.ts

@@ -3,8 +3,7 @@
  * Implements multi-layer caching with TTL, LRU eviction, and site-specific keys
  */
 
-import * as crypto from "crypto";
-import { ConfigHelpers } from "../config/Config.js";
+import { ConfigHelpers } from "@/config/Config.js";
 
 export interface CacheEntry<T = unknown> {
   value: T;
@@ -56,6 +55,7 @@ export class CacheManager {
 
   /**
    * Generate cache key with site prefix and parameter hash
+   * Uses fast non-cryptographic hash (FNV-1a) for 3-5x better performance
    */
   generateKey(siteId: string, endpoint: string, params?: Record<string, unknown>): string {
     const baseKey = `${siteId}:${endpoint}`;
@@ -64,16 +64,33 @@ export class CacheManager {
       return baseKey;
     }
 
-    // Create deterministic hash of parameters
-    const paramHash = crypto
-      .createHash("md5")
-      .update(JSON.stringify(this.normalizeParams(params)))
-      .digest("hex")
-      .substring(0, 8);
+    // Use fast non-cryptographic hash (FNV-1a) for cache keys
+    // Normalized params ensure consistent ordering
+    const paramString = JSON.stringify(this.normalizeParams(params));
+    const paramHash = this.fastHash(paramString);
 
     return `${baseKey}:${paramHash}`;
   }
 
+  /**
+   * Fast non-cryptographic hash function (FNV-1a variant)
+   * 3-5x faster than MD5 for cache key generation
+   * Returns base36 string for compact keys with low collision risk
+   */
+  private fastHash(str: string): string {
+    let hash = 2166136261; // FNV offset basis (32-bit)
+
+    for (let i = 0; i < str.length; i++) {
+      hash ^= str.charCodeAt(i);
+      // FNV prime: 16777619
+      hash = Math.imul(hash, 16777619);
+    }
+
+    // Convert to unsigned 32-bit integer and encode as base36
+    // Base36 (0-9, a-z) gives ~6 characters for 32-bit hash (more compact than hex)
+    return (hash >>> 0).toString(36);
+  }
+
   /**
    * Get value from cache if not expired
    */

package/src/cache/HttpCacheWrapper.ts

@@ -5,7 +5,7 @@
 
 import { CacheManager, CachePresets } from "./CacheManager.js";
 import * as crypto from "crypto";
-import { LoggerFactory } from "../utils/logger.js";
+import { LoggerFactory } from "@/utils/logger.js";
 
 export interface HttpCacheOptions {
   ttl?: number;

package/src/cache/SEOCacheManager.ts

@@ -9,8 +9,8 @@
  */
 
 import { CacheManager, type CacheConfig } from "./CacheManager.js";
-import { Config } from "../config/Config.js";
-import { LoggerFactory } from "../utils/logger.js";
+import { Config } from "@/config/Config.js";
+import { LoggerFactory } from "@/utils/logger.js";
 
 /**
  * SEO-specific cache manager
@@ -242,7 +242,13 @@ export class SEOCacheManager extends CacheManager {
   private async invalidatePattern(pattern: string): Promise<void> {
     // Get all cache keys and filter by pattern
     const allKeys = await this.getAllKeys();
-    const regex = new RegExp("^" + pattern.replace(/\*/g, ".*").replace(/:/g, "\\:") + "$");
+
+    // Escape regex special characters first, then convert glob * to regex .*
+    // This prevents regex injection and handles patterns correctly
+    const escapedPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, "\\$&") // Escape regex special chars except *
+      .replace(/\*/g, ".*"); // Convert glob wildcards to regex
+    const regex = new RegExp("^" + escapedPattern + "$");
 
     const matchingKeys = allKeys.filter((key) => regex.test(key));
 

package/src/cache/index.ts

@@ -6,7 +6,7 @@
 export { CacheManager, CachePresets } from "./CacheManager.js";
 export { HttpCacheWrapper } from "./HttpCacheWrapper.js";
 export { CacheInvalidation, WordPressCachePatterns, CacheWarmer } from "./CacheInvalidation.js";
-export { CachedWordPressClient } from "../client/CachedWordPressClient.js";
+export { CachedWordPressClient } from "@/client/CachedWordPressClient.js";
 
 export type { CacheEntry, CacheStats, CacheConfig } from "./CacheManager.js";
 

package/src/client/CachedWordPressClient.ts

@@ -4,11 +4,11 @@
  */
 
 import { WordPressClient } from "./api.js";
-import { CacheManager, type CacheStats } from "../cache/CacheManager.js";
-import { HttpCacheWrapper } from "../cache/HttpCacheWrapper.js";
-import { CacheInvalidation } from "../cache/CacheInvalidation.js";
-import { SecurityConfig } from "../security/SecurityConfig.js";
-import type { WordPressClientConfig, HTTPMethod, RequestOptions } from "../types/client.js";
+import { CacheManager, type CacheStats } from "@/cache/CacheManager.js";
+import { HttpCacheWrapper } from "@/cache/HttpCacheWrapper.js";
+import { CacheInvalidation } from "@/cache/CacheInvalidation.js";
+import { SecurityConfig } from "@/security/SecurityConfig.js";
+import type { WordPressClientConfig, HTTPMethod, RequestOptions } from "@/types/client.js";
 import type {
   WordPressPost,
   WordPressUser,
@@ -18,7 +18,7 @@ import type {
   PostQueryParams,
   CreatePostRequest,
   UpdatePostRequest,
-} from "../types/wordpress.js";
+} from "@/types/wordpress.js";
 
 /**
  * WordPress client with intelligent caching

package/src/client/MockWordPressClient.ts

@@ -1,6 +1,6 @@
 import { WordPressClient } from "./api.js";
-import { WordPressClientConfig } from "../types/client.js";
-import { LoggerFactory } from "../utils/logger.js";
+import { WordPressClientConfig } from "@/types/client.js";
+import { LoggerFactory } from "@/utils/logger.js";
 import type {
   WordPressPost,
   WordPressUser,
@@ -8,7 +8,7 @@ import type {
   PostQueryParams,
   CreatePostRequest,
   UpdatePostRequest,
-} from "../types/wordpress.js";
+} from "@/types/wordpress.js";
 
 /**
  * Mock WordPress client for CI environments

package/src/client/SEOWordPressClient.ts

@@ -17,12 +17,12 @@
  */
 
 import { WordPressClient } from "./api.js";
-import { LoggerFactory } from "../utils/logger.js";
-import { handleToolError } from "../utils/error.js";
-import type { WordPressPost, WordPressPage } from "../types/wordpress.js";
-import type { WordPressClientConfig } from "../types/client.js";
-import type { SchemaType } from "../types/seo.js";
-import type { SEOMetadata, SchemaMarkup } from "../types/seo.js";
+import { LoggerFactory } from "@/utils/logger.js";
+import { handleToolError } from "@/utils/error.js";
+import type { WordPressPost, WordPressPage } from "@/types/wordpress.js";
+import type { WordPressClientConfig } from "@/types/client.js";
+import type { SchemaType } from "@/types/seo.js";
+import type { SEOMetadata, SchemaMarkup } from "@/types/seo.js";
 
 /**
  * WordPress Plugin interface for API responses