MCP tools for tweet search, followers & X actions

interface OperationInfo {
  operationId: string;
  summary?: string;
  description?: string;
  tags?: string[];
  parameters?: unknown[];
  requestBody?: unknown;
  responses?: Record<string, unknown>;
}

interface PathItem {
  get?: OperationInfo;
  post?: OperationInfo;
  put?: OperationInfo;
  patch?: OperationInfo;
  delete?: OperationInfo;
}

declare const spec: { paths: Record<string, PathItem> };

async () => Object.entries(spec.paths).flatMap(([path, methods]) =>
  Object.entries(methods).flatMap(([method, operation]) =>
    operation?.summary?.toLowerCase().includes('tweet')
      ? [{ method: method.toUpperCase(), path, ...operation }]
      : []
  )
)

declare const xquik: {
  request<T = unknown>(path: string, options?: {
    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    body?: unknown;
    query?: Record<string, string | number | boolean | undefined>;
  }): Promise<T>;
};

async () => {
  // Step 1: Get editorial rules, questions, and Radar recommendations.
  const compose = await xquik.request('/api/v1/compose', {
    method: 'POST',
    body: { step: 'compose', topic: 'AI agents' }
  });
  return compose;
}

async () => {
  // When a user shares tweet screenshots, extract the texts and save as a style.
  // This lets free users clone any writing voice without a subscription.
  return xquik.request('/api/v1/styles/elonmusk', {
    method: 'PUT',
    body: {
      label: 'Elon Musk style',
      tweets: [
        { text: 'The most entertaining outcome is the most likely' },
        { text: 'Mars, here we come!!' }
      ]
    }
  });
  // Then compose with: POST /api/v1/compose { step: 'compose', topic: '...', styleUsername: 'elonmusk' }
}

async () => {
  return xquik.request('/api/v1/radar');
}

async () => {
  const [radar, styles] = await Promise.all([
    xquik.request('/api/v1/radar'),
    xquik.request('/api/v1/styles'),
  ]);
  return { radar, styles };
}

async () => {
  // Returns cached style if available (free)
  // Auto-refreshes from X if cache older than 7 days (credits required)
  return xquik.request('/api/v1/styles', {
    method: 'POST',
    body: { username: 'elonmusk' }
  });
}

async () => {
  const target = 100;
  const query = 'from:username giveaway';
  const seenIds = new Set();
  const seenCursors = new Set();
  const sampleTweets = [];
  let cursor;
  let hasMore = true;
  let nextCursor = '';
  let stopReason = 'page_cap';

  for (let pageNumber = 0; pageNumber < 10 && seenIds.size < target && hasMore; pageNumber += 1) {
    const page = await xquik.request('/api/v1/x/tweets/search', {
      query: {
        q: query,
        limit: String(Math.min(200, target - seenIds.size)),
        ...(cursor ? { cursor } : {})
      }
    });

    for (const tweet of page.tweets) {
      if (seenIds.has(tweet.id) || seenIds.size >= target) continue;
      seenIds.add(tweet.id);
      if (sampleTweets.length < 20) {
        sampleTweets.push({
          tweet_id: tweet.id,
          text_excerpt: tweet.text?.slice(0, 120) ?? null,
          author_id: tweet.author?.id ?? null,
          author_username: tweet.author?.username ?? null,
          created: tweet['created'] ?? null,
          like_count: tweet.like_count ?? null,
          view_count: tweet.view_count ?? null
        });
      }
    }

    hasMore = Boolean(page.has_more);
    nextCursor = page.next_cursor ?? '';
    if (!hasMore) {
      stopReason = 'exhausted';
      break;
    }
    if (!nextCursor || nextCursor === cursor || seenCursors.has(nextCursor)) {
      stopReason = 'cursor_stalled';
      break;
    }
    seenCursors.add(nextCursor);
    cursor = nextCursor;
  }

  return {
    source: 'xquik_mcp',
    job: 'tweet_search',
    query,
    rows_seen: seenIds.size,
    sample_tweets: sampleTweets,
    has_more: hasMore,
    next_cursor: nextCursor,
    stop_reason: seenIds.size >= target ? 'requested_total' : stopReason
  };
}

