xbird-mcp 0.1.0

package/src/commands/follow.ts

@@ -0,0 +1,40 @@
+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 { emoji, green } from "../formatters/common.ts";
+
+export function registerFollow(program: Command): void {
+  program
+    .command("follow <handle>")
+    .description("Follow a user")
+    .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.follow(normalized);
+      if (!result.success) error(result.error ?? "Failed to follow");
+      if (ctx.format === "json") {
+        output({ success: true, action: "follow", handle: normalized }, ctx.format);
+      } else {
+        console.log(`${green(emoji("✓"))} Now following @${normalized}`);
+      }
+    });
+
+  program
+    .command("unfollow <handle>")
+    .description("Unfollow a user")
+    .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.unfollow(normalized);
+      if (!result.success) error(result.error ?? "Failed to unfollow");
+      if (ctx.format === "json") {
+        output({ success: true, action: "unfollow", handle: normalized }, ctx.format);
+      } else {
+        console.log(`${green(emoji("✓"))} Unfollowed @${normalized}`);
+      }
+    });
+}

package/src/commands/followers.ts

@@ -0,0 +1,132 @@
+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 { formatUserCompact } from "../formatters/user.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+import type { TwitterUser } from "../lib/types.ts";
+
+export function registerFollowers(program: Command): void {
+  program
+    .command("followers <handle>")
+    .description("Show followers of a user")
+    .option("-n, --count <number>", "Number of users", "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);
+
+      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<TwitterUser>(
+          async (cursor?) => {
+            const r = await client.getFollowers(userResult.user!.id, count, cursor);
+            return { items: r.users, 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({ users: result.items, cursor: result.cursor }, "json");
+        } else {
+          for (const user of result.items) {
+            console.log(formatUserCompact(user));
+          }
+          if (result.items.length === 0) console.log("No followers found.");
+        }
+      } else {
+        const result = await client.getFollowers(
+          userResult.user!.id,
+          count,
+          opts.cursor
+        );
+        if (!result.success) error(result.error ?? "Failed to load followers");
+
+        if (ctx.format === "json") {
+          output({ users: result.users, cursor: result.cursor }, ctx.format);
+        } else {
+          for (const user of result.users) {
+            console.log(formatUserCompact(user));
+          }
+          if (result.users.length === 0) console.log("No followers found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+
+  program
+    .command("following <handle>")
+    .description("Show users that a user is following")
+    .option("-n, --count <number>", "Number of users", "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);
+
+      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<TwitterUser>(
+          async (cursor?) => {
+            const r = await client.getFollowing(userResult.user!.id, count, cursor);
+            return { items: r.users, 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({ users: result.items, cursor: result.cursor }, "json");
+        } else {
+          for (const user of result.items) {
+            console.log(formatUserCompact(user));
+          }
+          if (result.items.length === 0) console.log("No following found.");
+        }
+      } else {
+        const result = await client.getFollowing(
+          userResult.user!.id,
+          count,
+          opts.cursor
+        );
+        if (!result.success) error(result.error ?? "Failed to load following");
+
+        if (ctx.format === "json") {
+          output({ users: result.users, cursor: result.cursor }, ctx.format);
+        } else {
+          for (const user of result.users) {
+            console.log(formatUserCompact(user));
+          }
+          if (result.users.length === 0) console.log("No following found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}

package/src/commands/home.ts

@@ -0,0 +1,59 @@
+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 { formatTweet } from "../formatters/tweet.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+
+export function registerHome(program: Command): void {
+  program
+    .command("home")
+    .description("Show home timeline")
+    .option("-n, --count <number>", "Number of tweets", "20")
+    .option("--cursor <cursor>", "Pagination cursor")
+    .option("--following", "Show following-only timeline")
+    .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) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+
+      if (opts.all || opts.maxPages) {
+        const result = await autoPaginate(
+          async (cursor?) => {
+            const r = await client.home(count, cursor, opts.following);
+            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("---");
+          }
+        }
+      } else {
+        const result = await client.home(count, opts.cursor, opts.following);
+        if (!result.success || !result.tweets) error(result.error ?? "Failed to load timeline");
+        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.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}

package/src/commands/likes.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 registerLikes(program: Command): void {
+  program
+    .command("likes <handle>")
+    .description("Show tweets liked by a user")
+    .option("-n, --count <number>", "Number of likes", "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.getLikes(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 liked tweets found.");
+        }
+      } else {
+        const result = await client.getLikes(
+          userResult.user!.id,
+          count,
+          opts.cursor
+        );
+        if (!result.success) error(result.error ?? "Failed to load likes");
+
+        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 liked tweets found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}

package/src/commands/lists.ts

@@ -0,0 +1,101 @@
+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 { formatList, formatListCompact } from "../formatters/list.ts";
+import { formatTweet } from "../formatters/tweet.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+import type { Tweet } from "../lib/types.ts";
+
+export function registerLists(program: Command): void {
+  program
+    .command("lists")
+    .description("Show your owned lists and memberships")
+    .action(async function (this: Command) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+
+      const owned = await client.getOwnedLists();
+      const memberships = await client.getListMemberships();
+
+      if (!owned.success && !memberships.success) {
+        error(owned.error ?? memberships.error ?? "Failed to load lists");
+      }
+
+      if (ctx.format === "json") {
+        output({
+          owned: owned.lists,
+          memberships: memberships.lists,
+        }, ctx.format);
+      } else {
+        if (owned.lists.length > 0) {
+          console.log("Owned lists:");
+          for (const list of owned.lists) {
+            console.log(formatListCompact(list));
+          }
+        } else {
+          console.log("No owned lists.");
+        }
+
+        if (memberships.lists.length > 0) {
+          console.log("\nMemberships:");
+          for (const list of memberships.lists) {
+            console.log(formatListCompact(list));
+          }
+        }
+      }
+    });
+
+  program
+    .command("list-timeline <id>")
+    .description("Show tweets from a list")
+    .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, id: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+
+      if (opts.all || opts.maxPages) {
+        const result = await autoPaginate<Tweet>(
+          async (cursor?) => {
+            const r = await client.getListTimeline(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.getListTimeline(id, count, opts.cursor);
+        if (!result.success) error(result.error ?? "Failed to load list timeline");
+
+        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/mentions.ts

@@ -0,0 +1,32 @@
+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 { formatTweet } from "../formatters/tweet.ts";
+
+export function registerMentions(program: Command): void {
+  program
+    .command("mentions")
+    .description("Show recent mentions")
+    .option("-n, --count <number>", "Number of mentions", "20")
+    .action(async function (this: Command) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+      // First get current user handle, then search mentions
+      const me = await client.getCurrentUser();
+      if (!me.success || !me.user) error("Could not determine current user for mentions");
+      const result = await client.mentions(me.user!.screenName, count);
+      if (!result.success || !result.tweets) error(result.error ?? "Failed to load mentions");
+      if (ctx.format === "json") {
+        output(result.tweets, ctx.format);
+      } else {
+        for (const tweet of result.tweets!) {
+          console.log(formatTweet(tweet));
+          console.log("---");
+        }
+        if (result.tweets!.length === 0) console.log("No recent mentions.");
+      }
+    });
+}

package/src/commands/news.ts

@@ -0,0 +1,38 @@
+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 { formatNewsItem, formatNewsItemCompact } from "../formatters/news.ts";
+
+export function registerNews(program: Command): void {
+  program
+    .command("news")
+    .description("Show trending topics and news")
+    .option("--tab <tab>", "News tab: trending, forYou, news, sports, entertainment", "trending")
+    .option("-n, --count <number>", "Number of items", "20")
+    .option("--ai-only", "Only show AI-summarized items")
+    .option("--with-tweets", "Include related tweets")
+    .option("--trending-only", "Only show trending items")
+    .action(async function (this: Command) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+      const result = await client.getNews(count, {
+        tab: opts.tab,
+        aiOnly: opts.aiOnly,
+        withTweets: opts.withTweets,
+        trendingOnly: opts.trendingOnly,
+      });
+      if (!result.success) error(result.error ?? "Failed to load news");
+
+      if (ctx.format === "json") {
+        output(result.items, ctx.format);
+      } else {
+        for (const item of result.items) {
+          console.log(formatNewsItemCompact(item));
+        }
+        if (result.items.length === 0) console.log("No trending topics found.");
+      }
+    });
+}

package/src/commands/read.ts

@@ -0,0 +1,36 @@
+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 { formatTweet } from "../formatters/tweet.ts";
+
+export function registerRead(program: Command): void {
+  program
+    .command("read <id>")
+    .description("Read a tweet by ID or URL")
+    .option("-t, --thread", "Show full thread")
+    .action(async function (this: Command, id: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const tweetId = extractTweetId(id);
+      const opts = this.opts();
+
+      if (opts.thread) {
+        const result = await client.getThread(tweetId);
+        if (!result.success || !result.tweets) error(result.error ?? "Failed to get thread");
+        if (ctx.format === "json") {
+          output(result.tweets, ctx.format);
+        } else {
+          for (const tweet of result.tweets!) {
+            console.log(formatTweet(tweet));
+            console.log("---");
+          }
+        }
+      } else {
+        const result = await client.getTweet(tweetId);
+        if (!result.success || !result.tweet) error(result.error ?? "Failed to get tweet");
+        output(result.tweet, ctx.format, (data) => formatTweet(data as any));
+      }
+    });
+}

package/src/commands/replies.ts

@@ -0,0 +1,59 @@
+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 { formatTweet, formatTweetCompact } from "../formatters/tweet.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+
+export function registerReplies(program: Command): void {
+  program
+    .command("replies <id>")
+    .description("Show replies to a tweet")
+    .option("-n, --count <number>", "Number per page", "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, id: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+
+      if (opts.all || opts.maxPages) {
+        const result = await autoPaginate(
+          async (cursor?) => {
+            const r = await client.getReplies(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 t of result.items) {
+            console.log(formatTweetCompact(t));
+          }
+        }
+      } else {
+        const result = await client.getReplies(id, count, opts.cursor);
+        if (!result.success) error(result.error ?? "Failed to load replies");
+
+        if (ctx.format === "json" || ctx.format === "json-full") {
+          output({ tweets: result.tweets, cursor: result.cursor }, "json");
+        } else {
+          for (const t of result.tweets) {
+            console.log(formatTweet(t));
+            console.log("---");
+          }
+          if (result.tweets.length === 0) console.log("No replies found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}

package/src/commands/search.ts

@@ -0,0 +1,60 @@
+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 { formatTweet, formatTweetCompact } from "../formatters/tweet.ts";
+import { autoPaginate } from "../lib/paginate.ts";
+
+export function registerSearch(program: Command): void {
+  program
+    .command("search <query>")
+    .description("Search tweets")
+    .option("-n, --count <number>", "Number of results", "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, query: string) {
+      const ctx = await createContext(this);
+      const client = new XClient(ctx.credentials, ctx.timeoutMs);
+      const opts = this.opts();
+      const count = parseInt(opts.count, 10);
+
+      if (opts.all || opts.maxPages) {
+        const result = await autoPaginate(
+          async (cursor?) => {
+            const r = await client.search(query, 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 results found.");
+        }
+      } else {
+        const result = await client.search(query, count, opts.cursor);
+        if (!result.success || !result.tweets) error(result.error ?? "Search failed");
+        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 results found.");
+          if (result.cursor) console.log(`\nNext cursor: ${result.cursor}`);
+        }
+      }
+    });
+}