MCP WordPress Server

Instructions

Implementation Reference

• src/tools/users.ts:154-231 (handler)

  The main handler function that executes the wp_list_users tool. It fetches users using the WordPressClient, applies streaming for large lists, generates summaries and formatted output with roles, registration dates, and metadata.

  public async handleListUsers(client: WordPressClient, params: UserQueryParams): Promise<unknown> {
    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<unknown>[] = [];
  
        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 =
        metadata.join("\n") +
        "\n\n" +
        users
          .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)}`);
    }
  }

• src/tools/users.ts:29-52 (schema)

  The tool definition object specifying the name, description, input parameters schema (search string, roles array), and reference to the handler function.

  {
    name: "wp_list_users",
    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",
        type: "string",
        description: "Limit results to those matching a search term.",
      },
      {
        name: "roles",
        type: "array",
        items: { type: "string" },
        description: "Limit results to users with specific roles.",
      },
    ],
    handler: this.handleListUsers.bind(this),

• src/server/ToolRegistry.ts:46-62 (registration)

  Generic registration loop in ToolRegistry.registerAllTools() that instantiates UserTools (imported via * as Tools from '@/tools/index.js'), calls getTools() to retrieve the wp_list_users definition, and registers it with the MCP server via registerTool() which adds Zod validation and site selection.

  // Register all tools from the tools directory
  Object.values(Tools).forEach((ToolClass) => {
    let toolInstance: { getTools(): unknown[] };
  
    // Cache and Performance tools need the clients map
    if (ToolClass.name === "CacheTools" || ToolClass.name === "PerformanceTools") {
      toolInstance = new ToolClass(this.wordpressClients);
    } else {
      toolInstance = new (ToolClass as new () => { getTools(): unknown[] })();
    }
  
    const tools = toolInstance.getTools();
  
    tools.forEach((tool: unknown) => {
      this.registerTool(tool as ToolDefinition);
    });
  });

• src/index.ts:39-40 (registration)

  Calls ToolRegistry.registerAllTools() during server startup after creating the registry, which triggers registration of all tools including wp_list_users.

  private setupTools() {
    this.toolRegistry.registerAllTools();