async () => {
  const target = 100;
  const sourceUser = 'username';
  const seenIds = new Set();
  const seenCursors = new Set();
  const sampleProfiles = [];
  let verifiedCount = 0;
  let cursor;
  let hasMore = true;
  let nextCursor = '';
  let stopReason = 'page_cap';

  for (let pageNumber = 0; pageNumber < 10 && seenIds.size < target && hasMore; pageNumber += 1) {
    const page = await xquik.request(`/api/v1/x/users/${sourceUser}/followers`, {
      query: {
        pageSize: String(Math.max(20, Math.min(200, target - seenIds.size))),
        ...(cursor ? { cursor } : {})
      }
    });

    for (const user of page.users) {
      if (seenIds.has(user.id) || seenIds.size >= target) continue;
      seenIds.add(user.id);
      if (user.verified === true) verifiedCount += 1;
      if (sampleProfiles.length < 25) {
        sampleProfiles.push({
          user_id: user.id,
          username: user.username,
          name: user.name ?? null,
          followers: user.followers ?? null,
          verified: user.verified ?? null,
          profile_picture: user.profile_picture ?? null
        });
      }
    }

    hasMore = Boolean(page.has_more);
    nextCursor = page.next_cursor ?? '';
    if (!hasMore) {
      stopReason = 'exhausted';
      break;
    }
    if (!nextCursor || nextCursor === cursor || seenCursors.has(nextCursor)) {
      stopReason = 'cursor_stalled';
      break;
    }
    seenCursors.add(nextCursor);
    cursor = nextCursor;
  }

  return {
    source: 'xquik_mcp',
    job: 'follower_export',
    source_user: sourceUser,
    rows_seen: seenIds.size,
    verified_count: verifiedCount,
    sample_profiles: sampleProfiles,
    has_more: hasMore,
    next_cursor: nextCursor,
    stop_reason: seenIds.size >= target ? 'requested_total' : stopReason
  };
}

async () => {
  const body = {
    toolType: 'reply_extractor',
    targetTweetId: '1893704267862470862',
    resultsLimit: 500
  };

  const extraction = await xquik.request('/api/v1/extractions', {
    method: 'POST',
    body
  });

  return {
    source: 'xquik_mcp',
    job: 'reply_extraction',
    extraction_id: extraction.id,
    status: extraction.status,
    target_tweet_id: body.targetTweetId,
    results_limit: body.resultsLimit,
    poll: `/api/v1/extractions/${extraction.id}`,
    export_csv: `/api/v1/extractions/${extraction.id}/export?format=csv`,
    export_json: `/api/v1/extractions/${extraction.id}/export?format=json`,
    export_xlsx: `/api/v1/extractions/${extraction.id}/export?format=xlsx`
  };
}

async () => {
  const body = {
    account: 'myxhandle',
    text: 'Launch media is ready',
    reply_to_tweet_id: '1893456789012345678',
    media: ['https://example.com/product-demo.mp4']
  };

  const result = await xquik.request('/api/v1/x/tweets', {
    method: 'POST',
    body
  });

  return {
    source: 'xquik_mcp',
    job: 'tweet_write',
    status: result.status,
    terminal: result.terminal,
    safe_to_retry: result.safe_to_retry,
    write_action_id: result.id,
    request_hash: result.request.hash,
    tweet_id: result.result?.id ?? result.tweet_id ?? null,
    poll: result.terminal ? null : result.status_url,
    account: body.account,
    reply_to_tweet_id: body.reply_to_tweet_id,
    media: body.media,
    charged: result.billing.charged,
    charged_credits: result.billing.charged_credits
  };
}

async () => {
  const account = 'myxhandle';
  const user_id = '44196397';
  const source_url = 'https://example.com/image.png';

  const media = await xquik.request('/api/v1/x/media', {
    method: 'POST',
    body: {
      account,
      url: source_url
    }
  });

  const dm = await xquik.request(`/api/v1/x/dm/${user_id}`, {
    method: 'POST',
    body: {
      account,
      text: 'Here is the asset',
      media_ids: [media.media_id]
    }
  });

  return {
    source: 'xquik_mcp',
    job: 'dm_media',
    status: 'sent',
    user_id,
    account,
    source_url,
    media_id: media.media_id,
    media_url: media.media_url,
    message_id: dm.message_id
  };
}

async () => {
  const tweet_input = '1234567890';
  const download = await xquik.request('/api/v1/x/media/download', {
    method: 'POST',
    body: { tweetInput: tweet_input }
  });

  return {
    source: 'xquik_mcp',
    job: 'media_download',
    mode: 'single',
    tweet_input,
    tweet_id: download.tweet_id,
    gallery_url: download.gallery_url,
    cache_hit: download.cache_hit,
    note: 'Store gallery_url as the saved media gallery. It is not an uploaded media_id for DMs.'
  };
}

