@realaman90/x-mcp 2.0.2 → 2.1.0

package/README.md

@@ -3,50 +3,80 @@
 [![npm version](https://img.shields.io/npm/v/@realaman90/x-mcp)](https://www.npmjs.com/package/@realaman90/x-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search, read, post, like, retweet, follow, bookmark, and more.
+MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search, read, post, like, retweet, follow, bookmark, manage lists, explore communities, and more.
 
-**27 tools total**: 8 read-only (Bearer token) + 19 write/advanced-read (OAuth 1.0a).
+**44 tools total**: 17 read-only (Bearer token) + 27 write/advanced-read (OAuth 1.0a).
 
 ## Why
 
 - Search and analyze tweets without leaving your AI workflow
 - Post, reply, quote-tweet, and run polls directly from Claude
 - Like, retweet, follow, bookmark, block, mute — all from your terminal
+- Manage X Lists — create, update, add/remove members, pin/unpin
+- Explore Communities, trending topics, and news
+- Upload images and attach them to tweets
+- Monitor your API usage
 - Works with Claude Code, Claude Desktop, Codex, or any MCP client
 - OAuth credentials optional — runs read-only with just a Bearer token
 
 ## Tools
 
-### Always available (Bearer token only) — 8 tools
+### Always available (Bearer token only) — 17 tools
 
 | Tool | Description |
 |------|-------------|
+| **Tweets** | |
 | `search_tweets` | Search recent tweets (last 7 days) with full query operators |
 | `get_user_profile` | Get user profile by username (bio, followers, etc.) |
 | `get_user_tweets` | Get a user's recent tweets by user ID |
 | `get_tweet_replies` | Get replies to a specific tweet |
 | `get_tweet` | Get a single tweet with full details and metrics |
+| **Users** | |
 | `get_user_followers` | Get a user's followers |
 | `get_user_following` | Get who a user is following |
 | `get_liking_users` | Get users who liked a tweet |
-
-### Requires OAuth 1.0a — 19 tools (auto-registered when credentials present)
+| **Trends** | |
+| `get_trending_topics` | Get trending topics by location (WOEID) |
+| **Communities** | |
+| `get_community` | Get details for a specific community |
+| `search_communities` | Search communities by keyword |
+| **News** | |
+| `get_news` | Get a news article/cluster by ID |
+| **Usage** | |
+| `get_api_usage` | Get your API tweet consumption stats |
+| **Lists** | |
+| `get_list` | Get list details by ID |
+| `get_user_lists` | Get lists owned by a user |
+| `get_list_members` | Get members of a list |
+| `get_user_list_memberships` | Get lists a user belongs to |
+
+### Requires OAuth 1.0a — 27 tools (auto-registered when credentials present)
 
 | Tool | Description |
 |------|-------------|
+| **Read** | |
 | `get_my_profile` | Get your own profile |
 | `get_user_mentions` | Get tweets mentioning a user |
 | `get_quote_tweets` | Get quote tweets of a tweet |
 | `get_bookmarks` | Get your bookmarked tweets |
-| `get_trending_topics` | Get trending topics by location |
-| `create_post` | Post a tweet (text, reply, quote, poll) |
+| **Post** | |
+| `upload_media` | Upload an image (from URL) for use in tweets |
+| `create_post` | Post a tweet (text, reply, quote, poll, media) |
 | `delete_post` | Delete your own tweet |
+| **Engage** | |
 | `like_post` / `unlike_post` | Like or unlike a tweet |
 | `repost` / `unrepost` | Retweet or undo retweet |
 | `follow_user` / `unfollow_user` | Follow or unfollow a user |
 | `bookmark_post` / `unbookmark_post` | Bookmark or remove bookmark |
 | `block_user` / `unblock_user` | Block or unblock a user |
 | `mute_user` / `unmute_user` | Mute or unmute a user |
+| **Lists** | |
+| `create_list` | Create a new list |
+| `update_list` | Update list name/description/privacy |
+| `delete_list` | Delete a list you own |
+| `add_list_member` | Add a user to your list |
+| `remove_list_member` | Remove a user from your list |
+| `pin_list` / `unpin_list` | Pin or unpin a list |
 
 ## Quick Start
 
@@ -59,7 +89,7 @@ MCP server for X/Twitter API — give Claude (or any MCP client) the ability to
    - Copy the **API Key** and **API Secret** (for write access)
    - Generate and copy the **Access Token** and **Access Token Secret** (for write access)
 
-> **Read-only mode**: Only the Bearer Token is required. The 8 read tools work without OAuth.
+> **Read-only mode**: Only the Bearer Token is required. The 17 read tools work without OAuth.
 
 ### 2. Add to Claude Code
 
@@ -145,6 +175,13 @@ Like tweet 1234567890
 Retweet the latest tweet from @username
 ```
 
+### Lists
+```
+Create a private list called "AI Builders"
+Add @username to my "AI Builders" list
+Show me the members of list 123456
+```
+
 ### Chain tools
 1. `get_user_profile` → get user ID from username
 2. `get_user_tweets` → get their recent tweets
@@ -168,10 +205,10 @@ Retweet the latest tweet from @username
 
 ## How It Works
 
-Single-file MCP server (~430 lines). No build step, no config files, zero extra dependencies. Uses Node.js built-in `crypto` for OAuth signing.
+Single-file MCP server (~720 lines). No build step, no config files, zero extra dependencies. Uses Node.js built-in `crypto` for OAuth signing.
 
 ```
-Claude ↔ stdio ↔ x-mcp ↔ X API v1.1/v2
+Claude ↔ stdio ↔ x-mcp ↔ X API v2
                     ↑
           Bearer (read) + OAuth 1.0a (write)
 ```

package/index.js

@@ -35,6 +35,8 @@ const HAS_OAUTH = !!(OAUTH.consumerKey && OAUTH.consumerSecret && OAUTH.token &&
 
 const TWEET_FIELDS = "created_at,public_metrics,author_id,conversation_id,in_reply_to_user_id,lang";
 const USER_FIELDS = "created_at,description,public_metrics,profile_image_url,url,verified";
+const LIST_FIELDS = "created_at,description,follower_count,member_count,owner_id,private";
+const COMMUNITY_FIELDS = "name,description,member_count,created_at,is_private";
 
 // ─── Bearer fetch (read-only, no user context) ────────────────────────────────
 
@@ -95,7 +97,7 @@ function oauthSign(method, url, queryParams = {}) {
 async function xapiAuth(method, endpoint, body) {
   const isV1 = endpoint.startsWith("/1.1/");
   const base = isV1 ? "https://api.x.com" : "https://api.x.com/2";
-  const fullUrl = `${base}${isV1 ? endpoint : endpoint}`;
+  const fullUrl = `${base}${endpoint}`;
 
   // Parse any query params from endpoint for signing
   const urlObj = new URL(fullUrl);
@@ -123,6 +125,23 @@ async function xapiAuth(method, endpoint, body) {
   return res.json();
 }
 
+// ─── OAuth multipart upload ────────────────────────────────────────────────────
+
+async function xapiUpload(formData) {
+  const url = "https://upload.x.com/2/media/upload";
+  const authHeader = oauthSign("POST", url);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { Authorization: authHeader },
+    body: formData,
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`X API upload ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
 // ─── Cached authenticated user ID ──────────────────────────────────────────────
 
 let _myUserId = null;
@@ -137,7 +156,7 @@ async function getMyUserId() {
 
 const server = new McpServer({
   name: "x-mcp",
-  version: "2.0.0",
+  version: "2.1.0",
 });
 
 const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
@@ -146,6 +165,8 @@ const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, nul
 // BEARER-ONLY TOOLS (always registered)
 // ═══════════════════════════════════════════════════════════════════════════════
 
+// ─── Tweets ──────────────────────────────────────────────────────────────────
+
 // 1. Search tweets
 server.tool(
   "search_tweets",
@@ -228,6 +249,8 @@ server.tool(
   }
 );
 
+// ─── Users ───────────────────────────────────────────────────────────────────
+
 // 6. Get user's followers
 server.tool(
   "get_user_followers",
@@ -279,6 +302,146 @@ server.tool(
   }
 );
 
+// ─── Trends ──────────────────────────────────────────────────────────────────
+
+// 9. Get trending topics (v2)
+server.tool(
+  "get_trending_topics",
+  "Get current trending topics for a location. Default WOEID 1 = worldwide, 23424977 = US, 23424975 = UK.",
+  {
+    woeid: z.number().default(1).describe("Where On Earth ID (1=worldwide, 23424977=US, 23424975=UK)"),
+  },
+  async ({ woeid }) => {
+    const data = await xapi(`/trends/by/woeid/${woeid}`);
+    return ok(data);
+  }
+);
+
+// ─── Communities ─────────────────────────────────────────────────────────────
+
+// 10. Get community
+server.tool(
+  "get_community",
+  "Get details for a specific X Community by ID. Returns name, description, member count, and privacy status.",
+  { community_id: z.string().describe("Community ID") },
+  async ({ community_id }) => {
+    const data = await xapi(`/communities/${community_id}`, {
+      "community.fields": COMMUNITY_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// 11. Search communities
+server.tool(
+  "search_communities",
+  "Search for X Communities by keyword.",
+  {
+    query: z.string().describe("Search query for communities"),
+    max_results: z.number().min(1).max(100).default(10).describe("Number of results (1-100)"),
+  },
+  async ({ query, max_results }) => {
+    const data = await xapi("/communities/search", {
+      query,
+      max_results,
+      "community.fields": COMMUNITY_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// ─── News ────────────────────────────────────────────────────────────────────
+
+// 12. Get news
+server.tool(
+  "get_news",
+  "Get a news article/cluster by ID from X. Returns contexts and related posts.",
+  { news_id: z.string().describe("News ID") },
+  async ({ news_id }) => {
+    const data = await xapi(`/news/${news_id}`, {
+      "news.fields": "contexts,cluster_posts_results",
+    });
+    return ok(data);
+  }
+);
+
+// ─── Usage ───────────────────────────────────────────────────────────────────
+
+// 13. Get API usage
+server.tool(
+  "get_api_usage",
+  "Get your X API tweet consumption usage. Shows daily usage, app ID, and project cap.",
+  {},
+  async () => {
+    const data = await xapi("/usage/tweets");
+    return ok(data);
+  }
+);
+
+// ─── Lists (read) ────────────────────────────────────────────────────────────
+
+// 14. Get list
+server.tool(
+  "get_list",
+  "Get details for a specific X List by ID. Returns name, description, member/follower counts, and privacy status.",
+  { list_id: z.string().describe("List ID") },
+  async ({ list_id }) => {
+    const data = await xapi(`/lists/${list_id}`, { "list.fields": LIST_FIELDS });
+    return ok(data);
+  }
+);
+
+// 15. Get user's owned lists
+server.tool(
+  "get_user_lists",
+  "Get all Lists owned by a user. Use get_user_profile first to get the user ID.",
+  {
+    user_id: z.string().describe("X user ID (numeric string)"),
+    max_results: z.number().min(1).max(100).default(100).describe("Number of results (1-100)"),
+  },
+  async ({ user_id, max_results }) => {
+    const data = await xapi(`/users/${user_id}/owned_lists`, {
+      max_results,
+      "list.fields": LIST_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// 16. Get list members
+server.tool(
+  "get_list_members",
+  "Get all members of a specific X List.",
+  {
+    list_id: z.string().describe("List ID"),
+    max_results: z.number().min(1).max(100).default(100).describe("Number of results (1-100)"),
+  },
+  async ({ list_id, max_results }) => {
+    const data = await xapi(`/lists/${list_id}/members`, {
+      max_results,
+      "user.fields": USER_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// 17. Get user's list memberships
+server.tool(
+  "get_user_list_memberships",
+  "Get all Lists a user is a member of. Use get_user_profile first to get the user ID.",
+  {
+    user_id: z.string().describe("X user ID (numeric string)"),
+    max_results: z.number().min(1).max(100).default(100).describe("Number of results (1-100)"),
+  },
+  async ({ user_id, max_results }) => {
+    const data = await xapi(`/users/${user_id}/list_memberships`, {
+      max_results,
+      "list.fields": LIST_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // OAUTH TOOLS (only registered when OAuth credentials are present)
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -287,7 +450,7 @@ if (HAS_OAUTH) {
 
   // ─── OAuth Read Tools ──────────────────────────────────────────────────────
 
-  // 9. Get my profile
+  // 18. Get my profile
   server.tool(
     "get_my_profile",
     "Get the authenticated user's own profile. Requires OAuth — returns your user ID, bio, metrics, etc.",
@@ -298,7 +461,7 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 10. Get user mentions
+  // 19. Get user mentions
   server.tool(
     "get_user_mentions",
     "Get recent tweets mentioning a specific user. Requires OAuth for user-context access.",
@@ -315,7 +478,7 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 11. Get quote tweets
+  // 20. Get quote tweets
   server.tool(
     "get_quote_tweets",
     "Get tweets that quote a specific tweet. Requires OAuth for user-context access.",
@@ -332,7 +495,7 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 12. Get bookmarks
+  // 21. Get bookmarks
   server.tool(
     "get_bookmarks",
     "Get the authenticated user's bookmarked tweets. Bearer token is explicitly forbidden for this endpoint.",
@@ -349,36 +512,50 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 13. Get trending topics
+  // ─── OAuth Write Tools ─────────────────────────────────────────────────────
+
+  // 22. Upload media
   server.tool(
-    "get_trending_topics",
-    "Get current trending topics for a location. Uses v1.1 API. Default WOEID 1 = worldwide, 23424977 = US.",
+    "upload_media",
+    "Upload an image for use in tweets. Pass a publicly accessible URL — the image will be downloaded and uploaded to X. Returns a media_id to use with create_post. Max 5MB for images, 15MB for GIFs.",
     {
-      woeid: z.number().default(1).describe("Where On Earth ID (1=worldwide, 23424977=US, 23424975=UK)"),
+      media_url: z.string().describe("Public URL of the image to upload"),
+      media_category: z.enum(["tweet_image", "dm_image"]).default("tweet_image").describe("Media category"),
     },
-    async ({ woeid }) => {
-      const data = await xapiAuth("GET", `/1.1/trends/place.json?id=${woeid}`, null);
+    async ({ media_url, media_category }) => {
+      // Download the image
+      const imgRes = await fetch(media_url);
+      if (!imgRes.ok) throw new Error(`Failed to download image: ${imgRes.status}`);
+      const blob = await imgRes.blob();
+      const contentType = imgRes.headers.get("content-type") || "image/jpeg";
+
+      // Upload via multipart
+      const formData = new FormData();
+      formData.append("media", blob, { type: contentType });
+      formData.append("media_category", media_category);
+
+      const data = await xapiUpload(formData);
       return ok(data);
     }
   );
 
-  // ─── OAuth Write Tools ─────────────────────────────────────────────────────
-
-  // 14. Create post (most complex write tool)
+  // 23. Create post (supports text, reply, quote, poll, media)
   server.tool(
     "create_post",
-    "Create a new tweet/post on X. Supports text, replies, quote tweets, and polls. Max 280 characters for text.",
+    "Create a new tweet/post on X. Supports text, replies, quote tweets, polls, and media attachments. Max 280 characters for text.",
     {
       text: z.string().max(280).describe("Tweet text (max 280 characters)"),
       reply_to: z.string().optional().describe("Tweet ID to reply to (makes this a reply)"),
       quote_tweet_id: z.string().optional().describe("Tweet ID to quote (makes this a quote tweet)"),
+      media_ids: z.array(z.string()).min(1).max(4).optional().describe("Media IDs from upload_media (1-4 images)"),
       poll_options: z.array(z.string()).min(2).max(4).optional().describe("Poll options (2-4 choices). Creates a poll attached to the tweet."),
       poll_duration_minutes: z.number().min(5).max(10080).optional().describe("Poll duration in minutes (5-10080, default 1440 = 24h). Only used with poll_options."),
     },
-    async ({ text, reply_to, quote_tweet_id, poll_options, poll_duration_minutes }) => {
+    async ({ text, reply_to, quote_tweet_id, media_ids, poll_options, poll_duration_minutes }) => {
       const body = { text };
       if (reply_to) body.reply = { in_reply_to_tweet_id: reply_to };
       if (quote_tweet_id) body.quote_tweet_id = quote_tweet_id;
+      if (media_ids) body.media = { media_ids };
       if (poll_options) {
         body.poll = {
           options: poll_options,
@@ -390,7 +567,7 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 15. Delete post
+  // 24. Delete post
   server.tool(
     "delete_post",
     "Delete one of your own tweets by ID. This action is irreversible.",
@@ -401,7 +578,110 @@ if (HAS_OAUTH) {
     }
   );
 
-  // 16-27. Toggle tools (like/unlike, repost/unrepost, etc.)
+  // ─── Lists (write) ────────────────────────────────────────────────────────
+
+  // 25. Create list
+  server.tool(
+    "create_list",
+    "Create a new X List.",
+    {
+      name: z.string().max(25).describe("List name (max 25 characters)"),
+      description: z.string().max(100).optional().describe("List description (max 100 characters)"),
+      private: z.boolean().default(false).describe("Whether the list is private"),
+    },
+    async ({ name, description, private: isPrivate }) => {
+      const body = { name, private: isPrivate };
+      if (description) body.description = description;
+      const data = await xapiAuth("POST", "/lists", body);
+      return ok(data);
+    }
+  );
+
+  // 26. Update list
+  server.tool(
+    "update_list",
+    "Update an existing X List's name, description, or privacy.",
+    {
+      list_id: z.string().describe("List ID to update"),
+      name: z.string().max(25).optional().describe("New list name"),
+      description: z.string().max(100).optional().describe("New list description"),
+      private: z.boolean().optional().describe("Whether the list is private"),
+    },
+    async ({ list_id, name, description, private: isPrivate }) => {
+      const body = {};
+      if (name !== undefined) body.name = name;
+      if (description !== undefined) body.description = description;
+      if (isPrivate !== undefined) body.private = isPrivate;
+      const data = await xapiAuth("PUT", `/lists/${list_id}`, body);
+      return ok(data);
+    }
+  );
+
+  // 27. Delete list
+  server.tool(
+    "delete_list",
+    "Delete an X List you own. This action is irreversible.",
+    { list_id: z.string().describe("List ID to delete") },
+    async ({ list_id }) => {
+      const data = await xapiAuth("DELETE", `/lists/${list_id}`, null);
+      return ok(data);
+    }
+  );
+
+  // 28. Add list member
+  server.tool(
+    "add_list_member",
+    "Add a user to an X List you own.",
+    {
+      list_id: z.string().describe("List ID"),
+      user_id: z.string().describe("User ID to add"),
+    },
+    async ({ list_id, user_id }) => {
+      const data = await xapiAuth("POST", `/lists/${list_id}/members`, { user_id });
+      return ok(data);
+    }
+  );
+
+  // 29. Remove list member
+  server.tool(
+    "remove_list_member",
+    "Remove a user from an X List you own.",
+    {
+      list_id: z.string().describe("List ID"),
+      user_id: z.string().describe("User ID to remove"),
+    },
+    async ({ list_id, user_id }) => {
+      const data = await xapiAuth("DELETE", `/lists/${list_id}/members/${user_id}`, null);
+      return ok(data);
+    }
+  );
+
+  // 30. Pin list
+  server.tool(
+    "pin_list",
+    "Pin an X List to your profile.",
+    { list_id: z.string().describe("List ID to pin") },
+    async ({ list_id }) => {
+      const myId = await getMyUserId();
+      const data = await xapiAuth("POST", `/users/${myId}/pinned_lists`, { list_id });
+      return ok(data);
+    }
+  );
+
+  // 31. Unpin list
+  server.tool(
+    "unpin_list",
+    "Unpin an X List from your profile.",
+    { list_id: z.string().describe("List ID to unpin") },
+    async ({ list_id }) => {
+      const myId = await getMyUserId();
+      const data = await xapiAuth("DELETE", `/users/${myId}/pinned_lists/${list_id}`, null);
+      return ok(data);
+    }
+  );
+
+  // ─── Toggle tools (like/unlike, repost/unrepost, etc.) ─────────────────────
+
   const toggleTools = [
     ["like_post",       "Like a tweet",                         "POST",   (me) => `/users/${me}/likes`,                "tweet_id", (id) => ({ tweet_id: id })],
     ["unlike_post",     "Unlike a previously liked tweet",      "DELETE", (me) => `/users/${me}/likes/${"{id}"}`,      "tweet_id", null],
@@ -437,9 +717,10 @@ if (HAS_OAUTH) {
 
 // ─── Start server ──────────────────────────────────────────────────────────────
 
+const toolCount = HAS_OAUTH ? 44 : 17;
 if (!HAS_OAUTH) {
-  console.error("OAuth credentials not found — running with 8 read-only tools (Bearer token only)");
-  console.error("Set X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET for full 27-tool access");
+  console.error("OAuth credentials not found — running with 17 read-only tools (Bearer token only)");
+  console.error("Set X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET for full 44-tool access");
 }
 
 const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realaman90/x-mcp",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "MCP server for X/Twitter API — read tweets, profiles, timelines + write posts, likes, retweets, follows, bookmarks, and more",
   "type": "module",
   "main": "index.js",