getThreadMetrics
Analyze Twitter thread performance, engagement distribution, and user interactions by specifying a root tweet ID and optional timeframe. Gain insights into metrics for better strategy optimization.
Instructions
Analyze thread performance and engagement distribution
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| analyzeEngagement | No | Include detailed engagement analysis (default: true) | |
| timeframe | No | Analysis timeframe (default: "24h") | |
| tweetId | Yes | The thread root tweet ID |
Implementation Reference
- Main handler function for getThreadMetrics tool. Fetches thread tweets via SocialData client, computes aggregate engagement metrics, per-tweet averages, engagement distribution, 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/socialdata-tools.ts:218-238 (schema)JSON Schema definition for the getThreadMetrics tool input parameters, used for tool registration.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 the input arguments for the getThreadMetrics handler.export interface ThreadMetricsArgs { tweetId: string; analyzeEngagement?: boolean; timeframe?: string; }
- src/index.ts:467-470 (registration)Tool registration and dispatch in the main MCP server request handler switch statement.case 'getThreadMetrics': { const args = request.params.arguments as any; response = await handleGetThreadMetrics(client, args); break;