mcp-wordpress 1.5.2 → 2.0.0

package/src/tools/posts.ts

@@ -1,10 +1,9 @@
 import { WordPressClient } from "../client/api.js";
-import {
-  CreatePostRequest,
-  PostQueryParams,
-  UpdatePostRequest,
-} from "../types/wordpress.js";
+import { CreatePostRequest, PostQueryParams, UpdatePostRequest } from "../types/wordpress.js";
 import { getErrorMessage } from "../utils/error.js";
+import { ErrorHandlers, EnhancedError } from "../utils/enhancedError.js";
+import { validateId, validatePaginationParams, validatePostParams } from "../utils/validation.js";
+import { WordPressDataStreamer, StreamingUtils, StreamingResult } from "../utils/streaming.js";
 
 /**
  * Provides tools for managing posts on a WordPress site.
@@ -19,7 +18,15 @@ export class PostTools {
     return [
       {
         name: "wp_list_posts",
-        description: "Lists posts from a WordPress site, with filters.",
+        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`',
         parameters: [
           {
             name: "per_page",
@@ -54,7 +61,8 @@ export class PostTools {
       },
       {
         name: "wp_get_post",
-        description: "Retrieves a single post by its ID.",
+        description:
+          "Retrieves detailed information about a single post including metadata, content statistics, and management links.",
         parameters: [
           {
             name: "id",
@@ -67,7 +75,14 @@ export class PostTools {
       },
       {
         name: "wp_create_post",
-        description: "Creates a new 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' +
+          '• 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"`',
         parameters: [
           {
             name: "title",
@@ -108,7 +123,7 @@ export class PostTools {
       },
       {
         name: "wp_update_post",
-        description: "Updates an existing post.",
+        description: "Updates an existing WordPress post with validation and detailed confirmation.",
         parameters: [
           {
             name: "id",
@@ -137,7 +152,7 @@ export class PostTools {
       },
       {
         name: "wp_delete_post",
-        description: "Deletes a post.",
+        description: "Deletes a WordPress post with option for permanent deletion or moving to trash.",
         parameters: [
           {
             name: "id",
@@ -148,15 +163,14 @@ export class PostTools {
           {
             name: "force",
             type: "boolean",
-            description:
-              "If true, permanently delete. If false, move to trash. Defaults to false.",
+            description: "If true, permanently delete. If false, move to trash. Defaults to false.",
           },
         ],
         handler: this.handleDeletePost.bind(this),
       },
       {
         name: "wp_get_post_revisions",
-        description: "Retrieves revisions for a specific post.",
+        description: "Retrieves the revision history for a specific post showing author and modification dates.",
         parameters: [
           {
             name: "id",
@@ -170,63 +184,345 @@ export class PostTools {
     ];
   }
 
-  public async handleListPosts(
-    client: WordPressClient,
-    params: PostQueryParams,
-  ): Promise<any> {
+  public async handleListPosts(client: WordPressClient, params: PostQueryParams): Promise<any> {
     try {
-      const posts = await client.getPosts(params);
+      // Enhanced input validation and sanitization
+      const paginationValidated = validatePaginationParams({
+        page: params.page,
+        per_page: params.per_page,
+        offset: params.offset,
+      });
+
+      const sanitizedParams = {
+        ...params,
+        ...paginationValidated,
+      };
+
+      // Validate and sanitize search term
+      if (sanitizedParams.search) {
+        sanitizedParams.search = sanitizedParams.search.trim();
+        if (sanitizedParams.search.length === 0) {
+          delete sanitizedParams.search;
+        }
+      }
+
+      // Validate category and tag IDs if provided
+      if (sanitizedParams.categories) {
+        sanitizedParams.categories = sanitizedParams.categories.map((id) => validateId(id, "category ID"));
+      }
+
+      if (sanitizedParams.tags) {
+        sanitizedParams.tags = sanitizedParams.tags.map((id) => validateId(id, "tag ID"));
+      }
+
+      // Validate status parameter
+      if (sanitizedParams.status) {
+        const validStatuses = ["publish", "future", "draft", "pending", "private"];
+        const statusesToCheck = Array.isArray(sanitizedParams.status)
+          ? sanitizedParams.status
+          : [sanitizedParams.status];
+
+        for (const statusToCheck of statusesToCheck) {
+          if (!validStatuses.includes(statusToCheck)) {
+            throw ErrorHandlers.validationError("status", statusToCheck, "one of: " + validStatuses.join(", "));
+          }
+        }
+      }
+
+      // Performance optimization: set reasonable defaults
+      if (!sanitizedParams.per_page) {
+        sanitizedParams.per_page = 10; // Default to 10 posts for better performance
+      }
+
+      const posts = await client.getPosts(sanitizedParams);
       if (posts.length === 0) {
-        return "No posts found matching the criteria.";
+        const searchInfo = sanitizedParams.search ? ` matching "${sanitizedParams.search}"` : "";
+        const statusInfo = sanitizedParams.status ? ` with status "${sanitizedParams.status}"` : "";
+        return `No posts found${searchInfo}${statusInfo}. Try adjusting your search criteria or check if posts exist.`;
+      }
+
+      // Use streaming for large result sets (>50 posts)
+      if (posts.length > 50) {
+        const streamResults: StreamingResult<any>[] = [];
+
+        for await (const result of WordPressDataStreamer.streamPosts(posts, {
+          includeAuthor: true,
+          includeCategories: true,
+          includeTags: true,
+          batchSize: 20,
+        })) {
+          streamResults.push(result);
+        }
+
+        return StreamingUtils.formatStreamingResponse(streamResults, "posts");
       }
+
+      // Add comprehensive site context information
+      const siteUrl = client.getSiteUrl ? client.getSiteUrl() : "Unknown site";
+      const totalPosts = posts.length;
+      const statusCounts = posts.reduce(
+        (acc, p) => {
+          acc[p.status] = (acc[p.status] || 0) + 1;
+          return acc;
+        },
+        {} as Record<string, number>,
+      );
+
+      // Enhanced metadata
+      const metadata = [
+        `📊 **Posts Summary**: ${totalPosts} total`,
+        `📝 **Status Breakdown**: ${Object.entries(statusCounts)
+          .map(([status, count]) => `${status}: ${count}`)
+          .join(", ")}`,
+        `🌐 **Source**: ${siteUrl}`,
+        `📅 **Retrieved**: ${new Date().toLocaleString()}`,
+        ...(params.search ? [`🔍 **Search Term**: "${params.search}"`] : []),
+        ...(params.categories ? [`📁 **Categories**: ${params.categories.join(", ")}`] : []),
+        ...(params.tags ? [`🏷️ **Tags**: ${params.tags.join(", ")}`] : []),
+      ];
+
+      // Fetch additional metadata for enhanced responses
+      const authorIds = [...new Set(posts.map((p) => p.author).filter(Boolean))];
+      const categoryIds = [...new Set(posts.flatMap((p) => p.categories || []))];
+      const tagIds = [...new Set(posts.flatMap((p) => p.tags || []))];
+
+      // Fetch authors, categories, and tags in parallel for better performance
+      const [authors, categories, tags] = await Promise.all([
+        authorIds.length > 0
+          ? Promise.all(
+              authorIds.map(async (id) => {
+                try {
+                  const user = await client.getUser(id);
+                  return { id, name: user.name || user.username || `User ${id}` };
+                } catch {
+                  return { id, name: `User ${id}` };
+                }
+              }),
+            )
+          : [],
+        categoryIds.length > 0
+          ? Promise.all(
+              categoryIds.map(async (id) => {
+                try {
+                  const category = await client.getCategory(id);
+                  return { id, name: category.name || `Category ${id}` };
+                } catch {
+                  return { id, name: `Category ${id}` };
+                }
+              }),
+            )
+          : [],
+        tagIds.length > 0
+          ? Promise.all(
+              tagIds.map(async (id) => {
+                try {
+                  const tag = await client.getTag(id);
+                  return { id, name: tag.name || `Tag ${id}` };
+                } catch {
+                  return { id, name: `Tag ${id}` };
+                }
+              }),
+            )
+          : [],
+      ]);
+
+      // Create lookup maps for performance
+      const authorMap = new Map(authors.map((a) => [a.id, a.name]));
+      const categoryMap = new Map(categories.map((c) => [c.id, c.name]));
+      const tagMap = new Map(tags.map((t) => [t.id, t.name]));
+
       const content =
-        `Found ${posts.length} posts:\n\n` +
+        metadata.join("\n") +
+        "\n\n" +
         posts
-          .map(
-            (p) =>
-              `- ID ${p.id}: **${p.title.rendered}** (${p.status})\n  Link: ${p.link}`,
-          )
-          .join("\n");
-      return content;
+          .map((p) => {
+            const date = new Date(p.date);
+            const formattedDate = date.toLocaleDateString("en-US", {
+              year: "numeric",
+              month: "short",
+              day: "numeric",
+            });
+            const excerpt = p.excerpt?.rendered
+              ? p.excerpt.rendered.replace(/<[^>]*>/g, "").substring(0, 80) + "..."
+              : "";
+
+            // Enhanced metadata
+            const authorName = authorMap.get(p.author) || `User ${p.author}`;
+            const postCategories = (p.categories || []).map((id) => categoryMap.get(id) || `Category ${id}`);
+            const postTags = (p.tags || []).map((id) => tagMap.get(id) || `Tag ${id}`);
+
+            let postInfo = `- ID ${p.id}: **${p.title.rendered}** (${p.status})\n`;
+            postInfo += `  👤 Author: ${authorName}\n`;
+            postInfo += `  📅 Published: ${formattedDate}\n`;
+            if (postCategories.length > 0) {
+              postInfo += `  📁 Categories: ${postCategories.join(", ")}\n`;
+            }
+            if (postTags.length > 0) {
+              postInfo += `  🏷️ Tags: ${postTags.join(", ")}\n`;
+            }
+            if (excerpt) {
+              postInfo += `  📝 Excerpt: ${excerpt}\n`;
+            }
+            postInfo += `  🔗 Link: ${p.link}`;
+
+            return postInfo;
+          })
+          .join("\n\n");
+
+      // Add pagination guidance for large result sets
+      let finalContent = content;
+      if (posts.length >= (sanitizedParams.per_page || 10)) {
+        finalContent += `\n\n📄 **Pagination Tip**: Use \`per_page\` parameter to control results (max 100). Current: ${sanitizedParams.per_page || 10}`;
+      }
+
+      return finalContent;
     } catch (error) {
       throw new Error(`Failed to list posts: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleGetPost(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleGetPost(client: WordPressClient, params: { id: number }): Promise<any> {
     try {
+      // Input validation
+      if (!params.id || typeof params.id !== "number" || params.id <= 0) {
+        throw ErrorHandlers.validationError("id", params.id, "positive integer");
+      }
+
       const post = await client.getPost(params.id);
-      const content =
-        `**Post Details (ID: ${post.id})**\n\n` +
-        `- **Title:** ${post.title.rendered}\n` +
-        `- **Status:** ${post.status}\n` +
-        `- **Link:** ${post.link}\n` +
-        `- **Date:** ${new Date(post.date).toLocaleString()}`;
+
+      // Fetch additional metadata for enhanced response
+      const [author, categories, tags] = await Promise.all([
+        post.author
+          ? (async () => {
+              try {
+                const user = await client.getUser(post.author);
+                return user.name || user.username || `User ${post.author}`;
+              } catch {
+                return `User ${post.author}`;
+              }
+            })()
+          : "Unknown",
+        post.categories && post.categories.length > 0
+          ? Promise.all(
+              post.categories.map(async (id) => {
+                try {
+                  const category = await client.getCategory(id);
+                  return category.name || `Category ${id}`;
+                } catch {
+                  return `Category ${id}`;
+                }
+              }),
+            )
+          : [],
+        post.tags && post.tags.length > 0
+          ? Promise.all(
+              post.tags.map(async (id) => {
+                try {
+                  const tag = await client.getTag(id);
+                  return tag.name || `Tag ${id}`;
+                } catch {
+                  return `Tag ${id}`;
+                }
+              }),
+            )
+          : [],
+      ]);
+
+      // Enhanced post details with comprehensive metadata
+      const siteUrl = client.getSiteUrl ? client.getSiteUrl() : "Unknown site";
+      const publishedDate = new Date(post.date);
+      const modifiedDate = new Date(post.modified);
+      const excerpt = post.excerpt?.rendered
+        ? post.excerpt.rendered.replace(/<[^>]*>/g, "").substring(0, 150) + "..."
+        : "No excerpt available";
+      const wordCount = post.content?.rendered ? post.content.rendered.replace(/<[^>]*>/g, "").split(/\s+/).length : 0;
+
+      let content = `**📄 Post Details (ID: ${post.id})**\n\n`;
+      content += `**📋 Basic Information:**\n`;
+      content += `- **Title:** ${post.title.rendered}\n`;
+      content += `- **Status:** ${post.status}\n`;
+      content += `- **Type:** ${post.type}\n`;
+      content += `- **Author:** ${author}\n`;
+      content += `- **Slug:** ${post.slug}\n\n`;
+
+      content += `**📅 Dates:**\n`;
+      content += `- **Published:** ${publishedDate.toLocaleString()}\n`;
+      content += `- **Modified:** ${modifiedDate.toLocaleString()}\n\n`;
+
+      content += `**📊 Content:**\n`;
+      content += `- **Word Count:** ~${wordCount} words\n`;
+      content += `- **Excerpt:** ${excerpt}\n\n`;
+
+      if (categories.length > 0) {
+        content += `**📁 Categories:** ${categories.join(", ")}\n`;
+      }
+      if (tags.length > 0) {
+        content += `**🏷️ Tags:** ${tags.join(", ")}\n`;
+      }
+      if (categories.length > 0 || tags.length > 0) {
+        content += `\n`;
+      }
+
+      content += `**🔗 Links:**\n`;
+      content += `- **Permalink:** ${post.link}\n`;
+      content += `- **Edit Link:** ${post.link.replace(/\/$/, "")}/wp-admin/post.php?post=${post.id}&action=edit\n\n`;
+      content += `**🌐 Source:** ${siteUrl}\n`;
+      content += `**📅 Retrieved:** ${new Date().toLocaleString()}`;
+
       return content;
     } catch (error) {
-      throw new Error(`Failed to get post: ${getErrorMessage(error)}`);
+      // Handle specific error cases
+      const errorMessage = getErrorMessage(error);
+
+      if (errorMessage.includes("Invalid post ID") || errorMessage.includes("not found")) {
+        throw ErrorHandlers.postNotFound(params.id, error);
+      }
+
+      if (errorMessage.includes("401") || errorMessage.includes("Unauthorized")) {
+        throw ErrorHandlers.authenticationFailed(error);
+      }
+
+      if (errorMessage.includes("403") || errorMessage.includes("Forbidden")) {
+        throw ErrorHandlers.permissionDenied("get post", error);
+      }
+
+      if (errorMessage.includes("timeout") || errorMessage.includes("network")) {
+        throw ErrorHandlers.connectionError(error);
+      }
+
+      // Generic error with suggestions
+      throw ErrorHandlers.generic("get post", error);
     }
   }
 
-  public async handleCreatePost(
-    client: WordPressClient,
-    params: CreatePostRequest,
-  ): Promise<any> {
+  public async handleCreatePost(client: WordPressClient, params: CreatePostRequest): Promise<any> {
     try {
-      const post = await client.createPost(params);
-      return `✅ Post created successfully!\n- ID: ${post.id}\n- Title: ${post.title.rendered}\n- Link: ${post.link}`;
+      // Enhanced input validation using new validation utilities
+      const validatedParams = validatePostParams(params);
+
+      const post = await client.createPost(validatedParams);
+      const siteUrl = client.getSiteUrl ? client.getSiteUrl() : "Unknown site";
+
+      return (
+        `✅ **Post Created Successfully!**\n\n` +
+        `**📄 Post Details:**\n` +
+        `- **ID:** ${post.id}\n` +
+        `- **Title:** ${post.title.rendered}\n` +
+        `- **Status:** ${post.status}\n` +
+        `- **Link:** ${post.link}\n` +
+        `- **Edit Link:** ${post.link.replace(/\/$/, "")}/wp-admin/post.php?post=${post.id}&action=edit\n\n` +
+        `**🌐 Site:** ${siteUrl}\n` +
+        `**📅 Created:** ${new Date().toLocaleString()}`
+      );
     } catch (error) {
+      if (error instanceof EnhancedError) {
+        throw error;
+      }
       throw new Error(`Failed to create post: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleUpdatePost(
-    client: WordPressClient,
-    params: UpdatePostRequest & { id: number },
-  ): Promise<any> {
+  public async handleUpdatePost(client: WordPressClient, params: UpdatePostRequest & { id: number }): Promise<any> {
     try {
       const post = await client.updatePost(params);
       return `✅ Post ${post.id} updated successfully.`;
@@ -235,10 +531,7 @@ export class PostTools {
     }
   }
 
-  public async handleDeletePost(
-    client: WordPressClient,
-    params: { id: number; force?: boolean },
-  ): Promise<any> {
+  public async handleDeletePost(client: WordPressClient, params: { id: number; force?: boolean }): Promise<any> {
     try {
       await client.deletePost(params.id, params.force);
       const action = params.force ? "permanently deleted" : "moved to trash";
@@ -248,10 +541,7 @@ export class PostTools {
     }
   }
 
-  public async handleGetPostRevisions(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleGetPostRevisions(client: WordPressClient, params: { id: number }): Promise<any> {
     try {
       const revisions = await client.getPostRevisions(params.id);
       if (revisions.length === 0) {
@@ -260,18 +550,11 @@ export class PostTools {
       const content =
         `Found ${revisions.length} revisions for post ${params.id}:\n\n` +
         revisions
-          .map(
-            (r) =>
-              `- Revision by user ID ${r.author} at ${new Date(
-                r.modified,
-              ).toLocaleString()}`,
-          )
+          .map((r) => `- Revision by user ID ${r.author} at ${new Date(r.modified).toLocaleString()}`)
           .join("\n");
       return content;
     } catch (error) {
-      throw new Error(
-        `Failed to get post revisions: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to get post revisions: ${getErrorMessage(error)}`);
     }
   }
 }