xbird-mcp 0.1.0

package/src/mcp/tools.ts

@@ -0,0 +1,389 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { PaidExecutor } from "./executor.ts";
+
+export function registerTools(server: McpServer, executor: PaidExecutor): void {
+  // ── Read tier ($0.001) ──────────────────────────────────
+
+  server.tool(
+    "get_tweet",
+    "Get a tweet by ID",
+    { id: z.string().describe("Tweet ID") },
+    async ({ id }) => {
+      const result = await executor.getTweet(id);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_thread",
+    "Get a tweet thread (conversation chain)",
+    { id: z.string().describe("Tweet ID of any tweet in the thread") },
+    async ({ id }) => {
+      const result = await executor.getThread(id);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_replies",
+    "Get replies to a tweet",
+    {
+      id: z.string().describe("Tweet ID"),
+      count: z.number().optional().describe("Number of replies (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ id, count, cursor }) => {
+      const result = await executor.getReplies(id, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_user",
+    "Get a Twitter user profile by handle",
+    { handle: z.string().describe("Twitter handle (without @)") },
+    async ({ handle }) => {
+      const result = await executor.getUserByHandle(handle);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_user_about",
+    "Get detailed about info for a user",
+    { handle: z.string().describe("Twitter handle (without @)") },
+    async ({ handle }) => {
+      const result = await executor.getAbout(handle);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_current_user",
+    "Get the authenticated user's profile",
+    {},
+    async () => {
+      const result = await executor.getCurrentUser();
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_home_timeline",
+    "Get the home timeline (latest tweets from followed accounts)",
+    {
+      count: z.number().optional().describe("Number of tweets (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ count, cursor }) => {
+      const result = await executor.home(count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_news",
+    "Get trending news/topics on Twitter",
+    {
+      count: z.number().optional().describe("Number of items"),
+      tab: z.string().optional().describe("News tab: trending, forYou, news, sports, entertainment"),
+      aiOnly: z.boolean().optional().describe("Only AI-generated summaries"),
+    },
+    async ({ count, tab, aiOnly }) => {
+      const opts = tab || aiOnly !== undefined ? { tab, aiOnly } : undefined;
+      const result = await executor.getNews(count, opts);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_lists",
+    "Get owned Twitter lists",
+    {},
+    async () => {
+      const result = await executor.getOwnedLists();
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_list_timeline",
+    "Get tweets from a list",
+    {
+      id: z.string().describe("List ID"),
+      count: z.number().optional().describe("Number of tweets (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ id, count, cursor }) => {
+      const result = await executor.getListTimeline(id, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  // ── Search tier ($0.005) ────────────────────────────────
+
+  server.tool(
+    "search_tweets",
+    "Search for tweets",
+    {
+      query: z.string().describe("Search query"),
+      count: z.number().optional().describe("Number of results (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ query, count, cursor }) => {
+      const result = await executor.search(query, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_mentions",
+    "Get mentions for a user",
+    {
+      handle: z.string().describe("Twitter handle (without @)"),
+      count: z.number().optional().describe("Number of mentions"),
+    },
+    async ({ handle, count }) => {
+      const result = await executor.mentions(handle, count);
+      return toMcpResult(result);
+    }
+  );
+
+  // ── Bulk tier ($0.01) ───────────────────────────────────
+
+  server.tool(
+    "get_user_tweets",
+    "Get tweets posted by a user",
+    {
+      userId: z.string().describe("User ID (numeric)"),
+      count: z.number().optional().describe("Number of tweets (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ userId, count, cursor }) => {
+      const result = await executor.getUserTweets(userId, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_followers",
+    "Get a user's followers",
+    {
+      userId: z.string().describe("User ID (numeric)"),
+      count: z.number().optional().describe("Number of followers (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ userId, count, cursor }) => {
+      const result = await executor.getFollowers(userId, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_following",
+    "Get users that a user follows",
+    {
+      userId: z.string().describe("User ID (numeric)"),
+      count: z.number().optional().describe("Number of users (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ userId, count, cursor }) => {
+      const result = await executor.getFollowing(userId, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_likes",
+    "Get tweets liked by a user",
+    {
+      userId: z.string().describe("User ID (numeric)"),
+      count: z.number().optional().describe("Number of liked tweets (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+    },
+    async ({ userId, count, cursor }) => {
+      const result = await executor.getLikes(userId, count, cursor);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_bookmarks",
+    "Get bookmarked tweets",
+    {
+      count: z.number().optional().describe("Number of bookmarks (default 20)"),
+      cursor: z.string().optional().describe("Pagination cursor"),
+      folderId: z.string().optional().describe("Bookmark folder ID"),
+    },
+    async ({ count, cursor, folderId }) => {
+      const result = await executor.getBookmarks(count, cursor, folderId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "get_list_memberships",
+    "Get lists the authenticated user is a member of",
+    {},
+    async () => {
+      const result = await executor.getListMemberships();
+      return toMcpResult(result);
+    }
+  );
+
+  // ── Write tier ($0.01) ──────────────────────────────────
+
+  server.tool(
+    "post_tweet",
+    "Post a new tweet",
+    {
+      text: z.string().describe("Tweet text"),
+      mediaIds: z.array(z.string()).optional().describe("Media IDs to attach"),
+    },
+    async ({ text, mediaIds }) => {
+      const result = await executor.tweet(text, mediaIds);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "reply_to_tweet",
+    "Reply to a tweet",
+    {
+      text: z.string().describe("Reply text"),
+      replyToId: z.string().describe("Tweet ID to reply to"),
+      mediaIds: z.array(z.string()).optional().describe("Media IDs to attach"),
+    },
+    async ({ text, replyToId, mediaIds }) => {
+      const result = await executor.reply(text, replyToId, mediaIds);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "post_thread",
+    "Post a thread (multiple tweets in sequence)",
+    {
+      texts: z.array(z.string()).min(2).describe("Array of tweet texts (each becomes one tweet in the thread)"),
+    },
+    async ({ texts }) => {
+      const result = await executor.thread(texts);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "like_tweet",
+    "Like a tweet",
+    { tweetId: z.string().describe("Tweet ID to like") },
+    async ({ tweetId }) => {
+      const result = await executor.like(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "unlike_tweet",
+    "Unlike a tweet",
+    { tweetId: z.string().describe("Tweet ID to unlike") },
+    async ({ tweetId }) => {
+      const result = await executor.unlike(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "retweet",
+    "Retweet a tweet",
+    { tweetId: z.string().describe("Tweet ID to retweet") },
+    async ({ tweetId }) => {
+      const result = await executor.retweet(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "unretweet",
+    "Remove a retweet",
+    { tweetId: z.string().describe("Tweet ID to unretweet") },
+    async ({ tweetId }) => {
+      const result = await executor.unretweet(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "bookmark_tweet",
+    "Bookmark a tweet",
+    { tweetId: z.string().describe("Tweet ID to bookmark") },
+    async ({ tweetId }) => {
+      const result = await executor.bookmark(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "unbookmark_tweet",
+    "Remove a tweet bookmark",
+    { tweetId: z.string().describe("Tweet ID to unbookmark") },
+    async ({ tweetId }) => {
+      const result = await executor.unbookmark(tweetId);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "follow_user",
+    "Follow a Twitter user",
+    { handle: z.string().describe("Twitter handle to follow (without @)") },
+    async ({ handle }) => {
+      const result = await executor.follow(handle);
+      return toMcpResult(result);
+    }
+  );
+
+  server.tool(
+    "unfollow_user",
+    "Unfollow a Twitter user",
+    { handle: z.string().describe("Twitter handle to unfollow (without @)") },
+    async ({ handle }) => {
+      const result = await executor.unfollow(handle);
+      return toMcpResult(result);
+    }
+  );
+
+  // ── Media tier ($0.05) ──────────────────────────────────
+
+  server.tool(
+    "upload_media",
+    "Upload media (image/video) for use in tweets. Returns a mediaId to pass to post_tweet or reply_to_tweet.",
+    {
+      filePath: z.string().describe("Absolute path to the media file"),
+      alt: z.string().optional().describe("Alt text for accessibility"),
+    },
+    async ({ filePath, alt }) => {
+      const file = Bun.file(filePath);
+      const exists = await file.exists();
+      if (!exists) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: `File not found: ${filePath}` }) }],
+          isError: true,
+        };
+      }
+      const data = new Uint8Array(await file.arrayBuffer());
+      const mimeType = file.type || "application/octet-stream";
+      const result = await executor.uploadMedia({ data, mimeType, alt });
+      return toMcpResult(result);
+    }
+  );
+}
+
+/** Convert XClient result to MCP tool result format */
+function toMcpResult(result: Record<string, unknown>) {
+  const isError = result.success === false;
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+    isError,
+  };
+}

package/src/server/app.ts

@@ -0,0 +1,117 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { bodyLimit } from "hono/body-limit";
+import { logger } from "hono/logger";
+
+import { errorHandler } from "./middleware/error-handler.ts";
+import { accountPoolMiddleware, type XbirdEnv } from "./middleware/account-pool.ts";
+import { payerExtractMiddleware } from "./middleware/payer-extract.ts";
+import { createPaymentMiddleware } from "./middleware/x402.ts";
+import { NETWORK, ROUTE_PRICES } from "./config/pricing.ts";
+import type { AccountsDB } from "./storage/accounts-db.ts";
+
+import { health } from "./routes/health.ts";
+import { tweets } from "./routes/tweets.ts";
+import { users } from "./routes/users.ts";
+import { search } from "./routes/search.ts";
+import { timeline } from "./routes/timeline.ts";
+import { engagement } from "./routes/engagement.ts";
+import { follow } from "./routes/follow.ts";
+import { lists } from "./routes/lists.ts";
+import { news } from "./routes/news.ts";
+import { media } from "./routes/media.ts";
+import { mentions } from "./routes/mentions.ts";
+import { bookmarks } from "./routes/bookmarks.ts";
+import { createAccountsRoutes } from "./routes/accounts.ts";
+import { authorize } from "./routes/authorize.ts";
+
+export function createApp(payTo: string, accountsDb: AccountsDB): Hono<XbirdEnv> {
+  const app = new Hono<XbirdEnv>();
+
+  // Global middleware
+  app.use("*", cors());
+  app.use("*", logger());
+  app.use("*", errorHandler);
+
+  // Free routes (no payment, no auth)
+  app.route("/", health);
+
+  // Serve agent card (free)
+  app.get("/.well-known/agent.json", async (c) => {
+    const card = await Bun.file(
+      new URL("./erc8004/agent-card.json", import.meta.url).pathname
+    ).json();
+    // Inject dynamic values
+    card.paymentAddress = payTo;
+    card.network = NETWORK;
+    return c.json(card);
+  });
+
+  // x402scan discovery document (free)
+  app.get("/.well-known/x402", (c) => {
+    const baseUrl = process.env.XBIRD_BASE_URL ?? `https://${c.req.header("host")}`;
+    const resources = Object.keys(ROUTE_PRICES).map((route) => {
+      // "GET /api/tweets/[id]" → "https://host/api/tweets/[id]"
+      const path = route.split(" ")[1];
+      return `${baseUrl}${path}`;
+    });
+
+    return c.json({
+      version: 1,
+      resources,
+      instructions: [
+        "# xbird — BYOA Twitter/X API",
+        "",
+        "Pay-per-request Twitter API. Bring your own Twitter account, pay with USDC on Base.",
+        "",
+        "## Quick Start",
+        "1. Register your Twitter account: `POST /api/accounts` with `{ authToken, ct0 }`",
+        "2. Use any endpoint — your account is used automatically",
+        "",
+        "## Alternative",
+        "Pass `X-Twitter-Auth-Token` and `X-Twitter-CT0` headers per-request.",
+        "",
+        "## Docs",
+        `Agent card: ${baseUrl}/.well-known/agent.json`,
+      ].join("\n"),
+    });
+  });
+
+  // Body size limit for API routes (10KB — prevents DoS via oversized payloads)
+  app.use("/api/*", bodyLimit({ maxSize: 10 * 1024 }));
+
+  // x402 payment middleware — only for /api/* routes
+  app.use("/api/*", createPaymentMiddleware(payTo));
+
+  // Extract payer wallet from verified payment-signature header
+  app.use("/api/*", payerExtractMiddleware());
+
+  // BYOA account resolve — headers → registered account → reject
+  // (account routes are skipped inside the middleware)
+  app.use("/api/*", accountPoolMiddleware(accountsDb));
+
+  // Authorize routes — payment-only, no Twitter credentials needed (for MCP local execution)
+  app.route("/api/authorize", authorize);
+
+  // Account management routes (BYOA registration)
+  app.route("/api/accounts", createAccountsRoutes(accountsDb));
+
+  // API routes
+  app.route("/api/tweets", tweets);
+  app.route("/api/users", users);
+  app.route("/api/search", search);
+  app.route("/api/timeline", timeline);
+  app.route("/api/mentions", mentions);
+  app.route("/api/bookmarks", bookmarks);
+  app.route("/api/lists", lists);
+  app.route("/api/news", news);
+  app.route("/api/media", media);
+
+  // Engagement routes share /api/tweets/:id/* namespace
+  app.route("/api/tweets", engagement);
+
+  // Follow routes share /api/users/:handle/* namespace
+  app.route("/api/users", follow);
+
+  return app;
+}

package/src/server/config/accounts.ts

@@ -0,0 +1,137 @@
+import { XClient } from "../../lib/client-full.ts";
+import { resolveCredentials } from "../../lib/auth.ts";
+import type { Credentials } from "../../lib/types.ts";
+
+interface AccountEntry {
+  name: string;
+  authToken: string;
+  ct0: string;
+}
+
+interface PoolEntry {
+  name: string;
+  client: XClient;
+  lastUsed: number;
+  cooldownUntil: number;
+  disabled: boolean;
+}
+
+const COOLDOWN_MS = 2_000;
+const RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+export class AccountPool {
+  private accounts: PoolEntry[] = [];
+  private index = 0;
+
+  constructor(entries: AccountEntry[]) {
+    for (const entry of entries) {
+      const credentials: Credentials = {
+        authToken: entry.authToken,
+        ct0: entry.ct0,
+        source: "env",
+      };
+      this.accounts.push({
+        name: entry.name,
+        client: new XClient(credentials),
+        lastUsed: 0,
+        cooldownUntil: 0,
+        disabled: false,
+      });
+    }
+  }
+
+  get size(): number {
+    return this.accounts.length;
+  }
+
+  get availableCount(): number {
+    const now = Date.now();
+    return this.accounts.filter(
+      (a) => !a.disabled && a.cooldownUntil <= now
+    ).length;
+  }
+
+  /** Acquire a client using round-robin with cooldown awareness */
+  acquire(): { client: XClient; name: string } | null {
+    const now = Date.now();
+    const len = this.accounts.length;
+
+    for (let i = 0; i < len; i++) {
+      const idx = (this.index + i) % len;
+      const entry = this.accounts[idx]!;
+
+      if (entry.disabled || entry.cooldownUntil > now) continue;
+
+      entry.lastUsed = now;
+      entry.cooldownUntil = now + COOLDOWN_MS;
+      this.index = (idx + 1) % len;
+      return { client: entry.client, name: entry.name };
+    }
+
+    return null;
+  }
+
+  /** Mark an account as rate-limited */
+  markRateLimited(name: string): void {
+    const entry = this.accounts.find((a) => a.name === name);
+    if (entry) {
+      entry.cooldownUntil = Date.now() + RATE_LIMIT_COOLDOWN_MS;
+    }
+  }
+
+  /** Disable an account entirely */
+  disable(name: string): void {
+    const entry = this.accounts.find((a) => a.name === name);
+    if (entry) {
+      entry.disabled = true;
+    }
+  }
+
+  /** Re-enable a disabled account */
+  enable(name: string): void {
+    const entry = this.accounts.find((a) => a.name === name);
+    if (entry) {
+      entry.disabled = false;
+      entry.cooldownUntil = 0;
+    }
+  }
+
+  /** Load accounts from env or config file */
+  static async load(): Promise<AccountPool> {
+    // 1. Try XBIRD_ACCOUNTS env (JSON array)
+    const envAccounts = process.env.XBIRD_ACCOUNTS;
+    if (envAccounts) {
+      const entries = JSON.parse(envAccounts) as AccountEntry[];
+      return new AccountPool(entries);
+    }
+
+    // 2. Try config file
+    const configPath = `${process.env.HOME}/.config/xbird/accounts.json`;
+    const file = Bun.file(configPath);
+    if (await file.exists()) {
+      const entries = (await file.json()) as AccountEntry[];
+      return new AccountPool(entries);
+    }
+
+    // 3. Try single account from env
+    const authToken = process.env.TWITTER_AUTH_TOKEN ?? process.env.AUTH_TOKEN;
+    const ct0 = process.env.TWITTER_CT0 ?? process.env.CT0;
+    if (authToken && ct0) {
+      return new AccountPool([{ name: "default", authToken, ct0 }]);
+    }
+
+    // 4. Try browser cookies (same as CLI)
+    const { credentials, warnings } = await resolveCredentials();
+    for (const w of warnings) console.warn(`[accounts] ${w}`);
+    if (credentials) {
+      console.log(`[accounts] Using browser cookies (source: ${credentials.source}${credentials.browser ? `, ${credentials.browser}` : ""})`);
+      return new AccountPool([{
+        name: `browser-${credentials.browser ?? credentials.source}`,
+        authToken: credentials.authToken,
+        ct0: credentials.ct0,
+      }]);
+    }
+
+    return new AccountPool([]);
+  }
+}