searchTweets

Instructions

Implementation Reference

• src/handlers/search.handlers.ts:23-58 (handler)

  The core handler function that executes the searchTweets tool logic. It performs a Twitter v2 search using the provided query, handles expansions for authors, formats the results, and includes tier requirement checks.

  export const handleSearchTweets: TwitterHandler<SearchTweetsArgs> = async (
      client: TwitterClient | null,
      { query, maxResults = 10, tweetFields }: SearchTweetsArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('searchTweets');
      }
      try {
          const searchResult = await client.v2.search(query, {
              max_results: maxResults,
              'tweet.fields': tweetFields?.join(',') || 'created_at,public_metrics',
              expansions: ['author_id'],
              'user.fields': ['username']
          });
  
          const tweets = Array.isArray(searchResult.data) ? searchResult.data : [];
          if (tweets.length === 0) {
              return createResponse(`No tweets found for query: ${query}`);
          }
  
          const formattedTweets = tweets.map((tweet: TweetV2): TweetWithAuthor => ({
              ...tweet,
              author: searchResult.includes?.users?.find((u: UserV2) => u.id === tweet.author_id)
          }));
  
          return createResponse(`Search results: ${JSON.stringify(formattedTweets, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              if (error.message.includes('400') && error.message.includes('Invalid Request')) {
                  throw new Error(`Search functionality requires Pro tier access ($5,000/month) or higher. 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 data sources.`);
              }
              throw new Error(formatTwitterError(error, 'searching tweets'));
          }
          throw error;
      }
  };

• src/tools.ts:79-102 (schema)

  MCP tool schema definition for searchTweets, including description and inputSchema used for tool listing and validation.

  searchTweets: {
      description: 'Search for tweets using a query string',
      inputSchema: {
          type: 'object',
          properties: {
              query: {
                  type: 'string',
                  description: 'The search query'
              },
              maxResults: {
                  type: 'number',
                  description: 'Maximum number of results to return'
              },
              tweetFields: {
                  type: 'array',
                  items: {
                      type: 'string'
                  },
                  description: 'Fields to include in the tweet objects'
              }
          },
          required: ['query']
      }
  },

• src/index.ts:313-316 (registration)

  Registration in the main server request handler: dispatches CallToolRequest for 'searchTweets' to the handleSearchTweets function.

  case 'searchTweets': {
      const { query, maxResults } = request.params.arguments as { query: string; maxResults?: number };
      response = await handleSearchTweets(client, { query, maxResults });
      break;

• src/types.ts:12-17 (schema)

  TypeScript interface defining the input arguments for searchTweets handler.

  export interface SearchTweetsArgs {
      query: string;
      since?: string;
      until?: string;
      tweetFields?: string[];
  }

• src/index.ts:48-50 (registration)

  Import of the handleSearchTweets handler function into the main index.ts for use in tool dispatching.

      handleSearchTweets,
      handleHashtagAnalytics
  } from './handlers/search.handlers.js';