xbird-mcp 0.1.0

package/src/server/routes/engagement.ts

@@ -0,0 +1,84 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const engagement = new Hono<XbirdEnv>();
+
+/** POST /api/tweets/:id/like */
+engagement.post("/:id/like", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.like(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to like" }, 400);
+  }
+
+  return c.json({ data: { liked: true } });
+});
+
+/** DELETE /api/tweets/:id/like */
+engagement.delete("/:id/like", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.unlike(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to unlike" }, 400);
+  }
+
+  return c.json({ data: { liked: false } });
+});
+
+/** POST /api/tweets/:id/retweet */
+engagement.post("/:id/retweet", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.retweet(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to retweet" }, 400);
+  }
+
+  return c.json({ data: { retweeted: true } });
+});
+
+/** DELETE /api/tweets/:id/retweet */
+engagement.delete("/:id/retweet", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.unretweet(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to unretweet" }, 400);
+  }
+
+  return c.json({ data: { retweeted: false } });
+});
+
+/** POST /api/tweets/:id/bookmark */
+engagement.post("/:id/bookmark", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.bookmark(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to bookmark" }, 400);
+  }
+
+  return c.json({ data: { bookmarked: true } });
+});
+
+/** DELETE /api/tweets/:id/bookmark */
+engagement.delete("/:id/bookmark", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.unbookmark(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to unbookmark" }, 400);
+  }
+
+  return c.json({ data: { bookmarked: false } });
+});
+
+export { engagement };

package/src/server/routes/follow.ts

@@ -0,0 +1,32 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const follow = new Hono<XbirdEnv>();
+
+/** POST /api/users/:handle/follow */
+follow.post("/:handle/follow", async (c) => {
+  const client = c.get("xClient");
+  const handle = c.req.param("handle");
+
+  const result = await client.follow(handle);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to follow" }, 400);
+  }
+
+  return c.json({ data: { following: true } });
+});
+
+/** DELETE /api/users/:handle/follow */
+follow.delete("/:handle/follow", async (c) => {
+  const client = c.get("xClient");
+  const handle = c.req.param("handle");
+
+  const result = await client.unfollow(handle);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to unfollow" }, 400);
+  }
+
+  return c.json({ data: { following: false } });
+});
+
+export { follow };

