xbird-mcp 0.1.0

package/src/lib/types.ts

@@ -0,0 +1,147 @@
+export interface Credentials {
+  authToken: string;
+  ct0: string;
+  source: "cli" | "env" | "browser";
+  browser?: string;
+}
+
+export interface TwitterUser {
+  id: string;
+  screenName: string;
+  name: string;
+  description: string;
+  followersCount: number;
+  followingCount: number;
+  tweetCount: number;
+  verified: boolean;
+  profileImageUrl: string;
+  createdAt: string;
+  location?: string;
+  url?: string;
+  isBlueVerified: boolean;
+}
+
+export interface Tweet {
+  id: string;
+  text: string;
+  authorId: string;
+  authorName: string;
+  authorHandle: string;
+  createdAt: string;
+  likeCount: number;
+  retweetCount: number;
+  replyCount: number;
+  quoteCount: number;
+  bookmarkCount: number;
+  viewCount: number;
+  isRetweet: boolean;
+  isReply: boolean;
+  inReplyToId?: string;
+  conversationId?: string;
+  lang?: string;
+  media?: TweetMedia[];
+  urls?: TweetUrl[];
+  quotedTweet?: Tweet;
+}
+
+export interface TweetMedia {
+  type: "photo" | "video" | "animated_gif";
+  url: string;
+  width?: number;
+  height?: number;
+  videoUrl?: string;
+  durationMs?: number;
+}
+
+export interface TweetUrl {
+  url: string;
+  expandedUrl: string;
+  displayUrl: string;
+}
+
+export interface SearchResult {
+  tweets: Tweet[];
+  cursor?: string;
+}
+
+export interface TimelineResult {
+  tweets: Tweet[];
+  cursor?: string;
+}
+
+export interface ThreadResult {
+  mainTweet: Tweet;
+  replies: Tweet[];
+}
+
+export interface QueryIdEntry {
+  queryId: string;
+  operationName: string;
+}
+
+export interface QueryIdCache {
+  version: number;
+  timestamp: number;
+  ids: Record<string, QueryIdEntry>;
+}
+
+export interface GraphQLResponse<T = unknown> {
+  data?: T;
+  errors?: Array<{ message: string; code?: number }>;
+}
+
+export interface TwitterList {
+  id: string;
+  name: string;
+  description: string;
+  memberCount: number;
+  subscriberCount: number;
+  isPrivate: boolean;
+  createdAt: string;
+  owner?: { id: string; screenName: string; name: string };
+}
+
+export interface NewsItem {
+  id: string;
+  headline: string;
+  category: string;
+  postCount?: number;
+  description?: string;
+  url?: string;
+  tweets?: Tweet[];
+}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  cursor?: string;
+}
+
+export interface AboutInfo {
+  accountBasedIn?: string;
+  createdAt?: string;
+  source?: string;
+}
+
+export type OutputFormat = "human" | "json" | "json-full" | "plain";
+
+export type ExtendedBrowserName = "chrome" | "edge" | "firefox" | "safari" | "arc" | "brave";
+
+export interface XbirdConfig {
+  authToken?: string;
+  ct0?: string;
+  cookieSource?: ExtendedBrowserName;
+  format?: OutputFormat;
+  timeout?: number;
+  noColor?: boolean;
+  noEmoji?: boolean;
+  quoteDepth?: number;
+}
+
+export interface CLIContext {
+  credentials: Credentials;
+  format: OutputFormat;
+  noColor: boolean;
+  noEmoji: boolean;
+  quoteDepth: number;
+  timeoutMs: number;
+}

package/src/lib/utils.ts

