getDirectMessages

Instructions

Implementation Reference

• src/handlers/directmessage.handlers.ts:53-95 (handler)

  The main handler function that implements the getDirectMessages tool. It checks for Twitter client, constructs API options for listing DM events, calls the Twitter v2 API, and formats the response.

  export const handleGetDirectMessages: TwitterHandler<GetDirectMessagesArgs> = async (
      client: TwitterClient | null,
      { maxResults = 100, paginationToken, dmEventFields }: GetDirectMessagesArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getDirectMessages');
      }
      try {
          const options: any = {
              max_results: Math.min(maxResults, 100) // API limit is 100
          };
  
          if (paginationToken) {
              options.pagination_token = paginationToken;
          }
  
          if (dmEventFields && dmEventFields.length > 0) {
              options['dm_event.fields'] = dmEventFields.join(',');
          } else {
              // Default fields for better response
              options['dm_event.fields'] = 'id,text,created_at,sender_id,dm_conversation_id,referenced_tweet,attachments';
          }
  
          // Using v2 API for DM conversations
          const conversations = await client.v2.listDmEvents(options);
  
          if (!conversations.data || !Array.isArray(conversations.data) || conversations.data.length === 0) {
              return createResponse('No direct message conversations found.');
          }
  
          const responseData = {
              conversations: conversations.data,
              meta: conversations.meta
          };
  
          return createResponse(`Retrieved ${conversations.data.length} direct message events: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'getting direct messages'));
          }
          throw error;
      }
  };

• src/tools.ts:464-490 (schema)

  MCP tool definition including name 'getDirectMessages', description, and inputSchema for validation.

  getDirectMessages: {
      description: 'Retrieve direct message conversations',
      inputSchema: {
          type: 'object',
          properties: {
              maxResults: { 
                  type: 'number', 
                  description: 'Maximum number of results to return (default: 100, max: 100)',
                  minimum: 1,
                  maximum: 100
              },
              paginationToken: { 
                  type: 'string', 
                  description: 'Pagination token for retrieving next page of results' 
              },
              dmEventFields: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['id', 'text', 'created_at', 'sender_id', 'dm_conversation_id', 'referenced_tweet', 'attachments']
                  },
                  description: 'Fields to include in the DM event objects' 
              }
          },
          required: []
      }
  },

• src/types/handlers.ts:80-84 (schema)

  TypeScript interface defining the input arguments for the getDirectMessages handler.

  export interface GetDirectMessagesArgs {
      maxResults?: number;
      paginationToken?: string;
      dmEventFields?: string[];
  }

• src/index.ts:338-345 (registration)

  Registration and dispatching of the getDirectMessages tool in the main server request handler switch statement.

  case 'getDirectMessages': {
      const { maxResults, paginationToken, dmEventFields } = request.params.arguments as {
          maxResults?: number;
          paginationToken?: string;
          dmEventFields?: string[];
      };
      response = await handleGetDirectMessages(client, { maxResults, paginationToken, dmEventFields });
      break;