package/src/server/routes/health.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+
+const health = new Hono();
+
+health.get("/health", (c) => {
+  return c.json({
+    status: "ok",
+    service: "xbird",
+    version: "0.1.0",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+export { health };

package/src/server/routes/lists.ts

@@ -0,0 +1,38 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const lists = new Hono<XbirdEnv>();
+
+/** GET /api/lists — get owned + membership lists */
+lists.get("/", async (c) => {
+  const client = c.get("xClient");
+
+  const [owned, memberships] = await Promise.all([
+    client.getOwnedLists(),
+    client.getListMemberships(),
+  ]);
+
+  return c.json({
+    data: {
+      owned: owned.success ? owned.lists : [],
+      memberships: memberships.success ? memberships.lists : [],
+    },
+  });
+});
+
+/** GET /api/lists/:id/tweets — get list timeline */
+lists.get("/:id/tweets", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getListTimeline(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch list timeline" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+export { lists };

package/src/server/routes/media.ts

@@ -0,0 +1,44 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const media = new Hono<XbirdEnv>();
+
+/** POST /api/media — upload media (multipart/form-data or raw binary) */
+media.post("/", async (c) => {
+  const client = c.get("xClient");
+  const contentType = c.req.header("content-type") ?? "";
+
+  let data: Uint8Array;
+  let mimeType: string;
+  let alt: string | undefined;
+
+  if (contentType.includes("multipart/form-data")) {
+    const formData = await c.req.formData();
+    const file = formData.get("file");
+    if (!file || !(file instanceof File)) {
+      return c.json({ error: "file field is required (multipart)" }, 400);
+    }
+    data = new Uint8Array(await file.arrayBuffer());
+    mimeType = file.type || "image/png";
+    const altField = formData.get("alt");
+    alt = altField ? altField.toString() : undefined;
+  } else {
+    // Raw binary upload — mimeType from Content-Type header
+    data = new Uint8Array(await c.req.arrayBuffer());
+    mimeType = contentType.split(";")[0]?.trim() || "image/png";
+    alt = c.req.header("x-alt-text") ?? undefined;
+  }
+
+  if (data.length === 0) {
+    return c.json({ error: "Empty file" }, 400);
+  }
+
+  const result = await client.uploadMedia({ data, mimeType, alt });
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Upload failed" }, 400);
+  }
+
+  return c.json({ data: { mediaId: result.mediaId } }, 201);
+});
+
+export { media };

package/src/server/routes/mentions.ts

@@ -0,0 +1,20 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const mentions = new Hono<XbirdEnv>();
+
+/** GET /api/mentions/:handle?count=... */
+mentions.get("/:handle", async (c) => {
+  const client = c.get("xClient");
+  const handle = c.req.param("handle");
+  const count = Number(c.req.query("count") ?? 20);
+
+  const result = await client.mentions(handle, count);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch mentions" }, 400);
+  }
+
+  return c.json({ data: result.tweets });
+});
+
+export { mentions };

package/src/server/routes/news.ts

@@ -0,0 +1,23 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const news = new Hono<XbirdEnv>();
+
+/** GET /api/news?count=...&tab=...&aiOnly=...&withTweets=...&trendingOnly=... */
+news.get("/", async (c) => {
+  const client = c.get("xClient");
+  const count = Number(c.req.query("count") ?? 20);
+  const tab = c.req.query("tab");
+  const aiOnly = c.req.query("aiOnly") === "true";
+  const withTweets = c.req.query("withTweets") === "true";
+  const trendingOnly = c.req.query("trendingOnly") === "true";
+
+  const result = await client.getNews(count, { tab, aiOnly, withTweets, trendingOnly });
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch news" }, 400);
+  }
+
+  return c.json({ data: result.items });
+});
+
+export { news };

package/src/server/routes/search.ts

@@ -0,0 +1,26 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const search = new Hono<XbirdEnv>();
+
+/** GET /api/search?q=...&count=...&cursor=... */
+search.get("/", async (c) => {
+  const client = c.get("xClient");
+  const q = c.req.query("q");
+
+  if (!q) {
+    return c.json({ error: "q query parameter is required" }, 400);
+  }
+
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.search(q, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Search failed" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+export { search };

package/src/server/routes/timeline.ts

@@ -0,0 +1,21 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const timeline = new Hono<XbirdEnv>();
+
+/** GET /api/timeline/home?count=...&cursor=...&following=true */
+timeline.get("/home", async (c) => {
+  const client = c.get("xClient");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+  const following = c.req.query("following") === "true";
+
+  const result = await client.home(count, cursor, following);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch timeline" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+export { timeline };

package/src/server/routes/tweets.ts

@@ -0,0 +1,82 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const tweets = new Hono<XbirdEnv>();
+
+/** GET /api/tweets/:id — fetch a single tweet */
+tweets.get("/:id", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.getTweet(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Tweet not found" }, 404);
+  }
+
+  return c.json({ data: result.tweet });
+});
+
+/** GET /api/tweets/:id/thread — fetch tweet thread */
+tweets.get("/:id/thread", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+
+  const result = await client.getThread(id);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Thread not found" }, 404);
+  }
+
+  return c.json({ data: result.tweets });
+});
+
+/** GET /api/tweets/:id/replies — fetch replies to a tweet */
+tweets.get("/:id/replies", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getReplies(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch replies" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+/** POST /api/tweets — create a new tweet */
+tweets.post("/", async (c) => {
+  const client = c.get("xClient");
+  const body = await c.req.json<{ text: string; mediaIds?: string[] }>();
+
+  if (!body.text) {
+    return c.json({ error: "text is required" }, 400);
+  }
+
+  const result = await client.tweet(body.text, body.mediaIds);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to post tweet" }, 400);
+  }
+
+  return c.json({ data: { tweetId: result.tweetId } }, 201);
+});
+
+/** POST /api/tweets/:id/reply — reply to a tweet */
+tweets.post("/:id/reply", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const body = await c.req.json<{ text: string; mediaIds?: string[] }>();
+
+  if (!body.text) {
+    return c.json({ error: "text is required" }, 400);
+  }
+
+  const result = await client.reply(body.text, id, body.mediaIds);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to reply" }, 400);
+  }
+
+  return c.json({ data: { tweetId: result.tweetId } }, 201);
+});
+
+export { tweets };

package/src/server/routes/users.ts

@@ -0,0 +1,92 @@
+import { Hono } from "hono";
+import type { XbirdEnv } from "../middleware/account-pool.ts";
+
+const users = new Hono<XbirdEnv>();
+
+/** GET /api/users/:handle — get user profile by handle */
+users.get("/:handle", async (c) => {
+  const client = c.get("xClient");
+  const handle = c.req.param("handle");
+
+  const result = await client.getUserByHandle(handle);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "User not found" }, 404);
+  }
+
+  return c.json({ data: result.user });
+});
+
+/** GET /api/users/:handle/about — get user about info */
+users.get("/:handle/about", async (c) => {
+  const client = c.get("xClient");
+  const handle = c.req.param("handle");
+
+  const result = await client.getAbout(handle);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "About info not found" }, 404);
+  }
+
+  return c.json({ data: result.about });
+});
+
+/** GET /api/users/:id/tweets — get user's tweets by user ID */
+users.get("/:id/tweets", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getUserTweets(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch tweets" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+/** GET /api/users/:id/followers — get user's followers */
+users.get("/:id/followers", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getFollowers(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch followers" }, 400);
+  }
+
+  return c.json({ data: result.users, cursor: result.cursor });
+});
+
+/** GET /api/users/:id/following — get user's following */
+users.get("/:id/following", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getFollowing(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch following" }, 400);
+  }
+
+  return c.json({ data: result.users, cursor: result.cursor });
+});
+
+/** GET /api/users/:id/likes — get user's liked tweets */
+users.get("/:id/likes", async (c) => {
+  const client = c.get("xClient");
+  const id = c.req.param("id");
+  const count = Number(c.req.query("count") ?? 20);
+  const cursor = c.req.query("cursor");
+
+  const result = await client.getLikes(id, count, cursor);
+  if (!result.success) {
+    return c.json({ error: result.error ?? "Failed to fetch likes" }, 400);
+  }
+
+  return c.json({ data: result.tweets, cursor: result.cursor });
+});
+
+export { users };

