Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/socialdata/network.handlers.ts:20-89 (handler)

  The main handler function that implements the findMutualConnections tool logic. It searches for direct mentions between two users and users who mention both, computing connection strength and mutual interactions using Twitter search API.

  export const handleFindMutualConnections: SocialDataHandler<CommonFollowersArgs> = async (
      _client: any,
      { user1, user2, maxResults = 20 }: CommonFollowersArgs
  ) => {
      try {
          const socialClient = getSocialDataClient();
          
          if (!socialClient) {
              return createMissingApiKeyResponse('Mutual Connections Analysis');
          }
          
          // Get interactions between the users by searching for mentions
          const mutualMentionsQuery = `(from:${user1} @${user2}) OR (from:${user2} @${user1})`;
          const mentionsResult = await socialClient.searchTweets({
              query: mutualMentionsQuery,
              maxResults: 50
          });
  
          // Get users who mention both
          const bothMentionedQuery = `@${user1} @${user2}`;
          const bothMentionedResult = await socialClient.searchTweets({
              query: bothMentionedQuery,
              maxResults: maxResults
          });
  
          // Extract unique users from interactions
          const interactingUsers = new Set();
          [...(mentionsResult.data || []), ...(bothMentionedResult.data || [])].forEach((tweet: any) => {
              if (tweet.user?.screen_name && 
                  tweet.user.screen_name !== user1 && 
                  tweet.user.screen_name !== user2) {
                  interactingUsers.add(tweet.user.screen_name);
              }
          });
  
          const mutualConnections = {
              user1,
              user2,
              direct_interactions: {
                  count: mentionsResult.data?.length || 0,
                  recent_mentions: mentionsResult.data?.slice(0, 5).map((tweet: any) => ({
                      from: tweet.user?.screen_name,
                      text: tweet.text?.substring(0, 140),
                      date: tweet.tweet_created_at
                  })) || []
              },
              mutual_interactions: {
                  users_mentioning_both: Array.from(interactingUsers).slice(0, maxResults),
                  count: interactingUsers.size,
                  sample_tweets: bothMentionedResult.data?.slice(0, 3).map((tweet: any) => ({
                      author: tweet.user?.screen_name,
                      text: tweet.text?.substring(0, 140),
                      date: tweet.tweet_created_at
                  })) || []
              },
              connection_strength: {
                  direct_mentions: mentionsResult.data?.length || 0,
                  mutual_mention_network: interactingUsers.size,
                  estimated_relationship: interactingUsers.size > 5 ? 'Strong' : 
                                         interactingUsers.size > 1 ? 'Moderate' : 'Weak'
              }
          };
  
          return createSocialDataResponse(
              formatAnalytics(mutualConnections, `Mutual Connections: @${user1} ↔ @${user2}`)
          );
      } catch (error) {
          throw new Error(formatSocialDataError(error as Error, 'mutual connections analysis'));
      }
  };

• src/socialdata-tools.ts:241-263 (schema)

  Tool schema definition including description and input validation schema for findMutualConnections.

  findMutualConnections: {
      description: 'Find mutual connections and interactions between two users',
      inputSchema: {
          type: 'object',
          properties: {
              user1: {
                  type: 'string',
                  description: 'First username (without @)'
              },
              user2: {
                  type: 'string',
                  description: 'Second username (without @)'
              },
              maxResults: {
                  type: 'number',
                  description: 'Maximum results to return (default: 20)',
                  minimum: 5,
                  maximum: 50
              }
          },
          required: ['user1', 'user2']
      }
  },

• src/index.ts:473-476 (registration)

  Registration in the main tool dispatcher switch statement, mapping the tool name to its handler function.

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