Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/user.handlers.ts:116-179 (handler)

  Core handler function that executes the userInfluenceMetrics tool. Fetches user profile and recent tweets using SocialData client, computes engagement metrics (avg likes/retweets/replies, engagement rate) and reach metrics (follower base, influence score), formats and returns the response.

  export const handleUserInfluenceMetrics: SocialDataHandler<UserInfluenceMetricsArgs> = async (
      _client: any,
      { username, analyzeEngagement = true, analyzeReach = true }: UserInfluenceMetricsArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('User Influence Metrics');
          }
          
          // Get user profile and recent tweets
          const [profile, tweets] = await Promise.all([
              socialClient.getUserProfile({ username, includeMetrics: true }),
              socialClient.getUserTweets({ username, maxResults: 20 })
          ]);
  
          const user = profile.data;
          const recentTweets = tweets.data || [];
          
          // Calculate influence metrics
          const metrics: any = {
              user: {
                  username: user.username,
                  followers: user.public_metrics?.followers_count || 0,
                  following: user.public_metrics?.following_count || 0,
                  verified: user.verified || false
              }
          };
  
          if (analyzeEngagement && recentTweets.length > 0) {
              const totalLikes = recentTweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.public_metrics?.like_count || 0), 0);
              const totalRetweets = recentTweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.public_metrics?.retweet_count || 0), 0);
              const totalReplies = recentTweets.reduce((sum: number, tweet: any) => 
                  sum + (tweet.public_metrics?.reply_count || 0), 0);
  
              metrics.engagement = {
                  avg_likes_per_tweet: Math.round(totalLikes / recentTweets.length),
                  avg_retweets_per_tweet: Math.round(totalRetweets / recentTweets.length),
                  avg_replies_per_tweet: Math.round(totalReplies / recentTweets.length),
                  engagement_rate: user.public_metrics?.followers_count > 0 ? 
                      Math.round(((totalLikes + totalRetweets + totalReplies) / recentTweets.length / 
                      user.public_metrics.followers_count) * 10000) / 100 : 0
              };
          }
  
          if (analyzeReach) {
              metrics.reach = {
                  follower_base: user.public_metrics?.followers_count || 0,
                  potential_reach: user.public_metrics?.followers_count || 0,
                  estimated_influence_score: Math.min(100, 
                      Math.log10((user.public_metrics?.followers_count || 1) + 1) * 20)
              };
          }
  
          return createSocialDataResponse(
              formatAnalytics(metrics, `Influence Metrics for @${username}`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'user influence metrics'));
      }
  };

• src/socialdata-tools.ts:153-173 (schema)

  Tool schema definition including description and input validation schema for the userInfluenceMetrics tool, used for MCP tool registration.

  userInfluenceMetrics: {
      description: 'Calculate user influence scores and engagement metrics',
      inputSchema: {
          type: 'object',
          properties: {
              username: {
                  type: 'string',
                  description: 'Username to analyze influence metrics for'
              },
              analyzeEngagement: {
                  type: 'boolean',
                  description: 'Include engagement analysis (default: true)'
              },
              analyzeReach: {
                  type: 'boolean',
                  description: 'Include reach and influence scoring (default: true)'
              }
          },
          required: ['username']
      }
  },

• src/types/socialdata.ts:52-56 (schema)

  TypeScript interface defining the input arguments for the userInfluenceMetrics handler.

  export interface UserInfluenceMetricsArgs {
      username: string;
      analyzeEngagement?: boolean;
      analyzeReach?: boolean;
  }

• src/index.ts:451-454 (registration)

  Tool dispatch/registration in the main MCP server request handler switch statement, calling the specific handler function.

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

• src/index.ts:73-83 (registration)

  Import of the handleUserInfluenceMetrics handler function into the main index file for use in tool dispatching.

      handleUserInfluenceMetrics,
      handleGetFullThread,
      handleGetConversationTree,
      handleGetThreadMetrics,
      handleFindMutualConnections,
      handleAnalyzeFollowerDemographics,
      handleMapInfluenceNetwork,
      handleGetHashtagTrends,
      handleAnalyzeSentiment,
      handleTrackVirality
  } from './handlers/socialdata/index.js';