Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/thread.handlers.ts:84-151 (handler)

  Main handler function executing the getConversationTree tool: fetches replies and quotes using SocialData client, builds conversation tree with metrics, formats and returns response.

  export const handleGetConversationTree: SocialDataHandler<ConversationTreeArgs> = async (
      _client: any,
      { tweetId, maxDepth = 3, includeQuotes = true }: ConversationTreeArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('Conversation Tree Analysis');
          }
          
          // Get direct replies
          const repliesQuery = `to:* ${tweetId}`;
          const repliesResult = await socialClient.searchTweets({
              query: repliesQuery,
              maxResults: 50
          });
  
          // Get quote tweets if requested
          let quoteTweets: any[] = [];
          if (includeQuotes) {
              const quotesQuery = `url:${tweetId} OR ${tweetId}`;
              const quotesResult = await socialClient.searchTweets({
                  query: quotesQuery,
                  maxResults: 25
              });
              quoteTweets = quotesResult.data || [];
          }
  
          const conversationTree = {
              root_tweet_id: tweetId,
              max_depth_analyzed: maxDepth,
              direct_replies: {
                  count: repliesResult.data?.length || 0,
                  tweets: repliesResult.data?.map((tweet: any) => ({
                      id: tweet.id_str,
                      text: tweet.text?.substring(0, 280),
                      author: tweet.user?.screen_name,
                      created_at: tweet.tweet_created_at,
                      metrics: {
                          likes: tweet.favorite_count || 0,
                          retweets: tweet.retweet_count || 0
                      }
                  })) || []
              },
              quote_tweets: {
                  count: quoteTweets.length,
                  tweets: quoteTweets.map((tweet: any) => ({
                      id: tweet.id_str,
                      text: tweet.text?.substring(0, 280),
                      author: tweet.user?.screen_name,
                      created_at: tweet.tweet_created_at
                  }))
              },
              engagement_summary: {
                  total_interactions: (repliesResult.data?.length || 0) + quoteTweets.length,
                  reply_rate: repliesResult.data?.length || 0,
                  quote_rate: quoteTweets.length
              }
          };
  
          return createSocialDataResponse(
              formatAnalytics(conversationTree, `Conversation Tree for ${tweetId}`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'conversation tree analysis'));
      }
  };

• src/socialdata-tools.ts:194-216 (schema)

  Input schema definition for the getConversationTree tool, specifying parameters tweetId (required), maxDepth, includeQuotes.

  getConversationTree: {
      description: 'Map complete conversation structure including replies and quotes',
      inputSchema: {
          type: 'object',
          properties: {
              tweetId: {
                  type: 'string',
                  description: 'The root tweet ID to map conversation for'
              },
              maxDepth: {
                  type: 'number',
                  description: 'Maximum conversation depth to analyze (default: 3)',
                  minimum: 1,
                  maximum: 5
              },
              includeQuotes: {
                  type: 'boolean',
                  description: 'Include quote tweets in analysis (default: true)'
              }
          },
          required: ['tweetId']
      }
  },

• src/types/socialdata.ts:64-68 (schema)

  TypeScript interface defining the input arguments for getConversationTree handler.

  export interface ConversationTreeArgs {
      tweetId: string;
      maxDepth?: number;
      includeQuotes?: boolean;
  }

• src/tools.ts:737-737 (registration)

  Registration of getConversationTree tool schema by spreading SOCIALDATA_TOOLS into the main TOOLS export used by MCP ListTools.

  ...SOCIALDATA_TOOLS

• src/index.ts:462-465 (registration)

  Dispatch/registration in MCP CallToolRequestHandler switch case, calling the handler for getConversationTree.

  case 'getConversationTree': {
      const args = request.params.arguments as any;
      response = await handleGetConversationTree(client, args);
      break;