Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/directmessage.handlers.ts:154-209 (handler)

  The handler function that implements the getConversation tool logic. It uses the Twitter v2 API to list DM events, filters by conversationId, and returns the conversation history.

  export const handleGetConversation: TwitterHandler<GetConversationArgs> = async (
      client: TwitterClient | null,
      { conversationId, maxResults = 100, paginationToken, dmEventFields }: GetConversationArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getConversation');
      }
      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';
          }
  
          // Get conversation messages using the conversation ID endpoint
          // Note: This would typically use a specific conversation endpoint
          // For now, we'll use the general listDmEvents and filter by conversation ID
          const conversation = await client.v2.listDmEvents({
              ...options,
              // Note: The actual API might have a different method for getting conversation-specific events
          });
  
          if (!conversation.data || !Array.isArray(conversation.data) || conversation.data.length === 0) {
              return createResponse(`No messages found in conversation ${conversationId}.`);
          }
  
          // Filter by conversation ID if needed (depending on API implementation)
          const filteredMessages = conversation.data.filter((event: any) => 
              event.dm_conversation_id === conversationId
          );
  
          const responseData = {
              conversationId,
              messages: filteredMessages.length > 0 ? filteredMessages : conversation.data,
              meta: conversation.meta
          };
  
          return createResponse(`Retrieved ${responseData.messages.length} messages from conversation ${conversationId}: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('404')) {
                  throw new Error(`Failed to get conversation: Conversation ${conversationId} not found.`);
              }
              throw new Error(formatTwitterError(error, 'getting conversation'));
          }
          throw error;
      }
  };

• src/tools.ts:534-564 (schema)

  The tool schema defining the description and input parameters for getConversation, used for MCP tool registration.

  getConversation: {
      description: 'Get full conversation history for a specific conversation',
      inputSchema: {
          type: 'object',
          properties: {
              conversationId: { 
                  type: 'string', 
                  description: 'The ID of the conversation to retrieve' 
              },
              maxResults: { 
                  type: 'number', 
                  description: 'Maximum number of messages 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: ['conversationId']
      }
  },

• src/index.ts:358-366 (registration)

  The dispatch case in the MCP server's CallToolRequest handler that routes 'getConversation' calls to the handleGetConversation function.

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

• src/types/handlers.ts:94-99 (schema)

  TypeScript interface defining the input arguments for the getConversation handler.

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