mcp-wordpress 1.5.2 → 2.0.0

package/src/tools/site.ts

@@ -21,8 +21,7 @@ export class SiteTools {
       },
       {
         name: "wp_update_site_settings",
-        description:
-          "Updates one or more general settings for a WordPress site.",
+        description: "Updates one or more general settings for a WordPress site.",
         parameters: [
           {
             name: "title",
@@ -37,15 +36,21 @@ export class SiteTools {
           {
             name: "timezone",
             type: "string",
-            description:
-              "A city in the same timezone, e.g., 'America/New_York'.",
+            description: "A city in the same timezone, e.g., 'America/New_York'.",
           },
         ],
         handler: this.handleUpdateSiteSettings.bind(this),
       },
       {
         name: "wp_search_site",
-        description: "Performs a site-wide search for content.",
+        description:
+          "Performs a site-wide search for content across posts, pages, and media with comprehensive results and metadata.\n\n" +
+          "**Usage Examples:**\n" +
+          '• Search everything: `wp_search_site --term="WordPress"`\n' +
+          '• Search posts only: `wp_search_site --term="tutorial" --type="posts"`\n' +
+          '• Search pages: `wp_search_site --term="about" --type="pages"`\n' +
+          '• Search media: `wp_search_site --term="logo" --type="media"`\n' +
+          '• Find specific content: `wp_search_site --term="contact form"`',
         parameters: [
           {
             name: "term",
@@ -116,35 +121,70 @@ export class SiteTools {
     ];
   }
 
-  public async handleGetSiteSettings(
-    client: WordPressClient,
-    params: any,
-  ): Promise<any> {
+  public async handleGetSiteSettings(client: WordPressClient, params: any): Promise<any> {
     try {
       const settings = await client.getSiteSettings();
-      const content =
-        `**Site Settings for ${settings.url}**\n\n` +
-        `- **Title:** ${settings.title}\n` +
-        `- **Description:** ${settings.description}\n` +
-        `- **Timezone:** ${settings.timezone}\n` +
-        `- **Language:** ${settings.language}`;
+      const siteUrl = client.getSiteUrl();
+
+      // Enhanced site settings with comprehensive details
+      const weekDays = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+      const startOfWeek = settings.start_of_week !== undefined ? weekDays[settings.start_of_week] : "Not set";
+
+      // Get additional site information
+      const currentTime = new Date().toLocaleString("en-US", {
+        timeZone: settings.timezone || "UTC",
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        timeZoneName: "short",
+      });
+
+      let content = `**🌐 Site Settings for ${siteUrl}**\n\n`;
+
+      content += `**📋 Basic Information:**\n`;
+      content += `- **Title:** ${settings.title || "Not set"}\n`;
+      content += `- **Description:** ${settings.description || "Not set"}\n`;
+      content += `- **URL:** ${settings.url || siteUrl}\n`;
+      content += `- **Admin Email:** ${settings.email || "Not set"}\n\n`;
+
+      content += `**🌍 Localization:**\n`;
+      content += `- **Language:** ${settings.language || "English (US)"}\n`;
+      content += `- **Timezone:** ${settings.timezone || "UTC"}\n`;
+      content += `- **Current Time:** ${currentTime}\n\n`;
+
+      content += `**📅 Date & Time Format:**\n`;
+      content += `- **Date Format:** ${settings.date_format || "Not set"}\n`;
+      content += `- **Time Format:** ${settings.time_format || "Not set"}\n`;
+      content += `- **Start of Week:** ${startOfWeek}\n\n`;
+
+      content += `**📝 Content Settings:**\n`;
+      content += `- **Posts per Page:** ${settings.posts_per_page || "Not set"}\n`;
+      content += `- **Default Category:** ${settings.default_category || "Not set"}\n`;
+      content += `- **Default Post Format:** ${settings.default_post_format || "Standard"}\n\n`;
+
+      content += `**💬 Discussion Settings:**\n`;
+      content += `- **Default Comment Status:** ${settings.default_comment_status || "Not set"}\n`;
+      content += `- **Default Ping Status:** ${settings.default_ping_status || "Not set"}\n`;
+      content += `- **Use Smilies:** ${settings.use_smilies ? "Yes" : "No"}\n\n`;
+
+      content += `**📊 Retrieved:** ${new Date().toLocaleString()}`;
+
       return content;
     } catch (error) {
       throw new Error(`Failed to get site settings: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleUpdateSiteSettings(
-    client: WordPressClient,
-    params: any,
-  ): Promise<any> {
+  public async handleUpdateSiteSettings(client: WordPressClient, params: any): Promise<any> {
     try {
       const updatedSettings = await client.updateSiteSettings(params);
       return `✅ Site settings updated successfully. New title: ${updatedSettings.title}`;
     } catch (error) {
-      throw new Error(
-        `Failed to update site settings: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to update site settings: ${getErrorMessage(error)}`);
     }
   }
 
@@ -153,28 +193,20 @@ export class SiteTools {
     params: { term: string; type?: "posts" | "pages" | "media" },
   ): Promise<any> {
     try {
-      const results = await client.search(
-        params.term,
-        params.type ? [params.type] : undefined,
-      );
+      const results = await client.search(params.term, params.type ? [params.type] : undefined);
       if (results.length === 0) {
         return `No results found for "${params.term}".`;
       }
       const content =
         `Found ${results.length} results for "${params.term}":\n\n` +
-        results
-          .map((r) => `- [${r.type}] **${r.title}**\n  Link: ${r.url}`)
-          .join("\n");
+        results.map((r) => `- [${r.type}] **${r.title}**\n  Link: ${r.url}`).join("\n");
       return content;
     } catch (error) {
       throw new Error(`Failed to perform search: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleGetApplicationPasswords(
-    client: WordPressClient,
-    params: { user_id: number },
-  ): Promise<any> {
+  public async handleGetApplicationPasswords(client: WordPressClient, params: { user_id: number }): Promise<any> {
     try {
       const passwords = await client.getApplicationPasswords(params.user_id);
       if (passwords.length === 0) {
@@ -190,9 +222,7 @@ export class SiteTools {
           .join("\n");
       return content;
     } catch (error) {
-      throw new Error(
-        `Failed to get application passwords: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to get application passwords: ${getErrorMessage(error)}`);
     }
   }
 
@@ -201,10 +231,7 @@ export class SiteTools {
     params: { user_id: number; app_name: string },
   ): Promise<any> {
     try {
-      const result = await client.createApplicationPassword(
-        params.user_id,
-        params.app_name,
-      );
+      const result = await client.createApplicationPassword(params.user_id, params.app_name);
       const content =
         "✅ **Application password created successfully!**\n\n" +
         `**Name:** ${result.name}\n` +
@@ -212,9 +239,7 @@ export class SiteTools {
         "**IMPORTANT:** This password is shown only once. Please save it securely.";
       return content;
     } catch (error) {
-      throw new Error(
-        `Failed to create application password: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to create application password: ${getErrorMessage(error)}`);
     }
   }
 
@@ -226,9 +251,7 @@ export class SiteTools {
       await client.deleteApplicationPassword(params.user_id, params.uuid);
       return `✅ Application password with UUID ${params.uuid} has been revoked.`;
     } catch (error) {
-      throw new Error(
-        `Failed to delete application password: ${getErrorMessage(error)}`,
-      );
+      throw new Error(`Failed to delete application password: ${getErrorMessage(error)}`);
     }
   }
 }

package/src/tools/users.ts

@@ -1,10 +1,7 @@
 import { WordPressClient } from "../client/api.js";
-import {
-  CreateUserRequest,
-  UpdateUserRequest,
-  UserQueryParams,
-} from "../types/wordpress.js";
+import { CreateUserRequest, UpdateUserRequest, UserQueryParams } from "../types/wordpress.js";
 import { getErrorMessage } from "../utils/error.js";
+import { WordPressDataStreamer, StreamingUtils, StreamingResult } from "../utils/streaming.js";
 
 /**
  * Provides tools for managing users on a WordPress site.
@@ -19,7 +16,14 @@ export class UserTools {
     return [
       {
         name: "wp_list_users",
-        description: "Lists users from a WordPress site, with filters.",
+        description:
+          "Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.\n\n" +
+          "**Usage Examples:**\n" +
+          "• List all users: `wp_list_users`\n" +
+          '• Search users: `wp_list_users --search="john"`\n' +
+          '• Filter by role: `wp_list_users --roles=["editor","author"]`\n' +
+          '• Find admins: `wp_list_users --roles=["administrator"]`\n' +
+          '• Combined search: `wp_list_users --search="smith" --roles=["subscriber"]`',
         parameters: [
           {
             name: "search",
@@ -50,7 +54,13 @@ export class UserTools {
       },
       {
         name: "wp_get_current_user",
-        description: "Retrieves the currently authenticated user.",
+        description:
+          "Retrieves the currently authenticated user with comprehensive profile information including roles, capabilities, and account details.\n\n" +
+          "**Usage Examples:**\n" +
+          "• Get current user: `wp_get_current_user`\n" +
+          "• Check permissions: Use this to verify your current user's capabilities and roles\n" +
+          "• Account verification: Confirm you're authenticated with the correct account\n" +
+          "• Profile details: View registration date, email, and user metadata",
         parameters: [],
         handler: this.handleGetCurrentUser.bind(this),
       },
@@ -121,8 +131,7 @@ export class UserTools {
           {
             name: "reassign",
             type: "number",
-            description:
-              "The ID of a user to reassign the deleted user's content to.",
+            description: "The ID of a user to reassign the deleted user's content to.",
           },
         ],
         handler: this.handleDeleteUser.bind(this),
@@ -130,33 +139,86 @@ export class UserTools {
     ];
   }
 
-  public async handleListUsers(
-    client: WordPressClient,
-    params: UserQueryParams,
-  ): Promise<any> {
+  public async handleListUsers(client: WordPressClient, params: UserQueryParams): Promise<any> {
     try {
       const users = await client.getUsers(params);
       if (users.length === 0) {
         return "No users found matching the criteria.";
       }
+
+      // Use streaming for large user result sets (>30 users)
+      if (users.length > 30) {
+        const streamResults: StreamingResult<any>[] = [];
+
+        for await (const result of WordPressDataStreamer.streamUsers(users, {
+          includeRoles: true,
+          includeCapabilities: false, // Too verbose for large sets
+          batchSize: 15,
+        })) {
+          streamResults.push(result);
+        }
+
+        return StreamingUtils.formatStreamingResponse(streamResults, "users");
+      }
+
+      // Enhanced user information with comprehensive details
+      const siteUrl = client.getSiteUrl ? client.getSiteUrl() : "Unknown site";
+      const userCount = users.length;
+      const rolesSummary = users.reduce(
+        (acc, u) => {
+          const roles = u.roles || [];
+          roles.forEach((role) => {
+            acc[role] = (acc[role] || 0) + 1;
+          });
+          return acc;
+        },
+        {} as Record<string, number>,
+      );
+
+      const metadata = [
+        `👥 **Users Summary**: ${userCount} total users`,
+        `🌐 **Source**: ${siteUrl}`,
+        `📊 **Roles Distribution**: ${Object.entries(rolesSummary)
+          .map(([role, count]) => `${role}: ${count}`)
+          .join(", ")}`,
+        `📅 **Retrieved**: ${new Date().toLocaleString()}`,
+      ];
+
       const content =
-        `Found ${users.length} users:\n\n` +
+        metadata.join("\n") +
+        "\n\n" +
         users
-          .map(
-            (u) =>
-              `- ID ${u.id}: **${u.name}** (@${u.slug}) - ${u.email}\n  Roles: ${u.roles?.join(", ") || "N/A"}`,
-          )
-          .join("\n");
+          .map((u) => {
+            const registrationDate = u.registered_date
+              ? new Date(u.registered_date).toLocaleDateString("en-US", {
+                  year: "numeric",
+                  month: "short",
+                  day: "numeric",
+                })
+              : "Unknown";
+
+            const roles = u.roles?.join(", ") || "No roles";
+            const description = u.description || "No description";
+            const displayName = u.name || "No display name";
+            const userUrl = u.url || "No URL";
+
+            return (
+              `- **ID ${u.id}**: ${displayName} (@${u.slug})\n` +
+              `  📧 Email: ${u.email || "No email"}\n` +
+              `  🎭 Roles: ${roles}\n` +
+              `  📅 Registered: ${registrationDate}\n` +
+              `  🔗 URL: ${userUrl}\n` +
+              `  📝 Description: ${description}`
+            );
+          })
+          .join("\n\n");
       return content;
     } catch (error) {
       throw new Error(`Failed to list users: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleGetUser(
-    client: WordPressClient,
-    params: { id: number },
-  ): Promise<any> {
+  public async handleGetUser(client: WordPressClient, params: { id: number }): Promise<any> {
     try {
       const user = await client.getUser(params.id);
       const content =
@@ -171,28 +233,70 @@ export class UserTools {
     }
   }
 
-  public async handleGetCurrentUser(
-    client: WordPressClient,
-    params: any,
-  ): Promise<any> {
+  public async handleGetCurrentUser(client: WordPressClient, params: any): Promise<any> {
     try {
       const user = await client.getCurrentUser();
+      const siteUrl = client.getSiteUrl();
+
+      // Extract meaningful information from capabilities
+      const capabilities = user.capabilities || {};
+      const keyCapabilities = [
+        "edit_posts",
+        "edit_pages",
+        "publish_posts",
+        "publish_pages",
+        "delete_posts",
+        "delete_pages",
+        "manage_categories",
+        "manage_options",
+        "moderate_comments",
+        "upload_files",
+        "edit_others_posts",
+        "delete_others_posts",
+      ];
+
+      const userCapabilities = keyCapabilities.filter((cap) => capabilities[cap]).join(", ");
+      const totalCapabilities = Object.keys(capabilities).length;
+
+      // Format registration date more clearly
+      const registrationDate = user.registered_date
+        ? new Date(user.registered_date).toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "long",
+            day: "numeric",
+          })
+        : "Not available";
+
+      // Extract role information
+      const roles = user.roles || [];
+      const primaryRole = roles[0] || "No role assigned";
+      const allRoles = roles.length > 1 ? roles.join(", ") : primaryRole;
+
+      // Build comprehensive user information
       const content =
-        `**Current User Details (ID: ${user.id})**\n\n` +
-        `- **Name:** ${user.name}\n` +
-        `- **Username:** ${user.slug}\n` +
-        `- **Email:** ${user.email}\n` +
-        `- **Roles:** ${user.roles?.join(", ") || "N/A"}`;
+        `**Current User Details for ${siteUrl}**\n\n` +
+        `- **ID:** ${user.id}\n` +
+        `- **Display Name:** ${user.name || "Not set"}\n` +
+        `- **Username:** ${user.slug || "Not set"}\n` +
+        `- **Email:** ${user.email || "Not set"}\n` +
+        `- **User URL:** ${user.url || "Not set"}\n` +
+        `- **Nickname:** ${user.nickname || user.name || "Not set"}\n` +
+        `- **Description:** ${user.description || "No description provided"}\n` +
+        `- **Locale:** ${user.locale || "Default"}\n` +
+        `- **Registration Date:** ${registrationDate}\n` +
+        `- **Primary Role:** ${primaryRole}\n` +
+        `- **All Roles:** ${allRoles}\n` +
+        `- **Total Capabilities:** ${totalCapabilities} capabilities\n` +
+        `- **Key Capabilities:** ${userCapabilities || "None"}\n` +
+        `- **Profile Link:** ${user.link || `${siteUrl}/wp-admin/profile.php`}`;
+
       return content;
     } catch (error) {
       throw new Error(`Failed to get current user: ${getErrorMessage(error)}`);
     }
   }
 
-  public async handleCreateUser(
-    client: WordPressClient,
-    params: CreateUserRequest,
-  ): Promise<any> {
+  public async handleCreateUser(client: WordPressClient, params: CreateUserRequest): Promise<any> {
     try {
       const user = await client.createUser(params);
       return `✅ User "${user.name}" created successfully with ID: ${user.id}.`;
@@ -201,10 +305,7 @@ export class UserTools {
     }
   }
 
-  public async handleUpdateUser(
-    client: WordPressClient,
-    params: UpdateUserRequest & { id: number },
-  ): Promise<any> {
+  public async handleUpdateUser(client: WordPressClient, params: UpdateUserRequest & { id: number }): Promise<any> {
     try {
       const user = await client.updateUser(params);
       return `✅ User ${user.id} updated successfully.`;
@@ -213,10 +314,7 @@ export class UserTools {
     }
   }
 
-  public async handleDeleteUser(
-    client: WordPressClient,
-    params: { id: number; reassign?: number },
-  ): Promise<any> {
+  public async handleDeleteUser(client: WordPressClient, params: { id: number; reassign?: number }): Promise<any> {
     try {
       await client.deleteUser(params.id, params.reassign);
       let content = `✅ User ${params.id} has been deleted.`;