Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/search.handlers.ts:60-101 (handler)

  The core handler function for 'getHashtagAnalytics' that searches for tweets containing the specified hashtag (optionally within a time range), computes aggregate analytics (total tweets, likes, retweets, replies), and returns formatted results. Handles errors including API tier requirements.

  export const handleHashtagAnalytics: TwitterHandler<HashtagAnalyticsArgs> = async (
      client: TwitterClient | null,
      { hashtag, startTime, endTime }: HashtagAnalyticsArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('hashtagAnalytics');
      }
      try {
          const query = `#${hashtag.replace(/^#/, '')}`;
          const searchResult = await client.v2.search(query, {
              max_results: 100,
              'tweet.fields': 'public_metrics,created_at',
              start_time: startTime,
              end_time: endTime
          });
  
          const tweets = Array.isArray(searchResult.data) ? searchResult.data : [];
          if (tweets.length === 0) {
              return createResponse(`No tweets found for hashtag: ${hashtag}`);
          }
  
          const analytics = {
              totalTweets: tweets.length,
              totalLikes: tweets.reduce((sum: number, tweet: TweetV2) => 
                  sum + (tweet.public_metrics?.like_count || 0), 0),
              totalRetweets: tweets.reduce((sum: number, tweet: TweetV2) => 
                  sum + (tweet.public_metrics?.retweet_count || 0), 0),
              totalReplies: tweets.reduce((sum: number, tweet: TweetV2) => 
                  sum + (tweet.public_metrics?.reply_count || 0), 0)
          };
  
          return createResponse(`Hashtag Analytics for ${hashtag}:\n${JSON.stringify(analytics, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('400') && error.message.includes('Invalid Request')) {
                  throw new Error(`Hashtag analytics requires Pro tier access ($5,000/month) or higher for search functionality. Current Basic tier ($200/month) does not include recent search API access. Consider upgrading at https://developer.x.com/en/portal/products/pro or use alternative analytics sources.`);
              }
              throw new Error(formatTwitterError(error, 'getting hashtag analytics'));
          }
          throw error;
      }
  }; 

• src/tools.ts:403-423 (schema)

  Tool schema definition including description and input schema (hashtag required, startTime/endTime optional ISO 8601 strings) used for MCP tool listing and validation.

  getHashtagAnalytics: {
      description: 'Get analytics for a specific hashtag',
      inputSchema: {
          type: 'object',
          properties: {
              hashtag: {
                  type: 'string',
                  description: 'The hashtag to analyze (with or without #)'
              },
              startTime: {
                  type: 'string',
                  description: 'Start time for the analysis (ISO 8601)'
              },
              endTime: {
                  type: 'string',
                  description: 'End time for the analysis (ISO 8601)'
              }
          },
          required: ['hashtag']
      }
  },

• src/index.ts:318-326 (registration)

  Switch case in the main CallToolRequestHandler that registers and dispatches 'getHashtagAnalytics' calls to the handleHashtagAnalytics function.

  case 'getHashtagAnalytics': {
      const { hashtag, startTime, endTime } = request.params.arguments as {
          hashtag: string;
          startTime?: string;
          endTime?: string;
      };
      response = await handleHashtagAnalytics(client, { hashtag, startTime, endTime });
      break;
  }

• src/types.ts:117-121 (schema)

  TypeScript interface defining input arguments for getHashtagAnalytics (note: slightly differs from runtime schema; possibly legacy or additional).

  export interface GetHashtagAnalyticsArgs {
      hashtag: string;
      maxResults?: number;
      tweetFields?: string[];
  }

• src/types.ts:491-514 (schema)

  Runtime type assertion function for validating getHashtagAnalytics arguments.

  export function assertGetHashtagAnalyticsArgs(args: unknown): asserts args is GetHashtagAnalyticsArgs {
      if (typeof args !== 'object' || args === null) {
          throw new Error('Invalid arguments: expected object');
      }
      if (!('hashtag' in args) || typeof (args as any).hashtag !== 'string') {
          throw new Error('Invalid arguments: expected hashtag string');
      }
      if ('maxResults' in args) {
          const maxResults = (args as any).maxResults;
          if (typeof maxResults !== 'number' || maxResults < 10 || maxResults > 100) {
              throw new Error('Invalid arguments: maxResults must be a number between 10 and 100');
          }
      }
      if ('tweetFields' in args) {
          if (!Array.isArray((args as any).tweetFields)) {
              throw new Error('Invalid arguments: expected tweetFields to be an array');
          }
          for (const field of (args as any).tweetFields) {
              if (typeof field !== 'string') {
                  throw new Error('Invalid arguments: expected tweetFields to be an array of strings');
              }
          }
      }
  }