xbird-mcp 0.1.0

package/src/commands/tweet.ts

@@ -0,0 +1,128 @@
+import type { Command } from "commander";
+import { createContext } from "../cli/context.ts";
+import { XClient } from "../lib/client-full.ts";
+import { output, error } from "../cli/output.ts";
+import { extractTweetId } from "../lib/utils.ts";
+import { dim, emoji, green } from "../formatters/common.ts";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+
+const MIME_TYPES: Record<string, string> = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+};
+
+const VIDEO_EXTS = new Set([".mp4", ".mov"]);
+
+async function uploadMediaFile(
+  client: InstanceType<typeof XClient>,
+  filePath: string,
+  alt?: string
+): Promise<string> {
+  const ext = extname(filePath).toLowerCase();
+  const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
+  const data = readFileSync(filePath);
+  const result = await client.uploadMedia({ data: new Uint8Array(data), mimeType, alt });
+  if (!result.success || !result.mediaId) {
+    throw new Error(result.error ?? "Failed to upload media");
+  }
+  return result.mediaId;
+}
+
+function validateMediaFiles(files: string[]): void {
+  const hasVideo = files.some(f => VIDEO_EXTS.has(extname(f).toLowerCase()));
+  if (hasVideo && files.length > 1) {
+    throw new Error("Only 1 video file is allowed. Cannot mix video with other media.");
+  }
+  if (files.length > 4) {
+    throw new Error("Maximum 4 image files allowed.");
+  }
+}
+
+async function uploadAllMedia(
+  client: InstanceType<typeof XClient>,
+  files: string[],
+  altTexts?: string[]
+): Promise<string[]> {
+  validateMediaFiles(files);
+  const mediaIds: string[] = [];
+  for (let i = 0; i < files.length; i++) {
+    const mediaId = await uploadMediaFile(client, files[i]!, altTexts?.[i]);
+    mediaIds.push(mediaId);
+  }
+  return mediaIds;
+}
+
+export function registerTweet(program: Command): void {
+  program
+    .command("tweet <text>")
+    .description("Post a new tweet")
+    .option("--media <files...>", "Attach media files (images or video)")
+    .option("--alt <texts...>", "Alt text for each media file")
+    .action(async function (this: Command, text: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+
+      let mediaIds: string[] | undefined;
+      if (opts.media) {
+        mediaIds = await uploadAllMedia(client, opts.media, opts.alt);
+      }
+
+      const result = await client.tweet(text, mediaIds);
+      if (!result.success) error(result.error ?? "Failed to post tweet");
+      if (ctx.format === "json" || ctx.format === "json-full") {
+        output({ tweetId: result.tweetId, url: `https://x.com/i/status/${result.tweetId}` }, ctx.format);
+      } else {
+        console.log(`${green(emoji("✓"))} Tweet posted: ${dim(`https://x.com/i/status/${result.tweetId}`)}`);
+      }
+    });
+
+  program
+    .command("reply <id> <text>")
+    .description("Reply to a tweet")
+    .option("--media <files...>", "Attach media files (images or video)")
+    .option("--alt <texts...>", "Alt text for each media file")
+    .action(async function (this: Command, id: string, text: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const tweetId = extractTweetId(id);
+
+      let mediaIds: string[] | undefined;
+      if (opts.media) {
+        mediaIds = await uploadAllMedia(client, opts.media, opts.alt);
+      }
+
+      const result = await client.reply(text, tweetId, mediaIds);
+      if (!result.success) error(result.error ?? "Failed to post reply");
+      if (ctx.format === "json" || ctx.format === "json-full") {
+        output({ tweetId: result.tweetId, url: `https://x.com/i/status/${result.tweetId}` }, ctx.format);
+      } else {
+        console.log(`${green(emoji("✓"))} Reply posted: ${dim(`https://x.com/i/status/${result.tweetId}`)}`);
+      }
+    });
+
+  program
+    .command("thread <texts...>")
+    .description("Post a thread (multiple tweets)")
+    .action(async function (this: Command, texts: string[]) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const result = await client.thread(texts);
+      if (!result.success) error(result.error ?? "Failed to post thread");
+      if (ctx.format === "json") {
+        output({ tweetIds: result.tweetIds, urls: result.tweetIds?.map(id => `https://x.com/i/status/${id}`) }, ctx.format);
+      } else {
+        console.log(`${green(emoji("✓"))} Thread posted (${result.tweetIds?.length} tweets)`);
+        for (const tid of result.tweetIds ?? []) {
+          console.log(`  ${dim(`https://x.com/i/status/${tid}`)}`);
+        }
+      }
+    });
+}

package/src/commands/user-tweets.ts

@@ -0,0 +1,73 @@
+import type { Command } from "commander";
+import { createContext } from "../cli/context.ts";
+import { XClient } from "../lib/client-full.ts";
+import { output, error } from "../cli/output.ts";
+import { normalizeHandle } from "../lib/utils.ts";
+import { formatTweet } from "../formatters/tweet.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+
+export function registerUserTweets(program: Command): void {
+  program
+    .command("user-tweets <handle>")
+    .description("Show tweets from a user")
+    .option("-n, --count <number>", "Number of tweets", "20")
+    .option("--cursor <cursor>", "Pagination cursor")
+    .option("--all", "Fetch all pages")
+    .option("--max-pages <n>", "Max pages to fetch")
+    .option("--delay <ms>", "Delay between pages in ms")
+    .action(async function (this: Command, handle: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+      const screenName = normalizeHandle(handle);
+
+      // Resolve user ID
+      const userResult = await client.getUserByHandle(screenName);
+      if (!userResult.success || !userResult.user) {
+        error(userResult.error ?? `User @${screenName} not found`);
+      }
+
+      if (opts.all || opts.maxPages) {
+        const result = await autoPaginate(
+          async (cursor?) => {
+            const r = await client.getUserTweets(userResult.user!.id, count, cursor);
+            return { items: r.tweets, cursor: r.cursor };
+          },
+          {
+            all: opts.all,
+            maxPages: opts.maxPages ? parseInt(opts.maxPages, 10) : undefined,
+            delay: opts.delay ? parseInt(opts.delay, 10) : undefined,
+          }
+        );
+
+        if (ctx.format === "json" || ctx.format === "json-full") {
+          output({ tweets: result.items, cursor: result.cursor }, "json");
+        } else {
+          for (const tweet of result.items) {
+            console.log(formatTweet(tweet));
+            console.log("---");
+          }
+          if (result.items.length === 0) console.log("No tweets found.");
+        }
+      } else {
+        const result = await client.getUserTweets(
+          userResult.user!.id,
+          count,
+          opts.cursor
+        );
+        if (!result.success) error(result.error ?? "Failed to load user tweets");
+
+        if (ctx.format === "json") {
+          output({ tweets: result.tweets, cursor: result.cursor }, ctx.format);
+        } else {
+          for (const tweet of result.tweets) {
+            console.log(formatTweet(tweet));
+            console.log("---");
+          }
+          if (result.tweets.length === 0) console.log("No tweets found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}

package/src/commands/user.ts

@@ -0,0 +1,20 @@
+import type { Command } from "commander";
+import { createContext } from "../cli/context.ts";
+import { XClient } from "../lib/client-full.ts";
+import { output, error } from "../cli/output.ts";
+import { normalizeHandle } from "../lib/utils.ts";
+import { formatUser } from "../formatters/user.ts";
+
+export function registerUser(program: Command): void {
+  program
+    .command("user <handle>")
+    .description("Show user profile info")
+    .action(async function (this: Command, handle: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const normalized = normalizeHandle(handle);
+      const result = await client.getUserByHandle(normalized);
+      if (!result.success || !result.user) error(result.error ?? "User not found");
+      output(result.user, ctx.format, (data) => formatUser(data as any));
+    });
+}

package/src/commands/whoami.ts

@@ -0,0 +1,26 @@
+import type { Command } from "commander";
+import { createContext } from "../cli/context.ts";
+import { XClient } from "../lib/client-full.ts";
+import { output, error } from "../cli/output.ts";
+import { formatUser } from "../formatters/user.ts";
+import { bold, dim } from "../formatters/common.ts";
+
+export function registerWhoami(program: Command): void {
+  program
+    .command("whoami")
+    .description("Show the authenticated account")
+    .action(async function (this: Command) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const result = await client.getCurrentUser();
+      if (!result.success || !result.user) {
+        error(result.error ?? "Failed to get current user");
+      }
+      const user = result.user!;
+      if (ctx.format === "json") {
+        output(user, ctx.format);
+      } else {
+        console.log(`${bold(user.name)} ${dim("@" + user.screenName)} ${dim("(id: " + user.id + ")")}`);
+      }
+    });
+}

package/src/formatters/common.ts

@@ -0,0 +1,49 @@
+import kleur from "kleur";
+
+let emojiEnabled = true;
+
+export function setEmojiEnabled(enabled: boolean): void {
+  emojiEnabled = enabled;
+}
+
+const EMOJI_MAP: Record<string, string> = {
+  "❤": "[L]",
+  "🔁": "[RT]",
+  "💬": "[R]",
+  "👁": "[V]",
+  "✓": "[v]",
+  "📍": "[loc]",
+};
+
+export function emoji(char: string, fallback?: string): string {
+  if (emojiEnabled) return char;
+  return fallback ?? EMOJI_MAP[char] ?? char;
+}
+
+export function dim(text: string): string {
+  return kleur.dim(text);
+}
+
+export function bold(text: string): string {
+  return kleur.bold(text);
+}
+
+export function cyan(text: string): string {
+  return kleur.cyan(text);
+}
+
+export function green(text: string): string {
+  return kleur.green(text);
+}
+
+export function red(text: string): string {
+  return kleur.red(text);
+}
+
+export function yellow(text: string): string {
+  return kleur.yellow(text);
+}
+
+export function gray(text: string): string {
+  return kleur.gray(text);
+}

package/src/formatters/list.ts

@@ -0,0 +1,22 @@
+import type { TwitterList } from "../lib/types.ts";
+import { formatCount } from "../lib/utils.ts";
+import { bold, dim } from "./common.ts";
+
+export function formatList(list: TwitterList): string {
+  const header = `${bold(list.name)} ${dim(list.isPrivate ? "(private)" : "(public)")}`;
+  const desc = list.description || dim("No description");
+  const stats = dim(
+    `Members: ${formatCount(list.memberCount)}  Subscribers: ${formatCount(list.subscriberCount)}`
+  );
+  const owner = list.owner
+    ? dim(`Owner: @${list.owner.screenName}`)
+    : "";
+  const parts = [header, desc, stats];
+  if (owner) parts.push(owner);
+  return parts.join("\n");
+}
+
+export function formatListCompact(list: TwitterList): string {
+  const privacy = list.isPrivate ? " (private)" : "";
+  return `${bold(list.name)}${privacy} — ${formatCount(list.memberCount)} members`;
+}

package/src/formatters/news.ts

@@ -0,0 +1,23 @@
+import type { NewsItem } from "../lib/types.ts";
+import { formatCount } from "../lib/utils.ts";
+import { bold, dim } from "./common.ts";
+
+export function formatNewsItem(item: NewsItem): string {
+  const headline = bold(item.headline);
+  const category = dim(item.category);
+  const posts = item.postCount != null
+    ? dim(`${formatCount(item.postCount)} posts`)
+    : "";
+  const desc = item.description ? dim(item.description) : "";
+  const parts = [headline, category];
+  if (posts) parts.push(posts);
+  if (desc && desc !== posts) parts.push(desc);
+  return parts.join("\n");
+}
+
+export function formatNewsItemCompact(item: NewsItem): string {
+  const posts = item.postCount != null
+    ? ` (${formatCount(item.postCount)} posts)`
+    : "";
+  return `${bold(item.headline)} — ${item.category}${posts}`;
+}

package/src/formatters/tweet.ts

@@ -0,0 +1,38 @@
+import type { Tweet } from "../lib/types.ts";
+import { formatCount, formatDate, tweetUrl } from "../lib/utils.ts";
+import { bold, cyan, dim, emoji, gray } from "./common.ts";
+
+let defaultQuoteDepth = 1;
+
+export function setQuoteDepth(depth: number): void {
+  defaultQuoteDepth = Math.max(0, Math.min(3, depth));
+}
+
+export function formatTweet(tweet: Tweet, depth?: number, current = 0): string {
+  const header = `${bold(tweet.authorName)} ${dim("@" + tweet.authorHandle)} · ${dim(formatDate(tweet.createdAt))}`;
+  const text = tweet.text;
+  const stats = dim(
+    `${emoji("❤")} ${formatCount(tweet.likeCount)}  ${emoji("🔁")} ${formatCount(tweet.retweetCount)}  ${emoji("💬")} ${formatCount(tweet.replyCount)}  ${emoji("👁")} ${formatCount(tweet.viewCount)}`
+  );
+  const url = dim(tweetUrl(tweet.authorHandle, tweet.id));
+  let result = `${header}\n${text}\n${stats}\n${url}`;
+
+  const d = depth ?? defaultQuoteDepth;
+  if (tweet.quotedTweet && current < d) {
+    const quoted = formatTweet(tweet.quotedTweet, d, current + 1);
+    const indented = quoted.split("\n").map(l => `  ${dim("│")} ${l}`).join("\n");
+    result += "\n" + indented;
+  }
+
+  return result;
+}
+
+export function formatTweetCompact(tweet: Tweet): string {
+  const prefix = dim(`@${tweet.authorHandle}`);
+  const text = tweet.text.replace(/\n/g, " ").slice(0, 100);
+  return `${prefix}: ${text}`;
+}
+
+export function formatTweetPlain(tweet: Tweet): string {
+  return `@${tweet.authorHandle}: ${tweet.text}`;
+}

package/src/formatters/user.ts

@@ -0,0 +1,20 @@
+import type { TwitterUser } from "../lib/types.ts";
+import { formatCount, profileUrl } from "../lib/utils.ts";
+import { bold, cyan, dim, emoji, gray } from "./common.ts";
+
+export function formatUser(user: TwitterUser): string {
+  const header = `${bold(user.name)} ${dim("@" + user.screenName)}`;
+  const verified = user.isBlueVerified ? " " + emoji("✓") : "";
+  const bio = user.description || dim("No bio");
+  const stats = dim(
+    `Followers: ${formatCount(user.followersCount)}  Following: ${formatCount(user.followingCount)}  Tweets: ${formatCount(user.tweetCount)}`
+  );
+  const url = dim(profileUrl(user.screenName));
+  const parts = [`${header}${verified}`, bio, stats, url];
+  if (user.location) parts.splice(2, 0, dim(`${emoji("📍")} ${user.location}`));
+  return parts.join("\n");
+}
+
+export function formatUserCompact(user: TwitterUser): string {
+  return `${bold(user.name)} @${user.screenName} — ${formatCount(user.followersCount)} followers`;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// Library exports
+export { XClient } from "./lib/client-full.ts";
+export { TwitterClient } from "./lib/client.ts";
+export { resolveCredentials } from "./lib/auth.ts";
+export { extractBrowserCookies } from "./lib/cookies.ts";
+export { getQueryId, refreshQueryIds } from "./lib/query-ids.ts";
+export { extractCursorFromInstructions, parseUsersFromInstructions } from "./lib/utils.ts";
+export { autoPaginate } from "./lib/paginate.ts";
+export type { AutoPaginateOpts } from "./lib/paginate.ts";
+
+export type {
+  Credentials,
+  Tweet,
+  TwitterUser,
+  TweetMedia,
+  TweetUrl,
+  SearchResult,
+  TimelineResult,
+  ThreadResult,
+  TwitterList,
+  NewsItem,
+  PaginatedResult,
+  OutputFormat,
+  CLIContext,
+  AboutInfo,
+} from "./lib/types.ts";

package/src/lib/auth.ts

@@ -0,0 +1,105 @@
+import type { BrowserName } from "@steipete/sweet-cookie";
+import type { Credentials } from "./types.ts";
+import { extractBrowserCookies } from "./cookies.ts";
+
+export interface ResolveOptions {
+  authToken?: string;
+  ct0?: string;
+  cookieSource?: BrowserName | BrowserName[];
+  chromeProfile?: string;
+}
+
+export interface ResolveResult {
+  credentials: Credentials | null;
+  warnings: string[];
+}
+
+/**
+ * Resolve Twitter credentials from multiple sources.
+ * Priority: CLI args -> env vars -> browser cookies.
+ */
+export async function resolveCredentials(
+  options: ResolveOptions = {}
+): Promise<ResolveResult> {
+  const warnings: string[] = [];
+
+  // 1. CLI args
+  if (options.authToken && options.ct0) {
+    return {
+      credentials: {
+        authToken: options.authToken,
+        ct0: options.ct0,
+        source: "cli",
+      },
+      warnings,
+    };
+  }
+
+  // 2. Env vars
+  const envAuthToken =
+    options.authToken ||
+    process.env.TWITTER_AUTH_TOKEN ||
+    process.env.AUTH_TOKEN;
+  const envCt0 = options.ct0 || process.env.TWITTER_CT0 || process.env.CT0;
+
+  if (envAuthToken && envCt0) {
+    return {
+      credentials: {
+        authToken: envAuthToken,
+        ct0: envCt0,
+        source: options.authToken || options.ct0 ? "cli" : "env",
+      },
+      warnings,
+    };
+  }
+
+  // 3. Browser cookies
+  const browsers = options.cookieSource
+    ? Array.isArray(options.cookieSource)
+      ? options.cookieSource
+      : [options.cookieSource]
+    : undefined;
+
+  const result = await extractBrowserCookies(browsers, options.chromeProfile);
+  warnings.push(...result.warnings);
+
+  if (result.authToken && result.ct0) {
+    return {
+      credentials: {
+        authToken: result.authToken,
+        ct0: result.ct0,
+        source: "browser",
+        browser: result.source ?? undefined,
+      },
+      warnings,
+    };
+  }
+
+  // Partial credentials — try to combine env + browser
+  const finalAuthToken = envAuthToken || result.authToken;
+  const finalCt0 = envCt0 || result.ct0;
+
+  if (finalAuthToken && finalCt0) {
+    return {
+      credentials: {
+        authToken: finalAuthToken,
+        ct0: finalCt0,
+        source: "env",
+      },
+      warnings,
+    };
+  }
+
+  if (!finalAuthToken) {
+    warnings.push(
+      "Missing auth_token — provide via --auth-token, TWITTER_AUTH_TOKEN env var, or login to x.com in a browser"
+    );
+  }
+  if (!finalCt0) {
+    warnings.push(
+      "Missing ct0 — provide via --ct0, TWITTER_CT0 env var, or login to x.com in a browser"
+    );
+  }
+
+  return { credentials: null, warnings };
+}

package/src/lib/client-bookmarks.ts

@@ -0,0 +1,62 @@
+import { TwitterClient } from "./client.ts";
+import { bookmarksFeatures, fieldToggles } from "./features.ts";
+import { parseTweetsFromInstructions } from "./client-reading.ts";
+import { extractCursorFromInstructions } from "./utils.ts";
+import type { Tweet } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withBookmarks<T extends Constructor>(Base: T) {
+  return class extends Base {
+    async getBookmarks(
+      count?: number,
+      cursor?: string,
+      folderId?: string
+    ): Promise<{
+      success: boolean;
+      tweets: Tweet[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const variables: Record<string, unknown> = {
+          count: count ?? 20,
+          includePromotedContent: false,
+          withDownvotePerspective: false,
+          withReactionsMetadata: false,
+          withReactionsPerspective: false,
+        };
+        if (cursor) variables.cursor = cursor;
+        if (folderId) variables.bookmark_collection_id = folderId;
+
+        const { data, errors } = await this.graphqlGet(
+          "Bookmarks",
+          variables,
+          bookmarksFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return { success: false, tweets: [], error: this.formatErrors(errors) };
+        }
+
+        const bookmarkTimeline = (data as Record<string, unknown>)?.bookmark_timeline_v2 as Record<string, unknown> | undefined;
+        const timeline = bookmarkTimeline?.timeline as Record<string, unknown> | undefined;
+        const instructions = timeline?.instructions as unknown[] | undefined;
+
+        if (!instructions) return { success: true, tweets: [] };
+
+        const tweets = parseTweetsFromInstructions(instructions);
+        const nextCursor = extractCursorFromInstructions(instructions);
+        return { success: true, tweets, cursor: nextCursor };
+      } catch (err) {
+        return {
+          success: false,
+          tweets: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}