Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/directmessage.handlers.ts:97-149 (handler)

  Core handler function that implements the getDirectMessageEvents tool by calling Twitter v2 API listDmEvents with appropriate parameters and formatting the response.

  /**
   * Get specific direct message events
   */
  export const handleGetDirectMessageEvents: TwitterHandler<GetDirectMessageEventsArgs> = async (
      client: TwitterClient | null,
      { maxResults = 100, paginationToken, dmEventFields, expansions, userFields }: GetDirectMessageEventsArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getDirectMessageEvents');
      }
      try {
          const options: any = {
              max_results: Math.min(maxResults, 100)
          };
  
          if (paginationToken) {
              options.pagination_token = paginationToken;
          }
  
          if (dmEventFields && dmEventFields.length > 0) {
              options['dm_event.fields'] = dmEventFields.join(',');
          } else {
              options['dm_event.fields'] = 'id,text,created_at,sender_id,dm_conversation_id,referenced_tweet,attachments';
          }
  
          if (expansions && expansions.length > 0) {
              options.expansions = expansions.join(',');
          }
  
          if (userFields && userFields.length > 0) {
              options['user.fields'] = userFields.join(',');
          }
  
          const events = await client.v2.listDmEvents(options);
  
          if (!events.data || !Array.isArray(events.data) || events.data.length === 0) {
              return createResponse('No direct message events found.');
          }
  
          const responseData = {
              events: events.data,
              includes: events.includes,
              meta: events.meta
          };
  
          return createResponse(`Retrieved ${events.data.length} direct message events: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'getting direct message events'));
          }
          throw error;
      }
  };

• src/types/handlers.ts:86-92 (schema)

  TypeScript interface defining the input parameters for the getDirectMessageEvents handler.

  export interface GetDirectMessageEventsArgs {
      maxResults?: number;
      paginationToken?: string;
      dmEventFields?: string[];
      expansions?: string[];
      userFields?: string[];
  }

• src/tools.ts:491-533 (registration)

  MCP tool object registration defining the description and input schema (JSON Schema) for getDirectMessageEvents.

  getDirectMessageEvents: {
      description: 'Get specific direct message events with detailed information',
      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' 
              },
              expansions: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['sender_id', 'referenced_tweet.id', 'attachments.media_keys']
                  },
                  description: 'Additional fields to expand in the response' 
              },
              userFields: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['username', 'name', 'profile_image_url', 'verified']
                  },
                  description: 'User fields to include when expanding sender information' 
              }
          },
          required: []
      }
  },

• src/index.ts:347-356 (registration)

  Server request handler dispatch case that invokes the getDirectMessageEvents handler function with parsed arguments.

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