Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/search.handlers.ts:19-56 (handler)

  The primary handler function that executes the advanced tweet search logic. It constructs a search query with optional filters for retweets and language, calls the socialDataClient to perform the search, and formats the tweet results.

  export const handleAdvancedTweetSearch: SocialDataHandler<AdvancedSearchArgs> = async (
      _client: any,
      { query, maxResults = 10, startTime, endTime, includeRetweets = true, language }: AdvancedSearchArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('Advanced Tweet Search');
          }
          
          // Build advanced query with operators
          let searchQuery = query;
          if (!includeRetweets) {
              searchQuery += ' -is:retweet';
          }
          if (language) {
              searchQuery += ` lang:${language}`;
          }
          
          const result = await socialClient.searchTweets({
              query: searchQuery,
              maxResults,
              startTime,
              endTime
          });
  
          if (!result.data || result.data.length === 0) {
              return createSocialDataResponse(`No tweets found for advanced search: ${query}`);
          }
  
          return createSocialDataResponse(
              formatTweetList(result.data, `Advanced Search Results for "${query}" (${result.data.length} tweets)`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'advanced tweet search'));
      }
  };

• src/socialdata-tools.ts:5-39 (schema)

  Defines the tool description and input schema (including parameters like query, maxResults, time ranges, retweet filter, and language) for advancedTweetSearch.

  advancedTweetSearch: {
      description: 'Advanced tweet search with operators and filters, bypassing API tier restrictions',
      inputSchema: {
          type: 'object',
          properties: {
              query: {
                  type: 'string',
                  description: 'Search query with advanced operators (e.g., "AI OR ML -crypto lang:en")'
              },
              maxResults: {
                  type: 'number',
                  description: 'Maximum number of results to return (default: 10, max: 100)',
                  minimum: 1,
                  maximum: 100
              },
              startTime: {
                  type: 'string',
                  description: 'Start time for search in ISO 8601 format (e.g., "2024-01-01T00:00:00Z")'
              },
              endTime: {
                  type: 'string',
                  description: 'End time for search in ISO 8601 format'
              },
              includeRetweets: {
                  type: 'boolean',
                  description: 'Whether to include retweets in results (default: true)'
              },
              language: {
                  type: 'string',
                  description: 'Language code to filter tweets (e.g., "en", "es", "fr")'
              }
          },
          required: ['query']
      }
  },

• src/tools.ts:736-737 (registration)

  Registers the advancedTweetSearch tool (and other SocialData tools) into the main TOOLS object by spreading SOCIALDATA_TOOLS. This TOOLS export is used by the MCP server for tool discovery via ListToolsRequestHandler.

  // SocialData.tools enhanced research and analytics
  ...SOCIALDATA_TOOLS

• src/index.ts:426-429 (registration)

  Dispatches calls to the advancedTweetSearch handler in the main CallToolRequestHandler switch statement in the MCP server.

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