Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/thread.handlers.ts:153-221 (handler)

  Main handler function implementing getThreadMetrics: fetches conversation tweets using SocialData client, computes aggregate engagement metrics (likes, retweets, replies), per-tweet averages, engagement distribution across thread positions, and identifies top-performing tweet.

  export const handleGetThreadMetrics: SocialDataHandler<ThreadMetricsArgs> = async (
      _client: any,
      { tweetId, analyzeEngagement = true, timeframe = '24h' }: ThreadMetricsArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('Thread Metrics Analysis');
          }
          
          // Get thread data
          const threadQuery = `conversation_id:${tweetId}`;
          const threadResult = await socialClient.searchTweets({
              query: threadQuery,
              maxResults: 100
          });
  
          const tweets = threadResult.data || [];
          
          if (tweets.length === 0) {
              return createSocialDataResponse(`No thread data found for tweet ${tweetId}`);
          }
  
          let metrics: any = {
              thread_id: tweetId,
              thread_length: tweets.length,
              timeframe_analyzed: timeframe
          };
  
          if (analyzeEngagement) {
              const totalLikes = tweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.favorite_count || 0), 0);
              const totalRetweets = tweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.retweet_count || 0), 0);
              const totalReplies = tweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.reply_count || 0), 0);
  
              metrics.engagement_metrics = {
                  total_likes: totalLikes,
                  total_retweets: totalRetweets,
                  total_replies: totalReplies,
                  avg_likes_per_tweet: Math.round(totalLikes / tweets.length),
                  avg_retweets_per_tweet: Math.round(totalRetweets / tweets.length),
                  engagement_distribution: tweets.map((tweet: any, index: number) => ({
                      position: index + 1,
                      likes: tweet.favorite_count || 0,
                      retweets: tweet.retweet_count || 0,
                      engagement_score: (tweet.favorite_count || 0) + (tweet.retweet_count || 0) * 2
                  })).sort((a: any, b: any) => b.engagement_score - a.engagement_score)
              };
  
              // Find the most engaging tweet in thread
              const topTweet = metrics.engagement_metrics.engagement_distribution[0];
              metrics.top_performing_tweet = {
                  position: topTweet.position,
                  engagement_score: topTweet.engagement_score,
                  performance_boost: tweets.length > 1 ? 
                      Math.round((topTweet.engagement_score / (totalLikes + totalRetweets * 2)) * 100) : 100
              };
          }
  
          return createSocialDataResponse(
              formatAnalytics(metrics, `Thread Performance Metrics for ${tweetId}`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'thread metrics analysis'));
      }
  };

• src/index.ts:467-470 (registration)

  Tool call registration in main server request handler switch statement: routes 'getThreadMetrics' calls to the handleGetThreadMetrics function.

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

• src/socialdata-tools.ts:218-238 (schema)

  Tool schema definition in SOCIALDATA_TOOLS object: includes description and Zod-compatible inputSchema for listing and validation.

  getThreadMetrics: {
      description: 'Analyze thread performance and engagement distribution',
      inputSchema: {
          type: 'object',
          properties: {
              tweetId: {
                  type: 'string',
                  description: 'The thread root tweet ID'
              },
              analyzeEngagement: {
                  type: 'boolean',
                  description: 'Include detailed engagement analysis (default: true)'
              },
              timeframe: {
                  type: 'string',
                  description: 'Analysis timeframe (default: "24h")'
              }
          },
          required: ['tweetId']
      }
  },

• src/types/socialdata.ts:70-74 (schema)

  TypeScript interface defining input arguments for the handler function.

  export interface ThreadMetricsArgs {
      tweetId: string;
      analyzeEngagement?: boolean;
      timeframe?: string;
  }