mcp-wordpress 2.2.0 → 2.4.0

package/src/security/index.ts

@@ -0,0 +1,249 @@
+/**
+ * Security System Index
+ * Central export for all security components
+ */
+
+// Core Security Components
+export { SecurityConfig, SecurityUtils, createSecureError, getEnvironmentSecurity } from "./SecurityConfig";
+import { SecurityValidationError } from "./InputValidator";
+export {
+  InputSanitizer,
+  SecuritySchemas,
+  SecurityLimiter,
+  SecurityValidationError,
+  validateSecurity,
+  ToolSchemas,
+} from "./InputValidator";
+
+// AI-Powered Security Scanner
+import { AISecurityScanner } from "./AISecurityScanner";
+export { AISecurityScanner } from "./AISecurityScanner";
+
+// Automated Remediation System
+import { AutomatedRemediation, RemediationResult as _RemediationResult } from "./AutomatedRemediation";
+export { AutomatedRemediation, RemediationResult } from "./AutomatedRemediation";
+
+// Security Code Reviewer
+import { SecurityReviewer, CodeReviewResult as _CodeReviewResult } from "./SecurityReviewer";
+export { SecurityReviewer, CodeReviewResult } from "./SecurityReviewer";
+
+// Security Configuration Manager
+import { SecurityConfigManager } from "./SecurityConfigManager";
+export { SecurityConfigManager } from "./SecurityConfigManager";
+
+// Security Monitoring and Alerting
+import { SecurityMonitor, SecurityEvent as _SecurityEvent } from "./SecurityMonitoring";
+export { SecurityMonitor, SecurityEvent } from "./SecurityMonitoring";
+
+// CI/CD Pipeline Integration
+import { SecurityCIPipeline, PipelineSecurityReport as _PipelineSecurityReport } from "./SecurityCIPipeline";
+export { SecurityCIPipeline, PipelineSecurityReport } from "./SecurityCIPipeline";
+
+// Type definitions for external use
+export interface SecurityScanOptions {
+  targets?: string[];
+  depth?: "shallow" | "deep" | "comprehensive";
+  includeFileSystem?: boolean;
+  includeRuntime?: boolean;
+}
+
+export interface SecurityReviewOptions {
+  rules?: string[];
+  excludeRules?: string[];
+  aiAnalysis?: boolean;
+  recursive?: boolean;
+}
+
+export interface SecurityGateOptions {
+  skipNonBlocking?: boolean;
+  continueOnFailure?: boolean;
+  dryRun?: boolean;
+}
+
+/**
+ * Security System Manager
+ * Orchestrates all security components
+ */
+export class SecuritySystem {
+  private scanner: AISecurityScanner;
+  private remediation: AutomatedRemediation;
+  private reviewer: SecurityReviewer;
+  private configManager: SecurityConfigManager;
+  private monitor: SecurityMonitor;
+  private pipeline: SecurityCIPipeline;
+  private initialized = false;
+
+  constructor() {
+    this.scanner = new AISecurityScanner();
+    this.remediation = new AutomatedRemediation();
+    this.reviewer = new SecurityReviewer();
+    this.configManager = new SecurityConfigManager();
+    this.monitor = new SecurityMonitor();
+    this.pipeline = new SecurityCIPipeline();
+  }
+
+  /**
+   * Initialize the security system
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      console.log("[Security System] Already initialized");
+      return;
+    }
+
+    console.log("[Security System] Initializing comprehensive security system...");
+
+    try {
+      // Initialize all components
+      await this.configManager.initialize();
+      await this.pipeline.initialize();
+
+      // Start monitoring
+      this.monitor.start();
+
+      this.initialized = true;
+      console.log("[Security System] Security system initialized successfully");
+    } catch (error) {
+      console.error("[Security System] Initialization failed:", error);
+      throw new SecurityValidationError("Security system initialization failed", [{ message: String(error) }]);
+    }
+  }
+
+  /**
+   * Perform comprehensive security scan
+   */
+  async scan(options?: SecurityScanOptions) {
+    this.ensureInitialized();
+    return await this.scanner.performScan(options);
+  }
+
+  /**
+   * Perform security code review
+   */
+  async review(filePath: string, options?: SecurityReviewOptions): Promise<_CodeReviewResult> {
+    this.ensureInitialized();
+    return await this.reviewer.reviewFile(filePath, options);
+  }
+
+  /**
+   * Create and execute remediation plan
+   */
+  async remediate(scanResult: any, dryRun = false): Promise<_RemediationResult[]> {
+    this.ensureInitialized();
+    const plan = await this.remediation.createRemediationPlan(scanResult);
+    return await this.remediation.executeRemediationPlan(plan, { dryRun });
+  }
+
+  /**
+   * Execute security gates for CI/CD
+   */
+  async executeGates(stage: string, context: any, options?: SecurityGateOptions): Promise<_PipelineSecurityReport> {
+    this.ensureInitialized();
+    return await this.pipeline.executeSecurityGates(stage as any, context, options);
+  }
+
+  /**
+   * Log security event
+   */
+  async logEvent(eventData: any): Promise<_SecurityEvent> {
+    this.ensureInitialized();
+    return await this.monitor.logSecurityEvent(eventData);
+  }
+
+  /**
+   * Get security status
+   */
+  getStatus() {
+    this.ensureInitialized();
+    return {
+      system: this.initialized,
+      monitoring: this.monitor.getStatus(),
+      scanner: this.scanner.getLatestScan(),
+      pipeline: this.pipeline.getStatistics(),
+    };
+  }
+
+  /**
+   * Shutdown security system
+   */
+  shutdown(): void {
+    if (!this.initialized) {
+      return;
+    }
+
+    console.log("[Security System] Shutting down security system...");
+
+    this.monitor.stop();
+    this.initialized = false;
+
+    console.log("[Security System] Security system shutdown complete");
+  }
+
+  /**
+   * Ensure system is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new SecurityValidationError("Security system not initialized", [{ message: "Call initialize() first" }]);
+    }
+  }
+
+  /**
+   * Get individual components for advanced usage
+   */
+  getComponents() {
+    return {
+      scanner: this.scanner,
+      remediation: this.remediation,
+      reviewer: this.reviewer,
+      configManager: this.configManager,
+      monitor: this.monitor,
+      pipeline: this.pipeline,
+    };
+  }
+}
+
+/**
+ * Default security system instance
+ */
+export const securitySystem = new SecuritySystem();
+
+/**
+ * Convenience functions for common operations
+ */
+export const security = {
+  /**
+   * Quick security scan
+   */
+  scan: (options?: SecurityScanOptions) => securitySystem.scan(options),
+
+  /**
+   * Quick security review
+   */
+  review: (filePath: string, options?: SecurityReviewOptions) => securitySystem.review(filePath, options),
+
+  /**
+   * Quick remediation
+   */
+  remediate: (scanResult: any, dryRun = true) => securitySystem.remediate(scanResult, dryRun),
+
+  /**
+   * Log security event
+   */
+  logEvent: (eventData: any) => securitySystem.logEvent(eventData),
+
+  /**
+   * Get security status
+   */
+  status: () => securitySystem.getStatus(),
+
+  /**
+   * Initialize security system
+   */
+  init: () => securitySystem.initialize(),
+
+  /**
+   * Shutdown security system
+   */
+  shutdown: () => securitySystem.shutdown(),
+};