@@ -0,0 +1,176 @@
+/**
+ * Extract tweet ID from a URL or return the ID directly.
+ * Supports: https://x.com/user/status/123, https://twitter.com/user/status/123, plain ID
+ */
+export function extractTweetId(input: string): string {
+  const trimmed = input.trim();
+
+  // Plain numeric ID
+  if (/^\d+$/.test(trimmed)) {
+    return trimmed;
+  }
+
+  // URL format
+  const match = trimmed.match(
+    /(?:twitter\.com|x\.com)\/\w+\/status\/(\d+)/
+  );
+  if (match?.[1]) {
+    return match[1];
+  }
+
+  throw new Error(`Invalid tweet ID or URL: ${input}`);
+}
+
+/**
+ * Normalize a Twitter handle — strips leading @ and whitespace.
+ */
+export function normalizeHandle(handle: string): string {
+  return handle.trim().replace(/^@/, "");
+}
+
+/**
+ * Build a tweet URL from handle and ID.
+ */
+export function tweetUrl(handle: string, id: string): string {
+  return `https://x.com/${normalizeHandle(handle)}/status/${id}`;
+}
+
+/**
+ * Build a profile URL from handle.
+ */
+export function profileUrl(handle: string): string {
+  return `https://x.com/${normalizeHandle(handle)}`;
+}
+
+/**
+ * Format a large number for human display (e.g. 1234 → "1.2K").
+ */
+export function formatCount(n: number): string {
+  if (n >= 1_000_000) {
+    return `${(n / 1_000_000).toFixed(1)}M`;
+  }
+  if (n >= 1_000) {
+    return `${(n / 1_000).toFixed(1)}K`;
+  }
+  return String(n);
+}
+
+/**
+ * Format a date string to a relative or short format.
+ */
+export function formatDate(dateStr: string): string {
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  if (diffSec < 60) return `${diffSec}s`;
+  if (diffMin < 60) return `${diffMin}m`;
+  if (diffHour < 24) return `${diffHour}h`;
+  if (diffDay < 7) return `${diffDay}d`;
+
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: date.getFullYear() !== now.getFullYear() ? "numeric" : undefined,
+  });
+}
+
+/**
+ * Truncate text to a max length with ellipsis.
+ */
+export function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "…";
+}
+
+/**
+ * Extract a cursor value from GraphQL timeline instructions.
+ * Looks for entries with entryId starting with `cursor-bottom-` or `cursor-top-`.
+ */
+export function extractCursorFromInstructions(
+  instructions: unknown[],
+  cursorType: "Bottom" | "Top" = "Bottom"
+): string | undefined {
+  const prefix = `cursor-${cursorType.toLowerCase()}-`;
+
+  for (const inst of instructions ?? []) {
+    const instruction = inst as Record<string, unknown>;
+
+    // Check replaceEntry type (Twitter sometimes sends cursor updates this way)
+    if (instruction.type === "TimelineReplaceEntry") {
+      const entry = instruction.entry as Record<string, unknown> | undefined;
+      const entryId = entry?.entryId as string | undefined;
+      if (entryId?.startsWith(prefix)) {
+        const content = entry?.content as Record<string, unknown> | undefined;
+        return content?.value as string | undefined;
+      }
+    }
+
+    const entries = (instruction.entries ?? []) as Array<Record<string, unknown>>;
+    for (const entry of entries) {
+      const entryId = entry.entryId as string | undefined;
+      if (entryId?.startsWith(prefix)) {
+        const content = entry.content as Record<string, unknown> | undefined;
+        return content?.value as string | undefined;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Parse user objects from GraphQL timeline instructions.
+ */
+export function parseUsersFromInstructions(instructions: unknown[]): import("./types.ts").TwitterUser[] {
+  const users: import("./types.ts").TwitterUser[] = [];
+
+  for (const inst of instructions ?? []) {
+    const instruction = inst as Record<string, unknown>;
+    const entries = (instruction.entries ?? []) as Array<Record<string, unknown>>;
+
+    for (const entry of entries) {
+      const content = entry.content as Record<string, unknown> | undefined;
+      const itemContent = content?.itemContent as Record<string, unknown> | undefined;
+      const userResults = itemContent?.user_results as Record<string, unknown> | undefined;
+      const result = userResults?.result as Record<string, unknown> | undefined;
+
+      if (!result) continue;
+
+      const legacy = result.legacy as Record<string, unknown> | undefined;
+      const core = result.core as Record<string, unknown> | undefined;
+      const avatar = result.avatar as Record<string, unknown> | undefined;
+      const locationObj = result.location as Record<string, unknown> | undefined;
+
+      if (!legacy && !core) continue;
+
+      users.push({
+        id: String(result.rest_id ?? ""),
+        screenName: String(core?.screen_name ?? legacy?.screen_name ?? ""),
+        name: String(core?.name ?? legacy?.name ?? ""),
+        description: String(legacy?.description ?? ""),
+        followersCount: Number(legacy?.followers_count ?? 0),
+        followingCount: Number(legacy?.friends_count ?? 0),
+        tweetCount: Number(legacy?.statuses_count ?? 0),
+        verified: Boolean(legacy?.verified),
+        profileImageUrl: String(
+          avatar?.image_url ?? legacy?.profile_image_url_https ?? legacy?.profile_image_url ?? ""
+        ),
+        createdAt: String(core?.created_at ?? legacy?.created_at ?? ""),
+        location: locationObj?.location
+          ? String(locationObj.location)
+          : legacy?.location
+            ? String(legacy.location)
+            : undefined,
+        url: legacy?.url ? String(legacy.url) : undefined,
+        isBlueVerified: Boolean(result.is_blue_verified),
+      });
+    }
+  }
+
+  return users;
+}

package/src/mcp/executor.ts

@@ -0,0 +1,178 @@
+import type { XClient } from "../lib/client-full.ts";
+import type { PaymentHelper } from "./payment.ts";
+import type { PriceTier } from "../server/config/pricing.ts";
+
+export class PaidExecutor {
+  constructor(
+    private client: XClient,
+    private pay: PaymentHelper
+  ) {}
+
+  private async authorize(tier: PriceTier): Promise<void> {
+    await this.pay.authorize(tier);
+  }
+
+  // ── Read tier ($0.001) ──────────────────────────────────
+
+  async getTweet(id: string) {
+    await this.authorize("read");
+    return this.client.getTweet(id);
+  }
+
+  async getThread(id: string) {
+    await this.authorize("read");
+    return this.client.getThread(id);
+  }
+
+  async getReplies(id: string, count?: number, cursor?: string) {
+    await this.authorize("read");
+    return this.client.getReplies(id, count, cursor);
+  }
+
+  async getUserByHandle(handle: string) {
+    await this.authorize("read");
+    return this.client.getUserByHandle(handle);
+  }
+
+  async getAbout(handle: string) {
+    await this.authorize("read");
+    return this.client.getAbout(handle);
+  }
+
+  async getCurrentUser() {
+    await this.authorize("read");
+    return this.client.getCurrentUser();
+  }
+
+  async home(count?: number, cursor?: string) {
+    await this.authorize("read");
+    return this.client.home(count, cursor);
+  }
+
+  async getNews(count?: number, opts?: { tab?: string; aiOnly?: boolean }) {
+    await this.authorize("read");
+    return this.client.getNews(count, opts);
+  }
+
+  async getOwnedLists() {
+    await this.authorize("read");
+    return this.client.getOwnedLists();
+  }
+
+  async getListTimeline(id: string, count?: number, cursor?: string) {
+    await this.authorize("read");
+    return this.client.getListTimeline(id, count, cursor);
+  }
+
+  // ── Search tier ($0.005) ────────────────────────────────
+
+  async search(query: string, count?: number, cursor?: string) {
+    await this.authorize("search");
+    return this.client.search(query, count, cursor);
+  }
+
+  async mentions(handle: string, count?: number) {
+    await this.authorize("search");
+    return this.client.mentions(handle, count);
+  }
+
+  // ── Bulk tier ($0.01) ───────────────────────────────────
+
+  async getUserTweets(userId: string, count?: number, cursor?: string) {
+    await this.authorize("bulk");
+    return this.client.getUserTweets(userId, count, cursor);
+  }
+
+  async getFollowers(userId: string, count?: number, cursor?: string) {
+    await this.authorize("bulk");
+    return this.client.getFollowers(userId, count, cursor);
+  }
+
+  async getFollowing(userId: string, count?: number, cursor?: string) {
+    await this.authorize("bulk");
+    return this.client.getFollowing(userId, count, cursor);
+  }
+
+  async getLikes(userId: string, count?: number, cursor?: string) {
+    await this.authorize("bulk");
+    return this.client.getLikes(userId, count, cursor);
+  }
+
+  async getBookmarks(count?: number, cursor?: string, folderId?: string) {
+    await this.authorize("bulk");
+    return this.client.getBookmarks(count, cursor, folderId);
+  }
+
+  async getListMemberships() {
+    await this.authorize("bulk");
+    return this.client.getListMemberships();
+  }
+
+  // ── Write tier ($0.01) ──────────────────────────────────
+
+  async tweet(text: string, mediaIds?: string[]) {
+    await this.authorize("write");
+    return this.client.tweet(text, mediaIds);
+  }
+
+  async reply(text: string, replyToId: string, mediaIds?: string[]) {
+    await this.authorize("write");
+    return this.client.reply(text, replyToId, mediaIds);
+  }
+
+  async thread(texts: string[]) {
+    await this.authorize("write");
+    return this.client.thread(texts);
+  }
+
+  async like(tweetId: string) {
+    await this.authorize("write");
+    return this.client.like(tweetId);
+  }
+
+  async unlike(tweetId: string) {
+    await this.authorize("write");
+    return this.client.unlike(tweetId);
+  }
+
+  async retweet(tweetId: string) {
+    await this.authorize("write");
+    return this.client.retweet(tweetId);
+  }
+
+  async unretweet(tweetId: string) {
+    await this.authorize("write");
+    return this.client.unretweet(tweetId);
+  }
+
+  async bookmark(tweetId: string) {
+    await this.authorize("write");
+    return this.client.bookmark(tweetId);
+  }
+
+  async unbookmark(tweetId: string) {
+    await this.authorize("write");
+    return this.client.unbookmark(tweetId);
+  }
+
+  async follow(handle: string) {
+    await this.authorize("write");
+    return this.client.follow(handle);
+  }
+
+  async unfollow(handle: string) {
+    await this.authorize("write");
+    return this.client.unfollow(handle);
+  }
+
+  // ── Media tier ($0.05) ──────────────────────────────────
+
+  async uploadMedia(opts: {
+    data: Uint8Array | Buffer;
+    mimeType: string;
+    alt?: string;
+  }) {
+    await this.authorize("media");
+    return this.client.uploadMedia(opts);
+  }
+}

package/src/mcp/payment.ts

@@ -0,0 +1,38 @@
+import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+import type { PriceTier } from "../server/config/pricing.ts";
+
+export interface PaymentHelper {
+  authorize(tier: PriceTier): Promise<void>;
+}
+
+export function createPaymentHelper(
+  privateKey: `0x${string}`,
+  serverUrl: string
+): PaymentHelper {
+  const account = privateKeyToAccount(privateKey);
+  const client = new x402Client();
+  registerExactEvmScheme(client, { signer: account });
+  const paymentFetch = wrapFetchWithPayment(fetch, client);
+
+  return {
+    async authorize(tier: PriceTier): Promise<void> {
+      const res = await paymentFetch(`${serverUrl}/api/authorize/${tier}`, {
+        method: "POST",
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(
+          `Payment failed for tier "${tier}": ${res.status} ${res.statusText} ${body}`
+        );
+      }
+
+      const data = (await res.json()) as { authorized?: boolean };
+      if (!data.authorized) {
+        throw new Error(`Authorization denied for tier "${tier}"`);
+      }
+    },
+  };
+}

package/src/mcp/server.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { XClient } from "../lib/client-full.ts";
+import { createPaymentHelper } from "./payment.ts";
+import { PaidExecutor } from "./executor.ts";
+import { registerTools } from "./tools.ts";
+
+const AUTH_TOKEN = process.env.XBIRD_AUTH_TOKEN;
+const CT0 = process.env.XBIRD_CT0;
+const PRIVATE_KEY = process.env.XBIRD_PRIVATE_KEY as `0x${string}` | undefined;
+const SERVER_URL =
+  process.env.XBIRD_SERVER_URL ?? "https://xbirdapi.up.railway.app";
+
+if (!AUTH_TOKEN || !CT0) {
+  console.error(
+    "Missing required env vars: XBIRD_AUTH_TOKEN and XBIRD_CT0 (Twitter credentials)"
+  );
+  process.exit(1);
+}
+
+if (!PRIVATE_KEY) {
+  console.error(
+    "Missing required env var: XBIRD_PRIVATE_KEY (wallet private key for x402 payments)"
+  );
+  process.exit(1);
+}
+
+// Initialize Twitter client with local credentials
+const client = new XClient({
+  authToken: AUTH_TOKEN,
+  ct0: CT0,
+  source: "env",
+});
+
+// Initialize payment helper
+const payment = createPaymentHelper(PRIVATE_KEY, SERVER_URL);
+
+// Create executor (XClient + payment)
+const executor = new PaidExecutor(client, payment);
+
+// Create MCP server
+const server = new McpServer({
+  name: "xbird",
+  version: "0.1.0",
+});
+
+// Register all 30 tools
+registerTools(server, executor);
+
+// Start stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);