Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/user.handlers.ts:70-114 (handler)

  The core handler function implementing the userGrowthAnalytics tool. It fetches the user's current profile and recent tweets using SocialData client, computes growth metrics like followers, recent activity, and average engagement, then formats and returns the analytics.

  export const handleUserGrowthAnalytics: SocialDataHandler<UserGrowthAnalyticsArgs> = async (
      _client: any,
      { username, timeframe = 'weekly', period = 4 }: UserGrowthAnalyticsArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('User Growth Analytics');
          }
          
          // Get current profile
          const currentProfile = await socialClient.getUserProfile({ username, includeMetrics: true });
          
          // Get recent tweets to analyze growth patterns
          const tweets = await socialClient.getUserTweets({ username, maxResults: 50 });
          
          // Calculate basic growth metrics from available data
          const analytics = {
              user: {
                  username: currentProfile.data.username,
                  current_followers: currentProfile.data.public_metrics?.followers_count || 0,
                  current_following: currentProfile.data.public_metrics?.following_count || 0,
                  total_tweets: currentProfile.data.public_metrics?.tweet_count || 0
              },
              timeframe,
              period,
              recent_activity: {
                  recent_tweets_count: tweets.data?.length || 0,
                  avg_engagement: tweets.data ? 
                      tweets.data.reduce((sum: number, tweet: any) => 
                          sum + (tweet.public_metrics?.like_count || 0) + 
                                (tweet.public_metrics?.retweet_count || 0), 0) / tweets.data.length 
                      : 0
              },
              note: 'Growth analytics based on current snapshot and recent activity patterns'
          };
  
          return createSocialDataResponse(
              formatAnalytics(analytics, `User Growth Analytics for @${username}`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'user growth analytics'));
      }
  };

• src/socialdata-tools.ts:128-151 (schema)

  Input schema definition for the userGrowthAnalytics tool, specifying parameters like username (required), timeframe, and period with validation rules.

  userGrowthAnalytics: {
      description: 'Analyze user growth patterns and engagement trends over time',
      inputSchema: {
          type: 'object',
          properties: {
              username: {
                  type: 'string',
                  description: 'Username to analyze growth patterns for'
              },
              timeframe: {
                  type: 'string',
                  enum: ['daily', 'weekly', 'monthly'],
                  description: 'Analysis timeframe (default: "weekly")'
              },
              period: {
                  type: 'number',
                  description: 'Number of periods to analyze (default: 4)',
                  minimum: 1,
                  maximum: 12
              }
          },
          required: ['username']
      }
  },

• src/index.ts:446-449 (registration)

  Tool dispatch/registration in the main CallToolRequestSchema handler switch statement, routing calls to userGrowthAnalytics to the handleUserGrowthAnalytics function.

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

• src/types/socialdata.ts:46-50 (schema)

  TypeScript interface defining the input arguments for userGrowthAnalytics, used for type safety in the handler.

  export interface UserGrowthAnalyticsArgs {
      username: string;
      timeframe: 'daily' | 'weekly' | 'monthly';
      period?: number; // number of days/weeks/months
  }