Twitter MCP Server

Instructions

Implementation Reference

• src/handlers/engagement.handlers.ts:105-135 (handler)

  The core handler function implementing the getRetweets tool. It uses the Twitter API v2 tweetRetweetedBy endpoint to fetch users who retweeted a given tweet ID, with optional pagination and user fields.

  export const handleGetRetweets: TwitterHandler<GetRetweetsArgs> = async (
      client: TwitterClient | null,
      { tweetId, maxResults = 100, userFields }: GetRetweetsArgs
  ): Promise<HandlerResponse> => {
      if (!client) {
          return createMissingTwitterApiKeyResponse('getRetweets');
      }
      
      try {
          const retweets = await client.v2.tweetRetweetedBy(tweetId, {
              max_results: maxResults,
              'user.fields': userFields?.join(',') || 'description,profile_image_url,public_metrics,verified'
          });
  
          if (!retweets.data || !Array.isArray(retweets.data) || retweets.data.length === 0) {
              return createResponse(`No retweets found for tweet: ${tweetId}`);
          }
  
          const responseData = {
              retweetedBy: retweets.data,
              meta: retweets.meta
          };
  
          return createResponse(`Users who retweeted: ${JSON.stringify(responseData, null, 2)}`);
      } catch (error) {
          if (error instanceof Error) {
              throw new Error(formatTwitterError(error, 'getting retweets'));
          }
          throw error;
      }
  };

• src/tools.ts:229-252 (schema)

  MCP tool schema definition for getRetweets, including input validation schema with required tweetId and optional maxResults and userFields.

  getRetweets: {
      description: 'Get a list of retweets of a tweet',
      inputSchema: {
          type: 'object',
          properties: {
              tweetId: { type: 'string', description: 'The ID of the tweet to get retweets for' },
              maxResults: { 
                  type: 'number', 
                  description: 'The maximum number of results to return (default: 100, max: 100)',
                  minimum: 1,
                  maximum: 100
              },
              userFields: { 
                  type: 'array', 
                  items: { 
                      type: 'string',
                      enum: ['description', 'profile_image_url', 'public_metrics', 'verified']
                  },
                  description: 'Additional user fields to include in the response'
              },
          },
          required: ['tweetId'],
      },
  },

• src/index.ts:202-205 (registration)

  Tool registration and dispatch in the main MCP server request handler switch statement.

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

• src/types.ts:63-67 (schema)

  TypeScript interface defining the input arguments for the getRetweets handler.

  export interface GetRetweetsArgs {
      tweetId: string;
      maxResults?: number;
      userFields?: string[];
  }

• src/types.ts:309-332 (helper)

  Runtime assertion function to validate getRetweets arguments.

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