package/src/tools/media.ts

@@ -8,13 +8,52 @@ import {
 import { getErrorMessage } from "../utils/error.js";
 
 /**
- * Provides tools for managing media on a WordPress site.
- * This class encapsulates tool definitions and their corresponding handlers.
+ * Comprehensive media management tools for WordPress sites.
+ * 
+ * This class provides complete media library functionality including:
+ * - Listing media items with advanced filtering and search
+ * - Uploading new media files with validation and optimization
+ * - Retrieving detailed media information and metadata
+ * - Updating media properties like title, description, and alt text
+ * - Deleting media items with safety checks
+ * 
+ * Supports all WordPress media types including images, videos, audio files,
+ * and documents with proper MIME type validation and security checks.
+ * 
+ * @example
+ * ```typescript
+ * const mediaTools = new MediaTools();
+ * const tools = mediaTools.getTools();
+ * 
+ * // Upload an image
+ * const client = new WordPressClient(config);
+ * const result = await mediaTools.handleUploadMedia(client, {
+ *   file_path: "/path/to/image.jpg",
+ *   title: "My Image",
+ *   alt_text: "Description of the image"
+ * });
+ * ```
+ * 
+ * @since 1.0.0
+ * @author MCP WordPress Team
  */
 export class MediaTools {
   /**
-   * Retrieves the list of media management tools.
-   * @returns An array of MCPTool definitions.
+   * Retrieves the complete list of media management tools available for MCP.
+   * 
+   * Returns an array of tool definitions for comprehensive media library management.
+   * Each tool includes parameter validation, security checks, and detailed error handling.
+   * 
+   * @returns {Array<MCPTool>} Array of MCPTool definitions for media management
+   * 
+   * @example
+   * ```typescript
+   * const mediaTools = new MediaTools();
+   * const tools = mediaTools.getTools();
+   * console.log(tools.length); // 5 tools: list, get, upload, update, delete
+   * ```
+   * 
+   * @since 1.0.0
    */
   public getTools(): any[] {
     return [

package/src/tools/posts.ts

@@ -6,13 +6,45 @@ import { validateId, validatePaginationParams, validatePostParams } from "../uti
 import { WordPressDataStreamer, StreamingUtils, StreamingResult } from "../utils/streaming.js";
 
 /**
- * Provides tools for managing posts on a WordPress site.
- * This class encapsulates tool definitions and their corresponding handlers.
+ * Provides comprehensive tools for managing WordPress posts.
+ * 
+ * This class encapsulates tool definitions and their corresponding handlers for:
+ * - Listing posts with advanced filtering and search capabilities
+ * - Creating new posts with full metadata support
+ * - Updating existing posts with validation
+ * - Deleting posts with trash/permanent options
+ * - Retrieving individual posts with detailed information
+ * - Managing post revisions and history
+ * 
+ * @example
+ * ```typescript
+ * const postTools = new PostTools();
+ * const tools = postTools.getTools();
+ * 
+ * // Use with a WordPress client
+ * const client = new WordPressClient(config);
+ * const result = await postTools.handleListPosts(client, { per_page: 10 });
+ * ```
+ * 
+ * @since 1.0.0
+ * @author MCP WordPress Team
  */
 export class PostTools {
   /**
-   * Retrieves the list of post management tools.
-   * @returns An array of MCPTool definitions.
+   * Retrieves the complete list of post management tools available for MCP.
+   * 
+   * Returns an array of tool definitions that can be registered with an MCP server.
+   * Each tool includes comprehensive parameter validation, error handling, and
+   * detailed documentation with usage examples.
+   * 
+   * @returns {Array<MCPTool>} An array of MCPTool definitions for post management
+   * 
+   * @example
+   * ```typescript
+   * const postTools = new PostTools();
+   * const tools = postTools.getTools();
+   * console.log(tools.length); // 6 tools: list, get, create, update, delete, revisions
+   * ```
    */
   public getTools(): any[] {
     return [
@@ -184,6 +216,42 @@ export class PostTools {
     ];
   }
 
+  /**
+   * Handles listing posts from a WordPress site with comprehensive filtering options.
+   * 
+   * This method provides advanced search capabilities, status filtering, pagination,
+   * and category/tag filtering. Results include enhanced metadata and author information.
+   * For large result sets (>50 posts), it automatically uses streaming for better performance.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {PostQueryParams} params - Query parameters for filtering and pagination
+   * @param {number} [params.per_page=10] - Number of posts to return per page (max 100)
+   * @param {string} [params.search] - Search term to filter posts by title/content
+   * @param {string|string[]} [params.status] - Post status filter (publish, draft, etc.)
+   * @param {number[]} [params.categories] - Array of category IDs to filter by
+   * @param {number[]} [params.tags] - Array of tag IDs to filter by
+   * @param {number} [params.page=1] - Page number for pagination
+   * 
+   * @returns {Promise<string>} Formatted list of posts with metadata and context
+   * 
+   * @throws {EnhancedError} When validation fails or API request encounters an error
+   * 
+   * @example
+   * ```typescript
+   * // Basic listing
+   * const result = await handleListPosts(client, {});
+   * 
+   * // Advanced filtering
+   * const filtered = await handleListPosts(client, {
+   *   search: "WordPress tips",
+   *   status: "publish",
+   *   categories: [1, 2],
+   *   per_page: 20
+   * });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleListPosts(client: WordPressClient, params: PostQueryParams): Promise<any> {
     try {
       // Enhanced input validation and sanitization
@@ -381,6 +449,28 @@ export class PostTools {
     }
   }
 
+  /**
+   * Retrieves a single WordPress post by ID with complete details and metadata.
+   * 
+   * This method fetches a specific post and returns comprehensive information including
+   * content, metadata, author details, categories, tags, and publication status.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {Object} params - Parameters for post retrieval
+   * @param {number} params.id - The unique ID of the post to retrieve
+   * 
+   * @returns {Promise<string>} Detailed post information formatted for display
+   * 
+   * @throws {EnhancedError} When post ID is invalid or post is not found
+   * 
+   * @example
+   * ```typescript
+   * // Get a specific post
+   * const post = await handleGetPost(client, { id: 123 });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleGetPost(client: WordPressClient, params: { id: number }): Promise<any> {
     try {
       // Input validation
@@ -495,6 +585,47 @@ export class PostTools {
     }
   }
 
+  /**
+   * Creates a new WordPress post with comprehensive validation and metadata support.
+   * 
+   * This method handles the creation of new posts with full support for content,
+   * metadata, categories, tags, and publishing options. Includes automatic validation
+   * and sanitization of all input parameters.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {CreatePostRequest} params - Post creation parameters
+   * @param {string} params.title - The post title
+   * @param {string} params.content - The post content in HTML format
+   * @param {string} [params.status="draft"] - Post status (publish, draft, pending, private)
+   * @param {string} [params.excerpt] - Post excerpt/summary
+   * @param {number[]} [params.categories] - Array of category IDs to assign
+   * @param {number[]} [params.tags] - Array of tag IDs to assign
+   * 
+   * @returns {Promise<string>} Success message with the new post ID and details
+   * 
+   * @throws {EnhancedError} When validation fails or post creation encounters an error
+   * 
+   * @example
+   * ```typescript
+   * // Create a basic post
+   * const result = await handleCreatePost(client, {
+   *   title: "My New Post",
+   *   content: "<p>This is the post content.</p>",
+   *   status: "publish"
+   * });
+   * 
+   * // Create post with categories and tags
+   * const detailed = await handleCreatePost(client, {
+   *   title: "WordPress Tips",
+   *   content: "<p>Detailed WordPress tips...</p>",
+   *   categories: [1, 2],
+   *   tags: [5, 6],
+   *   excerpt: "Learn essential WordPress tips"
+   * });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleCreatePost(client: WordPressClient, params: CreatePostRequest): Promise<any> {
     try {
       // Enhanced input validation using new validation utilities
@@ -522,6 +653,45 @@ export class PostTools {
     }
   }
 
+  /**
+   * Updates an existing WordPress post with validation and detailed confirmation.
+   * 
+   * This method allows updating any aspect of a post including title, content, status,
+   * categories, and tags. Only provided fields are updated, leaving others unchanged.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {UpdatePostRequest & {id: number}} params - Update parameters
+   * @param {number} params.id - The ID of the post to update
+   * @param {string} [params.title] - New post title
+   * @param {string} [params.content] - New post content in HTML format
+   * @param {string} [params.status] - New post status (publish, draft, pending, private)
+   * @param {string} [params.excerpt] - New post excerpt
+   * @param {number[]} [params.categories] - New category IDs to assign
+   * @param {number[]} [params.tags] - New tag IDs to assign
+   * 
+   * @returns {Promise<string>} Success message confirming the update
+   * 
+   * @throws {EnhancedError} When post ID is invalid or update fails
+   * 
+   * @example
+   * ```typescript
+   * // Update post title and status
+   * const result = await handleUpdatePost(client, {
+   *   id: 123,
+   *   title: "Updated Post Title",
+   *   status: "publish"
+   * });
+   * 
+   * // Update content and categories
+   * const updated = await handleUpdatePost(client, {
+   *   id: 123,
+   *   content: "<p>New content here...</p>",
+   *   categories: [1, 3, 5]
+   * });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleUpdatePost(client: WordPressClient, params: UpdatePostRequest & { id: number }): Promise<any> {
     try {
       const post = await client.updatePost(params);
@@ -531,6 +701,35 @@ export class PostTools {
     }
   }
 
+  /**
+   * Deletes a WordPress post with options for trash or permanent deletion.
+   * 
+   * This method provides safe deletion with trash option (default) or permanent
+   * deletion when force is specified. Includes confirmation of the deletion action.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {Object} params - Deletion parameters
+   * @param {number} params.id - The ID of the post to delete
+   * @param {boolean} [params.force=false] - Whether to permanently delete (true) or move to trash (false)
+   * 
+   * @returns {Promise<string>} Confirmation message of the deletion action
+   * 
+   * @throws {EnhancedError} When post ID is invalid or deletion fails
+   * 
+   * @example
+   * ```typescript
+   * // Move post to trash (safe deletion)
+   * const result = await handleDeletePost(client, { id: 123 });
+   * 
+   * // Permanently delete post (cannot be undone)
+   * const permanent = await handleDeletePost(client, { 
+   *   id: 123, 
+   *   force: true 
+   * });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleDeletePost(client: WordPressClient, params: { id: number; force?: boolean }): Promise<any> {
     try {
       await client.deletePost(params.id, params.force);
@@ -541,6 +740,28 @@ export class PostTools {
     }
   }
 
+  /**
+   * Retrieves revision history for a specific WordPress post.
+   * 
+   * This method fetches all available revisions for a post, providing a complete
+   * history of changes including dates, authors, and modification details.
+   * 
+   * @param {WordPressClient} client - The WordPress client instance for API communication
+   * @param {Object} params - Parameters for revision retrieval
+   * @param {number} params.id - The ID of the post to get revisions for
+   * 
+   * @returns {Promise<string>} Formatted list of post revisions with details
+   * 
+   * @throws {EnhancedError} When post ID is invalid or revisions cannot be retrieved
+   * 
+   * @example
+   * ```typescript
+   * // Get all revisions for a post
+   * const revisions = await handleGetPostRevisions(client, { id: 123 });
+   * ```
+   * 
+   * @since 1.0.0
+   */
   public async handleGetPostRevisions(client: WordPressClient, params: { id: number }): Promise<any> {
     try {
       const revisions = await client.getPostRevisions(params.id);