mcp-wordpress 2.4.2 → 2.5.1

package/src/tools/posts/PostToolDefinitions.ts

@@ -0,0 +1,250 @@
+/**
+ * WordPress Posts Tool Definitions
+ *
+ * Defines all MCP tool schemas for WordPress post management.
+ * This module separates tool definitions from their implementations
+ * for better maintainability and testing.
+ */
+
+import type { MCPTool } from "../../types/mcp.js";
+
+/**
+ * Tool definition for listing WordPress posts
+ */
+export const listPostsTool: MCPTool = {
+  name: "wp_list_posts",
+  description:
+    "Lists posts from a WordPress site with comprehensive filtering options. Supports search, status filtering, and category/tag filtering with enhanced metadata display.\n\n" +
+    "**Usage Examples:**\n" +
+    "• Basic listing: `wp_list_posts`\n" +
+    '• Search posts: `wp_list_posts --search="AI trends"`\n' +
+    '• Filter by status: `wp_list_posts --status="draft"`\n' +
+    "• Category filtering: `wp_list_posts --categories=[1,2,3]`\n" +
+    "• Paginated results: `wp_list_posts --per_page=20 --page=2`\n" +
+    '• Combined filters: `wp_list_posts --search="WordPress" --status="publish" --per_page=10`',
+  inputSchema: {
+    type: "object",
+    properties: {
+      per_page: {
+        type: "number",
+        description: "Number of items to return per page (max 100).",
+      },
+      search: {
+        type: "string",
+        description: "Limit results to those matching a search term.",
+      },
+      status: {
+        type: "string",
+        description: "Filter by post status.",
+        enum: ["publish", "future", "draft", "pending", "private"],
+      },
+      categories: {
+        type: "array",
+        items: { type: "number" },
+        description: "Limit results to posts in specific category IDs.",
+      },
+      tags: {
+        type: "array",
+        items: { type: "number" },
+        description: "Limit results to posts with specific tag IDs.",
+      },
+    },
+  },
+};
+
+/**
+ * Tool definition for retrieving a single WordPress post
+ */
+export const getPostTool: MCPTool = {
+  name: "wp_get_post",
+  description:
+    "Retrieves detailed information about a single post including metadata, content statistics, and management links.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "number",
+        description: "The unique identifier for the post.",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+/**
+ * Tool definition for creating a new WordPress post
+ */
+export const createPostTool: MCPTool = {
+  name: "wp_create_post",
+  description:
+    "Creates a new WordPress post with comprehensive validation and detailed success feedback including management links.\n\n" +
+    "**Usage Examples:**\n" +
+    '• Simple post: `wp_create_post --title="My New Post" --content="<p>Hello World!</p>"`\n' +
+    '• Draft post: `wp_create_post --title="Draft Post" --status="draft"`\n' +
+    '• Categorized post: `wp_create_post --title="Tech News" --categories=[1,5] --tags=[10,20]`\n' +
+    '• Post with featured image: `wp_create_post --title="My Post" --content="<p>Content</p>" --featured_media=42`\n' +
+    '• Remove featured image: `wp_create_post --title="My Post" --featured_media=0`\n' +
+    '• Scheduled post: `wp_create_post --title="Future Post" --status="future" --date="2024-12-25T10:00:00"`\n' +
+    '• Complete post: `wp_create_post --title="Complete Post" --content="<p>Content</p>" --excerpt="Summary" --status="publish"`',
+  inputSchema: {
+    type: "object",
+    properties: {
+      title: {
+        type: "string",
+        description: "The title for the post.",
+      },
+      content: {
+        type: "string",
+        description: "The content for the post, in HTML format.",
+      },
+      status: {
+        type: "string",
+        description: "The publishing status for the post.",
+        enum: ["publish", "draft", "pending", "private"],
+      },
+      excerpt: {
+        type: "string",
+        description: "The excerpt for the post.",
+      },
+      categories: {
+        type: "array",
+        items: { type: "number" },
+        description: "An array of category IDs to assign to the post.",
+      },
+      tags: {
+        type: "array",
+        items: { type: "number" },
+        description: "An array of tag IDs to assign to the post.",
+      },
+      featured_media: {
+        type: "number",
+        description: "The ID of the featured media (image). Use 0 to remove featured media.",
+      },
+      date: {
+        type: "string",
+        description: "The date the post was published, in the site's timezone (ISO 8601 format).",
+      },
+    },
+    required: ["title"],
+  },
+};
+
+/**
+ * Tool definition for updating an existing WordPress post
+ */
+export const updatePostTool: MCPTool = {
+  name: "wp_update_post",
+  description:
+    "Updates an existing WordPress post with comprehensive validation and change tracking. All parameters except ID are optional - only provided fields will be updated.\n\n" +
+    "**Usage Examples:**\n" +
+    '• Update title: `wp_update_post --id=123 --title="New Title"`\n' +
+    '• Update content: `wp_update_post --id=123 --content="<p>Updated content</p>"`\n' +
+    '• Change status: `wp_update_post --id=123 --status="publish"`\n' +
+    "• Update categories: `wp_update_post --id=123 --categories=[1,5,10]`\n" +
+    "• Set featured image: `wp_update_post --id=123 --featured_media=42`\n" +
+    "• Remove featured image: `wp_update_post --id=123 --featured_media=0`\n" +
+    '• Multiple updates: `wp_update_post --id=123 --title="New Title" --status="publish" --categories=[1,2]`',
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "number",
+        description: "The ID of the post to update.",
+      },
+      title: {
+        type: "string",
+        description: "The new title for the post.",
+      },
+      content: {
+        type: "string",
+        description: "The new content for the post, in HTML format.",
+      },
+      status: {
+        type: "string",
+        description: "The new publishing status for the post.",
+        enum: ["publish", "draft", "pending", "private"],
+      },
+      excerpt: {
+        type: "string",
+        description: "The new excerpt for the post.",
+      },
+      categories: {
+        type: "array",
+        items: { type: "number" },
+        description: "An array of category IDs to assign to the post.",
+      },
+      tags: {
+        type: "array",
+        items: { type: "number" },
+        description: "An array of tag IDs to assign to the post.",
+      },
+      featured_media: {
+        type: "number",
+        description: "The ID of the featured media (image). Use 0 to remove featured media.",
+      },
+      date: {
+        type: "string",
+        description: "The date the post was published, in the site's timezone (ISO 8601 format).",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+/**
+ * Tool definition for deleting a WordPress post
+ */
+export const deletePostTool: MCPTool = {
+  name: "wp_delete_post",
+  description:
+    "Deletes a WordPress post with options for trash or permanent deletion. Includes safety confirmations and detailed feedback on the deletion action.\n\n" +
+    "**Usage Examples:**\n" +
+    "• Trash a post: `wp_delete_post --id=123` (moves to trash)\n" +
+    "• Permanent deletion: `wp_delete_post --id=123 --force=true`\n" +
+    "• Bulk operations: Use multiple calls with different IDs",
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "number",
+        description: "The ID of the post to delete.",
+      },
+      force: {
+        type: "boolean",
+        description: "Whether to bypass trash and force deletion (default: false, moves to trash).",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+/**
+ * Tool definition for retrieving post revisions
+ */
+export const getPostRevisionsTool: MCPTool = {
+  name: "wp_get_post_revisions",
+  description:
+    "Retrieves the revision history for a specific post, including details about changes, dates, and authors for content management and auditing purposes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      id: {
+        type: "number",
+        description: "The ID of the post to get revisions for.",
+      },
+    },
+    required: ["id"],
+  },
+};
+
+/**
+ * Collection of all post tool definitions
+ */
+export const postToolDefinitions = [
+  listPostsTool,
+  getPostTool,
+  createPostTool,
+  updatePostTool,
+  deletePostTool,
+  getPostRevisionsTool,
+];