async () => {
  const query = 'from:berktavsan has:videos';
  const search = await xquik.request('/api/v1/x/tweets/search', {
    query: { q: query }
  });
  if (!search.tweets?.length) {
    return {
      source: 'xquik_mcp',
      job: 'bulk_media_download',
      status: 'empty',
      query
    };
  }

  const tweetIds = search.tweets.map(t => t.id).slice(0, 50);
  const download = await xquik.request('/api/v1/x/media/download', {
    method: 'POST',
    body: { tweetIds }
  });

  return {
    source: 'xquik_mcp',
    job: 'bulk_media_download',
    status: 'ready',
    query,
    tweet_ids: tweetIds,
    gallery_url: download.gallery_url,
    total_tweets: download.total_tweets,
    total_media: download.total_media
  };
}

async () => {
  const monitor = await xquik.request('/api/v1/monitors', {
    method: 'POST',
    body: { username: 'elonmusk', eventTypes: ['tweet.new', 'tweet.reply'] }
  });
  const webhook = await xquik.request('/api/v1/webhooks', {
    method: 'POST',
    body: { url: 'https://example.com/hook', eventTypes: ['tweet.new', 'tweet.reply'] }
  });
  const test = await xquik.request(`/api/v1/webhooks/${webhook.id}/test`, {
    method: 'POST'
  });
  return {
    monitor_id: monitor.id,
    event_types: monitor.event_types,
    next_billing_at: monitor.next_billing_at,
    webhook_id: webhook.id,
    webhook_url: webhook.url,
    save_secret_once: 'Store webhook.secret for X-Xquik-Signature verification; do not print it in logs.',
    idempotency_keys: ['deliveryId', 'streamEventId'],
    delivery_status: `/api/v1/webhooks/${webhook.id}/deliveries`,
    test
  };
}

async () => {
  const monitor_id = 'mon_123';
  const event_type = 'tweet.new';
  const page = await xquik.request('/api/v1/events', {
    query: { monitorId: monitor_id, eventType: event_type }
  });

  return {
    source: 'xquik_mcp',
    job: 'monitor_event_poll',
    monitor_id,
    event_type,
    rows: page.events.map(event => ({
      event_id: event.id,
      type: event.type,
      username: event.username ?? null,
      query: event.query ?? null,
      monitor_id: event.monitor_id,
      monitor_type: event.monitor_type,
      occurred_at: event.occurred_at,
      data: event.data
    })),
    has_more: page.has_more,
    next_cursor: page.next_cursor,
    next_query: page.next_cursor
      ? { monitorId: monitor_id, eventType: event_type, cursor: page.next_cursor }
      : null
  };
}

async () => {
  const body = {
    toolType: 'tweet_search_extractor',
    searchQuery: 'launch announcement',
    resultsLimit: 500
  };

  // Add optional filters only when the user requests them.

  const job = await xquik.request('/api/v1/extractions', {
    method: 'POST',
    body
  });

  return {
    source: 'xquik_mcp',
    job: 'tweet_search_extraction',
    extraction_id: job.id,
    tool_type: job.tool_type,
    status: job.status,
    query: body.searchQuery,
    results_limit: body.resultsLimit,
    poll: `/api/v1/extractions/${job.id}`,
    export_after_complete: `/api/v1/extractions/${job.id}/export?format=json`
  };
}

async () => {
  const page = await xquik.request('/api/v1/x/tweets/search', {
    query: { q: 'from:username giveaway', limit: '50' }
  });

  return {
    source: 'xquik_mcp',
    job: 'tweet_search',
    query: 'from:username giveaway',
    rows: page.tweets.map(tweet => ({
      tweet_id: tweet.id,
      text: tweet.text,
      author: tweet.author,
      created: tweet['created'],
      url: tweet.url
    })),
    has_more: page.has_more,
    next_cursor: page.next_cursor
  };
}

async () => {
  const page = await xquik.request('/api/v1/x/tweets', {
    query: { ids: '1893456789012345678,1893456789012345679' }
  });
  return {
    tweets: page.tweets.map(tweet => ({
      tweet_id: tweet.id,
      text: tweet.text,
      author_username: tweet.author?.username ?? null
    }))
  };
}

async () => {
  return xquik.request('/api/v1/subscribe', { method: 'POST' });
}