package/src/server/storage/accounts-db.ts

@@ -0,0 +1,84 @@
+import { Database } from "bun:sqlite";
+import { chmodSync } from "node:fs";
+
+export interface RegisteredAccount {
+  wallet_address: string;
+  auth_token: string;
+  ct0: string;
+  twitter_username: string | null;
+  registered_at: number;
+  last_used_at: number | null;
+}
+
+export class AccountsDB {
+  private db: Database;
+
+  constructor(dbPath: string = "xbird-accounts.db") {
+    this.db = new Database(dbPath, { strict: true });
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS registered_accounts (
+        wallet_address TEXT PRIMARY KEY,
+        auth_token TEXT NOT NULL,
+        ct0 TEXT NOT NULL,
+        twitter_username TEXT,
+        registered_at INTEGER NOT NULL,
+        last_used_at INTEGER
+      )
+    `);
+    // Restrict DB file permissions to owner-only (0600)
+    if (dbPath !== ":memory:") {
+      try {
+        chmodSync(dbPath, 0o600);
+        chmodSync(`${dbPath}-wal`, 0o600);
+        chmodSync(`${dbPath}-shm`, 0o600);
+      } catch {
+        // WAL/SHM files may not exist yet
+      }
+    }
+  }
+
+  /** Register or update Twitter credentials for a wallet */
+  register(wallet: string, authToken: string, ct0: string, username?: string): void {
+    wallet = wallet.toLowerCase();
+    const now = Date.now();
+    this.db.run(
+      `INSERT INTO registered_accounts (wallet_address, auth_token, ct0, twitter_username, registered_at, last_used_at)
+       VALUES (?, ?, ?, ?, ?, NULL)
+       ON CONFLICT(wallet_address) DO UPDATE SET
+         auth_token = excluded.auth_token,
+         ct0 = excluded.ct0,
+         twitter_username = COALESCE(excluded.twitter_username, registered_accounts.twitter_username),
+         last_used_at = NULL`,
+      [wallet, authToken, ct0, username ?? null, now],
+    );
+  }
+
+  /** Look up credentials for a wallet */
+  lookup(wallet: string): RegisteredAccount | null {
+    return this.db.query<RegisteredAccount, [string]>(
+      "SELECT * FROM registered_accounts WHERE wallet_address = ?",
+    ).get(wallet.toLowerCase());
+  }
+
+  /** Remove a registered account */
+  remove(wallet: string): boolean {
+    const result = this.db.run(
+      "DELETE FROM registered_accounts WHERE wallet_address = ?",
+      [wallet.toLowerCase()],
+    );
+    return result.changes > 0;
+  }
+
+  /** Touch the last_used_at timestamp */
+  updateLastUsed(wallet: string): void {
+    this.db.run(
+      "UPDATE registered_accounts SET last_used_at = ? WHERE wallet_address = ?",
+      [Date.now(), wallet.toLowerCase()],
+    );
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/server.ts

@@ -0,0 +1,34 @@
+import { AccountsDB } from "./server/storage/accounts-db.ts";
+import { createApp } from "./server/app.ts";
+import { NETWORK, FACILITATOR_URL } from "./server/config/pricing.ts";
+
+const PORT = Number(process.env.PORT ?? 3402);
+const PAY_TO = process.env.XBIRD_PAY_TO_ADDRESS;
+const isMainnet = process.env.XBIRD_NETWORK === "mainnet";
+const DB_PATH = process.env.XBIRD_DB_PATH ?? "xbird-accounts.db";
+
+if (!PAY_TO) {
+  console.error("XBIRD_PAY_TO_ADDRESS env is required (your USDC wallet on Base)");
+  process.exit(1);
+}
+
+if (isMainnet && !process.env.CDP_API_KEY_ID) {
+  console.warn("WARNING: Mainnet mode requires CDP_API_KEY_ID and CDP_API_KEY_SECRET for the facilitator");
+}
+
+const accountsDb = new AccountsDB(DB_PATH);
+
+const app = createApp(PAY_TO, accountsDb);
+
+console.log(`xbird API server starting on port ${PORT} (BYOA mode)`);
+console.log(`  Network: ${NETWORK} (${isMainnet ? "MAINNET" : "testnet"})`);
+console.log(`  Facilitator: ${FACILITATOR_URL}`);
+console.log(`  Accounts DB: ${DB_PATH}`);
+console.log(`  Pay-to address: ${PAY_TO}`);
+console.log(`  Health: http://localhost:${PORT}/health`);
+console.log(`  Agent card: http://localhost:${PORT}/.well-known/agent.json`);
+
+export default {
+  port: PORT,
+  fetch: app.fetch,
+};

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}