mcp-wordpress 1.1.2

package/src/tools/auth.ts

@@ -0,0 +1,153 @@
+import { WordPressClient } from "../client/api.js";
+import { AuthMethod } from "../types/client.js";
+import { getErrorMessage } from "../utils/error.js";
+
+/**
+ * Provides authentication-related tools for WordPress sites.
+ * This class encapsulates tool definitions and their corresponding handlers.
+ */
+export class AuthTools {
+  /**
+   * Retrieves the list of authentication tools.
+   * @returns An array of MCPTool definitions.
+   */
+  public getTools(): any[] {
+    return [
+      {
+        name: "wp_test_auth",
+        description:
+          "Tests the authentication and connectivity for a configured WordPress site.",
+        parameters: [], // The 'site' parameter is added dynamically by the server
+        handler: this.handleTestAuth.bind(this),
+      },
+      {
+        name: "wp_get_auth_status",
+        description:
+          "Gets the current authentication status for a configured WordPress site.",
+        parameters: [],
+        handler: this.handleGetAuthStatus.bind(this),
+      },
+      {
+        name: "wp_switch_auth_method",
+        description:
+          "Switches the authentication method for a site for the current session.",
+        parameters: [
+          {
+            name: "method",
+            type: "string",
+            required: true,
+            description: "The new authentication method to use.",
+            enum: ["app-password", "jwt", "basic", "api-key", "cookie"],
+          },
+          {
+            name: "username",
+            type: "string",
+            description:
+              "The username for 'app-password' or 'basic' authentication.",
+          },
+          {
+            name: "password",
+            type: "string",
+            description:
+              "The Application Password for 'app-password' or password for 'basic' auth.",
+          },
+          {
+            name: "jwt_token",
+            type: "string",
+            description: "The token for 'jwt' authentication.",
+          },
+        ],
+        handler: this.handleSwitchAuthMethod.bind(this),
+      },
+    ];
+  }
+
+  /**
+   * Handles the 'wp_test_auth' tool request.
+   * It tests the connection and fetches user details upon success.
+   * @param client - The WordPressClient instance for the target site.
+   * @param params - The parameters for the tool request.
+   * @returns A promise that resolves to an MCPToolResponse.
+   */
+  public async handleTestAuth(
+    client: WordPressClient,
+    params: any,
+  ): Promise<any> {
+    try {
+      await client.ping();
+      const user = await client.getCurrentUser();
+      const siteConfig = client.config;
+
+      const content =
+        `✅ **Authentication successful!**\n\n` +
+        `**Site:** ${siteConfig.baseUrl}\n` +
+        `**Method:** ${siteConfig.auth.method}\n` +
+        `**User:** ${user.name} (@${user.slug})\n` +
+        `**Roles:** ${user.roles?.join(", ") || "N/A"}\n\n` +
+        `Your WordPress connection is working properly.`;
+
+      return content;
+    } catch (error) {
+      throw new Error(`Authentication test failed: ${getErrorMessage(error)}`);
+    }
+  }
+
+  /**
+   * Handles the 'wp_get_auth_status' tool request.
+   * Reports whether the client is currently authenticated.
+   * @param client - The WordPressClient instance for the target site.
+   * @param params - The parameters for the tool request.
+   * @returns A promise that resolves to an MCPToolResponse.
+   */
+  public async handleGetAuthStatus(
+    client: WordPressClient,
+    params: any,
+  ): Promise<any> {
+    try {
+      const isAuthenticated = client.isAuthenticated;
+      const config = client.config;
+      let content =
+        `**Authentication Status for ${config.baseUrl}**\n\n` +
+        `**Authenticated:** ${isAuthenticated ? "✅ Yes" : "❌ No"}\n` +
+        `**Method:** ${config.auth.method}\n`;
+
+      if (isAuthenticated) {
+        const user = await client.getCurrentUser();
+        content += `**User:** ${user.name} (@${user.slug})\n`;
+      } else {
+        content += `**Status:** Not connected. Use 'wp_test_auth' to connect and verify credentials.`;
+      }
+
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to get auth status: ${getErrorMessage(error)}`);
+    }
+  }
+
+  /**
+   * Handles the 'wp_switch_auth_method' tool request.
+   * Updates the client's authentication configuration in memory for the session.
+   * @param client - The WordPressClient instance for the target site.
+   * @param params - The parameters for the tool request, including the new auth details.
+   * @returns A promise that resolves to an MCPToolResponse.
+   */
+  public async handleSwitchAuthMethod(
+    client: WordPressClient,
+    params: {
+      method: AuthMethod;
+      username?: string;
+      password?: string;
+      jwt_token?: string;
+    },
+  ): Promise<any> {
+    try {
+      // This functionality is not currently supported as the client
+      // doesn't have an updateAuthConfig method
+      throw new Error("Dynamic authentication method switching is not currently supported. Please update your configuration file and restart the server.");
+    } catch (error) {
+      throw new Error(`Failed to switch auth method: ${getErrorMessage(error)}`);
+    }
+  }
+}
+
+export default AuthTools;

package/src/tools/comments.ts

@@ -0,0 +1,263 @@
+import { WordPressClient } from "../client/api.js";
+import {
+  CommentQueryParams,
+  CreateCommentRequest,
+  UpdateCommentRequest,
+} from "../types/wordpress.js";
+import { getErrorMessage } from "../utils/error.js";
+
+/**
+ * Provides tools for managing comments on a WordPress site.
+ * This class encapsulates tool definitions and their corresponding handlers.
+ */
+export class CommentTools {
+  /**
+   * Retrieves the list of comment management tools.
+   * @returns An array of MCPTool definitions.
+   */
+  public getTools(): any[] {
+    return [
+      {
+        name: "wp_list_comments",
+        description: "Lists comments from a WordPress site, with filters.",
+        parameters: [
+          {
+            name: "post",
+            type: "number",
+            description:
+              "Limit results to comments assigned to a specific post ID.",
+          },
+          {
+            name: "status",
+            type: "string",
+            description: "Filter by comment status.",
+            enum: ["hold", "approve", "spam", "trash"],
+          },
+        ],
+        handler: this.handleListComments.bind(this),
+      },
+      {
+        name: "wp_get_comment",
+        description: "Retrieves a single comment by its ID.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The unique identifier for the comment.",
+          },
+        ],
+        handler: this.handleGetComment.bind(this),
+      },
+      {
+        name: "wp_create_comment",
+        description: "Creates a new comment on a post.",
+        parameters: [
+          {
+            name: "post",
+            type: "number",
+            required: true,
+            description: "The ID of the post to comment on.",
+          },
+          {
+            name: "content",
+            type: "string",
+            required: true,
+            description: "The content of the comment.",
+          },
+          {
+            name: "author_name",
+            type: "string",
+            description: "The name of the comment author.",
+          },
+          {
+            name: "author_email",
+            type: "string",
+            description: "The email of the comment author.",
+          },
+        ],
+        handler: this.handleCreateComment.bind(this),
+      },
+      {
+        name: "wp_update_comment",
+        description: "Updates an existing comment.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the comment to update.",
+          },
+          {
+            name: "content",
+            type: "string",
+            description: "The updated content for the comment.",
+          },
+          {
+            name: "status",
+            type: "string",
+            description: "The new status for the comment.",
+            enum: ["hold", "approve", "spam", "trash"],
+          },
+        ],
+        handler: this.handleUpdateComment.bind(this),
+      },
+      {
+        name: "wp_delete_comment",
+        description: "Deletes a comment.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the comment to delete.",
+          },
+          {
+            name: "force",
+            type: "boolean",
+            description:
+              "If true, the comment will be permanently deleted. Defaults to false (moved to trash).",
+          },
+        ],
+        handler: this.handleDeleteComment.bind(this),
+      },
+      {
+        name: "wp_approve_comment",
+        description: "Approves a pending comment.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the comment to approve.",
+          },
+        ],
+        handler: this.handleApproveComment.bind(this),
+      },
+      {
+        name: "wp_spam_comment",
+        description: "Marks a comment as spam.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the comment to mark as spam.",
+          },
+        ],
+        handler: this.handleSpamComment.bind(this),
+      },
+    ];
+  }
+
+  public async handleListComments(
+    client: WordPressClient,
+    params: CommentQueryParams,
+  ): Promise<any> {
+    try {
+      const comments = await client.getComments(params);
+      if (comments.length === 0) {
+        return "No comments found matching the criteria.";
+      }
+      const content =
+        `Found ${comments.length} comments:\n\n` +
+        comments
+          .map(
+            (c) =>
+              `- ID ${c.id}: By **${c.author_name}** on Post ${c.post} (${c.status})\n  > ${c.content.rendered.substring(0, 100)}...`,
+          )
+          .join("\n");
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to list comments: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleGetComment(
+    client: WordPressClient,
+    params: { id: number },
+  ): Promise<any> {
+    try {
+      const comment = await client.getComment(params.id);
+      const content =
+        `**Comment Details (ID: ${comment.id})**\n\n` +
+        `- **Author:** ${comment.author_name}\n` +
+        `- **Post ID:** ${comment.post}\n` +
+        `- **Date:** ${new Date(comment.date).toLocaleString()}\n` +
+        `- **Status:** ${comment.status}\n` +
+        `- **Content:** ${comment.content.rendered}`;
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to get comment: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleCreateComment(
+    client: WordPressClient,
+    params: CreateCommentRequest,
+  ): Promise<any> {
+    try {
+      const comment = await client.createComment(params);
+      return `✅ Comment created successfully with ID: ${comment.id}`;
+    } catch (error) {
+      throw new Error(`Failed to create comment: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleUpdateComment(
+    client: WordPressClient,
+    params: UpdateCommentRequest & { id: number },
+  ): Promise<any> {
+    try {
+      const comment = await client.updateComment(params);
+      return `✅ Comment ${comment.id} updated successfully. New status: ${comment.status}.`;
+    } catch (error) {
+      throw new Error(`Failed to update comment: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleDeleteComment(
+    client: WordPressClient,
+    params: { id: number; force?: boolean },
+  ): Promise<any> {
+    try {
+      await client.deleteComment(params.id, params.force);
+      const action = params.force ? "permanently deleted" : "moved to trash";
+      return `✅ Comment ${params.id} has been ${action}.`;
+    } catch (error) {
+      throw new Error(`Failed to delete comment: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleApproveComment(
+    client: WordPressClient,
+    params: { id: number },
+  ): Promise<any> {
+    try {
+      const comment = await client.updateComment({
+        id: params.id,
+        status: "approved",
+      });
+      return `✅ Comment ${comment.id} has been approved.`;
+    } catch (error) {
+      throw new Error(`Failed to approve comment: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleSpamComment(
+    client: WordPressClient,
+    params: { id: number },
+  ): Promise<any> {
+    try {
+      const comment = await client.updateComment({
+        id: params.id,
+        status: "spam",
+      });
+      return `✅ Comment ${comment.id} has been marked as spam.`;
+    } catch (error) {
+      throw new Error(`Failed to mark comment as spam: ${getErrorMessage(error)}`);
+    }
+  }
+}
+
+export default CommentTools;

package/src/tools/index.ts

@@ -0,0 +1,8 @@
+export { default as AuthTools } from './auth.js';
+export { default as CommentTools } from './comments.js';
+export { default as MediaTools } from './media.js';
+export { default as PageTools } from './pages.js';
+export { default as PostTools } from './posts.js';
+export { default as SiteTools } from './site.js';
+export { default as TaxonomyTools } from './taxonomies.js';
+export { default as UserTools } from './users.js';

package/src/tools/media.ts

@@ -0,0 +1,240 @@
+import * as fs from "fs";
+import * as path from "path";
+import { WordPressClient } from "../client/api.js";
+import {
+  MediaQueryParams,
+  UpdateMediaRequest,
+  UploadMediaRequest,
+  WordPressMedia,
+} from "../types/wordpress.js";
+import { getErrorMessage } from "../utils/error.js";
+
+/**
+ * Provides tools for managing media on a WordPress site.
+ * This class encapsulates tool definitions and their corresponding handlers.
+ */
+export class MediaTools {
+  /**
+   * Retrieves the list of media management tools.
+   * @returns An array of MCPTool definitions.
+   */
+  public getTools(): any[] {
+    return [
+      {
+        name: "wp_list_media",
+        description: "Lists media items from a WordPress site, with filters.",
+        parameters: [
+          {
+            name: "per_page",
+            type: "number",
+            description: "Number of items to return per page (max 100).",
+          },
+          {
+            name: "search",
+            type: "string",
+            description: "Limit results to those matching a search term.",
+          },
+          {
+            name: "media_type",
+            type: "string",
+            description: "Limit results to a specific media type.",
+            enum: ["image", "video", "audio", "application"],
+          },
+        ],
+        handler: this.handleListMedia.bind(this),
+      },
+      {
+        name: "wp_get_media",
+        description: "Retrieves a single media item by its ID.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The unique identifier for the media item.",
+          },
+        ],
+        handler: this.handleGetMedia.bind(this),
+      },
+      {
+        name: "wp_upload_media",
+        description: "Uploads a file to the WordPress media library.",
+        parameters: [
+          {
+            name: "file_path",
+            type: "string",
+            required: true,
+            description: "The local, absolute path to the file to upload.",
+          },
+          {
+            name: "title",
+            type: "string",
+            description: "The title for the media item.",
+          },
+          {
+            name: "alt_text",
+            type: "string",
+            description:
+              "Alternative text for the media item (for accessibility).",
+          },
+          {
+            name: "caption",
+            type: "string",
+            description: "The caption for the media item.",
+          },
+          {
+            name: "description",
+            type: "string",
+            description: "The description for the media item.",
+          },
+          {
+            name: "post",
+            type: "number",
+            description: "The ID of a post to attach this media to.",
+          },
+        ],
+        handler: this.handleUploadMedia.bind(this),
+      },
+      {
+        name: "wp_update_media",
+        description: "Updates the metadata of an existing media item.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the media item to update.",
+          },
+          {
+            name: "title",
+            type: "string",
+            description: "The new title for the media item.",
+          },
+          {
+            name: "alt_text",
+            type: "string",
+            description: "The new alternative text.",
+          },
+          {
+            name: "caption",
+            type: "string",
+            description: "The new caption.",
+          },
+          {
+            name: "description",
+            type: "string",
+            description: "The new description.",
+          },
+        ],
+        handler: this.handleUpdateMedia.bind(this),
+      },
+      {
+        name: "wp_delete_media",
+        description: "Deletes a media item.",
+        parameters: [
+          {
+            name: "id",
+            type: "number",
+            required: true,
+            description: "The ID of the media item to delete.",
+          },
+          {
+            name: "force",
+            type: "boolean",
+            description:
+              "If true, permanently delete. If false, move to trash. Defaults to false.",
+          },
+        ],
+        handler: this.handleDeleteMedia.bind(this),
+      },
+    ];
+  }
+
+  public async handleListMedia(
+    client: WordPressClient,
+    params: MediaQueryParams,
+  ): Promise<any> {
+    try {
+      const media = await client.getMedia(params);
+      if (media.length === 0) {
+        return "No media items found matching the criteria.";
+      }
+      const content =
+        `Found ${media.length} media items:\n\n` +
+        media
+          .map(
+            (m) =>
+              `- ID ${m.id}: **${m.title.rendered}** (${m.mime_type})\n  Link: ${m.source_url}`,
+          )
+          .join("\n");
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to list media: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleGetMedia(
+    client: WordPressClient,
+    params: { id: number },
+  ): Promise<any> {
+    try {
+      const media = await client.getMediaItem(params.id);
+      const content =
+        `**Media Details (ID: ${media.id})**\n\n` +
+        `- **Title:** ${media.title.rendered}\n` +
+        `- **URL:** ${media.source_url}\n` +
+        `- **Type:** ${media.media_type} (${media.mime_type})\n` +
+        `- **Date:** ${new Date(media.date).toLocaleString()}\n` +
+        (media.alt_text ? `- **Alt Text:** ${media.alt_text}\n` : "") +
+        (media.caption.rendered
+          ? `- **Caption:** ${media.caption.rendered}\n`
+          : "");
+      return content;
+    } catch (error) {
+      throw new Error(`Failed to get media item: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleUploadMedia(
+    client: WordPressClient,
+    params: UploadMediaRequest & { file_path: string },
+  ): Promise<any> {
+    try {
+      if (!fs.existsSync(params.file_path)) {
+        throw new Error(`File not found at path: ${params.file_path}`);
+      }
+
+      const media = await client.uploadMedia(params);
+      return `✅ Media uploaded successfully!\n- ID: ${media.id}\n- Title: ${media.title.rendered}\n- URL: ${media.source_url}`;
+    } catch (error) {
+      throw new Error(`Failed to upload media: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleUpdateMedia(
+    client: WordPressClient,
+    params: UpdateMediaRequest & { id: number },
+  ): Promise<any> {
+    try {
+      const media = await client.updateMedia(params);
+      return `✅ Media ${media.id} updated successfully.`;
+    } catch (error) {
+      throw new Error(`Failed to update media: ${getErrorMessage(error)}`);
+    }
+  }
+
+  public async handleDeleteMedia(
+    client: WordPressClient,
+    params: { id: number; force?: boolean },
+  ): Promise<any> {
+    try {
+      await client.deleteMedia(params.id, params.force);
+      const action = params.force ? "permanently deleted" : "moved to trash";
+      return `✅ Media item ${params.id} has been ${action}.`;
+    } catch (error) {
+      throw new Error(`Failed to delete media: ${getErrorMessage(error)}`);
+    }
+  }
+}
+
+export default MediaTools;