buddypress_list_messages

Retrieve and organize user message threads from BuddyPress community sites, filtering by inbox/sentbox, read/unread status, and pagination for efficient management.

Instructions

List message threads

Input Schema

TableJSON Schema

Name	Required	Description
`user_id`	No	User ID to get messages for
`box`	No	Message box (inbox, sentbox, notices)
`type`	No	Message type (all, read, unread)
`page`	No	Page number (default: 1)
`per_page`	No	Items per page (default: 20)

Implementation Reference

src/index.ts:687-694 (handler)

Handler implementation for the buddypress_list_messages tool. Constructs query parameters from input arguments and makes an authenticated API request to the BuddyPress /messages endpoint.

else if (name === 'buddypress_list_messages') {
  const params = new URLSearchParams();
  if (args.user_id) params.append('user_id', String(args.user_id));
  if (args.box) params.append('box', String(args.box));
  if (args.type) params.append('type', String(args.type));
  if (args.page) params.append('page', String(args.page));
  if (args.per_page) params.append('per_page', String(args.per_page));
  result = await buddypressRequest(`/messages?${params}`);

src/index.ts:403-416 (registration)

Registration of the buddypress_list_messages tool in the tools array, including name, description, and input schema definition.

{
  name: 'buddypress_list_messages',
  description: 'List message threads',
  inputSchema: {
    type: 'object',
    properties: {
      user_id: { type: 'number', description: 'User ID to get messages for' },
      box: { type: 'string', description: 'Message box (inbox, sentbox, notices)' },
      type: { type: 'string', description: 'Message type (all, read, unread)' },
      page: { type: 'number', description: 'Page number (default: 1)' },
      per_page: { type: 'number', description: 'Items per page (default: 20)' },
    },
  },
},

src/index.ts:406-415 (schema)

Input schema definition for validating arguments to the buddypress_list_messages tool.

inputSchema: {
  type: 'object',
  properties: {
    user_id: { type: 'number', description: 'User ID to get messages for' },
    box: { type: 'string', description: 'Message box (inbox, sentbox, notices)' },
    type: { type: 'string', description: 'Message type (all, read, unread)' },
    page: { type: 'number', description: 'Page number (default: 1)' },
    per_page: { type: 'number', description: 'Items per page (default: 20)' },
  },
},

src/index.ts:18-46 (helper)

Shared helper function used by the tool handler to make authenticated requests to the BuddyPress REST API.

async function buddypressRequest(
  endpoint: string,
  method: string = 'GET',
  body?: any
): Promise<any> {
  const url = `${BUDDYPRESS_URL}/wp-json/buddypress/v2${endpoint}`;
  const auth = Buffer.from(`${BUDDYPRESS_USERNAME}:${BUDDYPRESS_PASSWORD}`).toString('base64');

  const options: any = {
    method,
    headers: {
      'Authorization': `Basic ${auth}`,
      'Content-Type': 'application/json',
    },
  };

  if (body && method !== 'GET') {
    options.body = JSON.stringify(body);
  }

  const response = await fetch(url, options);

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`BuddyPress API Error (${response.status}): ${errorText}`);
  }

  return await response.json();
}

BuddyPress MCP Server