Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/analytics.handlers.ts:248-358 (handler)

  The core handler function that implements the trackVirality tool logic. It searches for retweets, quotes, and discussions related to a given tweet ID, analyzes spread patterns over time, calculates virality metrics including velocity, peak hours, top spreaders, and a viral score.
  export const handleTrackVirality: SocialDataHandler<ViralityTrackingArgs> = async ( _client: any, { tweetId, trackingPeriod = '24h', analyzeSpread = true }: ViralityTrackingArgs ) => { try { const socialClient = getSocialDataClient(); if (!socialClient) { return createMissingApiKeyResponse('Virality Tracking'); } // Search for retweets and mentions of the tweet const viralQuery = `${tweetId} OR url:${tweetId}`; const viralResult = await socialClient.searchTweets({ query: viralQuery, maxResults: 100 }); // Search for quotes and discussions const discussionQuery = `"${tweetId}"`; const discussionResult = await socialClient.searchTweets({ query: discussionQuery, maxResults: 50 }); const allInteractions = [...(viralResult.data || []), ...(discussionResult.data || [])]; if (allInteractions.length === 0) { return createSocialDataResponse(`No viral spread detected for tweet ${tweetId}`); } // Analyze spread pattern const spreadAnalysis: any = { tweet_id: tweetId, tracking_period: trackingPeriod, total_interactions: allInteractions.length, spread_metrics: { direct_shares: viralResult.data?.length || 0, discussions: discussionResult.data?.length || 0, unique_users: new Set(allInteractions.map(t => t.user?.screen_name)).size } }; if (analyzeSpread) { // Group by time to see spread velocity const timeGroups = new Map(); allInteractions.forEach((tweet: any) => { const hour = new Date(tweet.tweet_created_at).toISOString().substring(0, 13); if (!timeGroups.has(hour)) { timeGroups.set(hour, []); } timeGroups.get(hour).push(tweet); }); const spreadVelocity = Array.from(timeGroups.entries()) .map(([hour, tweets]: [string, any[]]) => ({ hour, interactions: tweets.length, cumulative: 0 // Will be calculated below })) .sort((a, b) => a.hour.localeCompare(b.hour)); // Calculate cumulative spread let cumulative = 0; spreadVelocity.forEach(period => { cumulative += period.interactions; period.cumulative = cumulative; }); // Find peak spread hour const peakHour = spreadVelocity.reduce((max, current) => current.interactions > max.interactions ? current : max); // Analyze influential spreaders const userEngagement = new Map(); allInteractions.forEach((tweet: any) => { const user = tweet.user?.screen_name; if (user) { const engagement = (tweet.favorite_count || 0) + (tweet.retweet_count || 0); userEngagement.set(user, (userEngagement.get(user) || 0) + engagement); } }); const topSpreaders = Array.from(userEngagement.entries()) .sort(([,a], [,b]) => b - a) .slice(0, 10) .map(([user, engagement]) => ({ user, engagement })); spreadAnalysis.virality_analysis = { spread_velocity: spreadVelocity, peak_spread_hour: peakHour.hour, viral_coefficient: Math.round(allInteractions.length / Math.max(1, timeGroups.size)), spread_pattern: spreadVelocity.length > 5 ? (peakHour.interactions > spreadVelocity[0].interactions * 3 ? 'Exponential' : 'Linear') : 'Limited', top_spreaders: topSpreaders, reach_estimate: topSpreaders.reduce((sum, spreader) => sum + spreader.engagement, 0), viral_score: Math.min(100, Math.round( (allInteractions.length * 0.3) + (userEngagement.size * 0.4) + (peakHour.interactions * 0.3) )) }; } return createSocialDataResponse( formatAnalytics(spreadAnalysis, `Virality Tracking for Tweet ${tweetId}`) ); } catch (error) { throw new Error(formatSocialDataError(error as Error, 'virality tracking')); } };
• src/socialdata-tools.ts:367-387 (schema)

  JSON Schema definition for the trackVirality tool, defining input parameters, descriptions, and requirements for tool discovery and validation.
  trackVirality: { description: 'Track viral spread patterns and engagement velocity', inputSchema: { type: 'object', properties: { tweetId: { type: 'string', description: 'Tweet ID to track virality for' }, trackingPeriod: { type: 'string', description: 'Period to track (default: "24h")' }, analyzeSpread: { type: 'boolean', description: 'Include detailed spread analysis (default: true)' } }, required: ['tweetId'] } }
• src/handlers/socialdata/analytics.handlers.ts:26-30 (schema)

  TypeScript interface defining the typed arguments for the handleTrackVirality function.
  interface ViralityTrackingArgs { tweetId: string; trackingPeriod?: string; analyzeSpread?: boolean; }
• src/index.ts:499-503 (registration)

  Registration in the main MCP server tool request handler switch statement, dispatching calls to the trackVirality tool to the appropriate handler function.
  case 'trackVirality': { const args = request.params.arguments as any; response = await handleTrackVirality(client, args); break; }