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>;
  components: { schemas: Record<string, unknown> };
};

async () => {
  const path = "/api/v1/x/tweets/search";
  const { operationId, summary, parameters } = spec.paths[path].get;
  return { path, method: "GET", operationId, summary, parameters };
};

async () => spec.components.schemas.PaginatedTweets.properties;

interface XquikRequest {
  path: string;
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  query?: Record<string, string | number | boolean | undefined>;
  body?: unknown;
}

interface XquikResponse<T> {
  success: true;
  status: number;
  result: T;
  errors: [];
  messages: [];
}

declare const xquik: {
  result: unknown;
  request<T = unknown>(options: XquikRequest): Promise<XquikResponse<T>>;
};

{
  "code": "async () => xquik.result.tweets.slice(0, 10).map(({ id }) => id)",
  "result_id": "<result_id from the output error>"
}

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 { result: page } = await xquik.request({
      path: "/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 { result: page } = await xquik.request({
      path: `/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 { result: extraction } = await xquik.request({
    path: "/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({
    path: "/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 { result: media } = await xquik.request({
    path: "/api/v1/x/media",
    method: "POST",
    body: {
      account,
      url: source_url,
    },
  });

  const { result: dm } = await xquik.request({
    path: `/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 { result: download } = await xquik.request({
    path: "/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 { result: search } = await xquik.request({
    path: "/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 { result: download } = await xquik.request({
    path: "/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 { result: monitor } = await xquik.request({
    path: "/api/v1/monitors",
    method: "POST",
    body: { username: "elonmusk", eventTypes: ["tweet.new", "tweet.reply"] },
  });
  const { result: webhook } = await xquik.request({
    path: "/api/v1/webhooks",
    method: "POST",
    body: { url: "https://example.com/hook", eventTypes: ["tweet.new", "tweet.reply"] },
  });
  const { result: test } = await xquik.request({
    path: `/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 { result: page } = await xquik.request({
    path: "/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 { result: job } = await xquik.request({
    path: "/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 { result: page } = await xquik.request({
    path: "/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 { result: page } = await xquik.request({
    path: "/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({
    path: "/api/v1/subscribe",
    method: "POST",
  });
};