package/src/tools/posts/index.ts

@@ -0,0 +1,192 @@
+/**
+ * WordPress Posts Tools - Refactored Module
+ *
+ * This module provides comprehensive WordPress post management functionality
+ * through a clean, modular architecture. It combines tool definitions with
+ * their corresponding handlers for complete post management capabilities.
+ *
+ * Features:
+ * - List posts with advanced filtering and search
+ * - Get individual posts with detailed metadata
+ * - Create new posts with validation and feedback
+ * - Update existing posts with change tracking
+ * - Delete posts with trash/permanent options
+ * - Retrieve post revision history
+ *
+ * @example
+ * ```typescript
+ * import { PostTools } from './tools/posts';
+ *
+ * const postTools = new PostTools();
+ * const tools = postTools.getTools();
+ *
+ * // Use with MCP server
+ * server.setRequestHandler(ListToolsRequestSchema, () => ({
+ *   tools: [...tools, ...otherTools]
+ * }));
+ * ```
+ */
+
+import { WordPressClient } from "../../client/api.js";
+import { CreatePostRequest, PostQueryParams, UpdatePostRequest, WordPressPost } from "../../types/wordpress.js";
+import { postToolDefinitions } from "./PostToolDefinitions.js";
+import {
+  handleListPosts,
+  handleGetPost,
+  handleCreatePost,
+  handleUpdatePost,
+  handleDeletePost,
+  handleGetPostRevisions,
+} from "./PostHandlers.js";
+
+/**
+ * Main PostTools class that provides WordPress post management functionality.
+ *
+ * This class serves as the interface between the MCP framework and WordPress
+ * post operations. It combines tool definitions with their corresponding handlers
+ * to provide a complete post management solution.
+ *
+ * The class is designed with a modular architecture:
+ * - Tool definitions are separate from implementations
+ * - Handlers are extracted into focused functions
+ * - Business logic is isolated from framework concerns
+ *
+ * @since 2.0.0 (Refactored from monolithic implementation)
+ */
+export class PostTools {
+  /**
+   * Retrieves all post management tool definitions for MCP registration.
+   *
+   * Returns an array of tool definitions that include:
+   * - wp_list_posts: Advanced post listing with filtering
+   * - wp_get_post: Detailed individual post retrieval
+   * - wp_create_post: New post creation with validation
+   * - wp_update_post: Post updating with change tracking
+   * - wp_delete_post: Post deletion with trash/permanent options
+   * - wp_get_post_revisions: Post revision history
+   *
+   * Each tool includes comprehensive parameter validation, detailed documentation,
+   * and usage examples for optimal developer experience.
+   *
+   * @returns Tool definitions ready for MCP server registration
+   */
+  public getTools(): unknown[] {
+    return postToolDefinitions.map((toolDef) => ({
+      ...toolDef,
+      handler: this.getHandlerForTool(toolDef.name),
+    }));
+  }
+
+  /**
+   * Maps tool names to their corresponding handler methods.
+   *
+   * This method provides the binding between tool definitions and their
+   * implementations, ensuring proper context and error handling.
+   *
+   * @param toolName - The name of the tool to get a handler for
+   * @returns The bound handler method for the specified tool
+   * @private
+   */
+  private getHandlerForTool(toolName: string) {
+    switch (toolName) {
+      case "wp_list_posts":
+        return this.handleListPosts.bind(this);
+      case "wp_get_post":
+        return this.handleGetPost.bind(this);
+      case "wp_create_post":
+        return this.handleCreatePost.bind(this);
+      case "wp_update_post":
+        return this.handleUpdatePost.bind(this);
+      case "wp_delete_post":
+        return this.handleDeletePost.bind(this);
+      case "wp_get_post_revisions":
+        return this.handleGetPostRevisions.bind(this);
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  }
+
+  // Handler Methods - Delegated to Extracted Functions
+
+  /**
+   * Lists WordPress posts with advanced filtering capabilities.
+   *
+   * @param client - WordPress client instance
+   * @param params - Query parameters for filtering posts
+   * @returns Formatted list of posts or error message
+   */
+  public async handleListPosts(client: WordPressClient, params: PostQueryParams): Promise<WordPressPost[] | string> {
+    return handleListPosts(client, params);
+  }
+
+  /**
+   * Retrieves a single WordPress post with detailed information.
+   *
+   * @param client - WordPress client instance
+   * @param params - Parameters including post ID
+   * @returns Detailed post information or error message
+   */
+  public async handleGetPost(client: WordPressClient, params: { id: number }): Promise<WordPressPost | string> {
+    return handleGetPost(client, params);
+  }
+
+  /**
+   * Creates a new WordPress post with validation and feedback.
+   *
+   * @param client - WordPress client instance
+   * @param params - Post creation parameters
+   * @returns Created post information or error message
+   */
+  public async handleCreatePost(client: WordPressClient, params: CreatePostRequest): Promise<WordPressPost | string> {
+    return handleCreatePost(client, params);
+  }
+
+  /**
+   * Updates an existing WordPress post with change tracking.
+   *
+   * @param client - WordPress client instance
+   * @param params - Post update parameters including ID
+   * @returns Updated post information or error message
+   */
+  public async handleUpdatePost(
+    client: WordPressClient,
+    params: UpdatePostRequest & { id: number },
+  ): Promise<WordPressPost | string> {
+    return handleUpdatePost(client, params);
+  }
+
+  /**
+   * Deletes a WordPress post with options for trash or permanent deletion.
+   *
+   * @param client - WordPress client instance
+   * @param params - Deletion parameters including ID and force option
+   * @returns Deletion result or error message
+   */
+  public async handleDeletePost(
+    client: WordPressClient,
+    params: { id: number; force?: boolean },
+  ): Promise<{ deleted: boolean; previous?: WordPressPost } | string> {
+    return handleDeletePost(client, params);
+  }
+
+  /**
+   * Retrieves revision history for a WordPress post.
+   *
+   * @param client - WordPress client instance
+   * @param params - Parameters including post ID
+   * @returns Post revisions or error message
+   */
+  public async handleGetPostRevisions(
+    client: WordPressClient,
+    params: { id: number },
+  ): Promise<WordPressPost[] | string> {
+    return handleGetPostRevisions(client, params);
+  }
+}
+
+// Export everything for easy imports
+export { postToolDefinitions } from "./PostToolDefinitions.js";
+export * from "./PostHandlers.js";
+
+// Default export for backwards compatibility
+export default PostTools;