@realaman90/x-mcp 1.0.0 → 2.0.0

package/README.md

@@ -1,38 +1,65 @@
 # x-mcp
 
-MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search tweets, read profiles, get timelines, and read replies.
+[![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)
 
-**Read-only. No posting, liking, or following. Safe to use with AI agents.**
+MCP server for X/Twitter API — give Claude (or any MCP client) the ability to search, read, post, like, retweet, follow, bookmark, and more.
+
+**27 tools total**: 8 read-only (Bearer token) + 19 write/advanced-read (OAuth 1.0a).
 
 ## Why
 
-- Find engagement opportunities on X without leaving Claude
-- Study reply patterns and conversations around any topic
-- Research accounts, their content, and audience reactions
-- All read-only — no risk of accidental tweets or follows
+- 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
+- Works with Claude Code, Claude Desktop, Codex, or any MCP client
+- OAuth credentials optional — runs read-only with just a Bearer token
 
 ## Tools
 
-| Tool | Description | X API Endpoint |
-|------|-------------|----------------|
-| `search_tweets` | Search recent tweets (last 7 days) with full query operators | `GET /2/tweets/search/recent` |
-| `get_user_profile` | Get user profile by username (bio, followers, etc.) | `GET /2/users/by/username/{username}` |
-| `get_user_tweets` | Get a user's recent tweets by user ID | `GET /2/users/{id}/tweets` |
-| `get_tweet_replies` | Get replies to a specific tweet | Search `conversation_id:{id}` |
-| `get_tweet` | Get a single tweet with full details and metrics | `GET /2/tweets/{id}` |
+### Always available (Bearer token only) — 8 tools
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+| `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)
+
+| Tool | Description |
+|------|-------------|
+| `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) |
+| `delete_post` | Delete your own tweet |
+| `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 |
 
 ## Quick Start
 
-### 1. Get an X API Bearer Token
+### 1. Get X API credentials
 
-1. Go to [developer.x.com](https://developer.x.com) and sign in
-2. Click **Developer Portal** → **Projects & Apps**
-3. Create a new **Project** (any name)
-4. Create an **App** inside the project
-5. Go to **Keys and Tokens** → generate a **Bearer Token**
-6. Copy the token — you'll need it in step 2
+1. Go to [developer.x.com](https://developer.x.com) → **Developer Portal** → **Projects & Apps**
+2. Create a **Project** and an **App** inside it
+3. Go to **Keys and Tokens**:
+   - Copy the **Bearer Token** (required)
+   - Copy the **API Key** and **API Secret** (for write access)
+   - Generate and copy the **Access Token** and **Access Token Secret** (for write access)
 
-> The **Basic** tier ($200/mo pay-per-usage) is sufficient. Free tier works too but has lower rate limits.
+> **Read-only mode**: Only the Bearer Token is required. The 8 read tools work without OAuth.
 
 ### 2. Add to Claude Code
 
@@ -44,18 +71,22 @@ Add to `~/.claude/settings.json`:
     "x": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "x-mcp"],
+      "args": ["-y", "@realaman90/x-mcp"],
       "env": {
-        "X_BEARER_TOKEN": "your-bearer-token"
+        "X_BEARER_TOKEN": "your-bearer-token",
+        "X_API_KEY": "your-api-key",
+        "X_API_SECRET": "your-api-secret",
+        "X_ACCESS_TOKEN": "your-access-token",
+        "X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
       }
     }
   }
 }
 ```
 
-### Or add to Claude Desktop
+Or add to **Claude Desktop**: **Settings** → **Developer** → **Edit Config** → same block.
 
-Open **Settings** → **Developer** → **Edit Config** and add the same block above.
+> Omit the `X_API_KEY`/`X_API_SECRET`/`X_ACCESS_TOKEN`/`X_ACCESS_TOKEN_SECRET` lines for read-only mode.
 
 ### 3. Restart Claude and test
 
@@ -63,41 +94,101 @@ Open **Settings** → **Developer** → **Edit Config** and add the same block a
 Search X for "AI agents" in English, no retweets
 ```
 
-Claude will use the `search_tweets` tool automatically.
+```
+Post a tweet: "Hello from Claude!"
+```
+
+## Team Setup (sharing your app with others)
+
+If you want a colleague to use your X app but post from **their own account**:
+
+### App owner (one-time)
+
+1. In [X Developer Portal](https://developer.x.com) → your app → **Authentication Settings**:
+   - App permissions: **Read and write**
+   - Type of App: **Web App, Automated App or Bot**
+   - Callback URL: `http://localhost:3456/callback`
+2. Share your **API Key**, **API Secret**, and **Bearer Token** with your colleague
+
+### Colleague (one-time)
+
+```bash
+npx @realaman90/x-mcp --setup
+```
+
+Or if running from source:
+
+```bash
+X_API_KEY=<app_api_key> X_API_SECRET=<app_api_secret> node setup.js
+```
+
+This will:
+1. Open your browser to X's authorization page
+2. You log in with **your** X account and click "Authorize"
+3. Print your personal **Access Token** and **Access Token Secret**
+4. Add those to your Claude config — done. Tokens never expire.
 
 ## Usage Examples
 
 ### Search tweets
 ```
-"AI video" lang:en -is:retweet           # English tweets about AI video, no RTs
+"AI video" lang:en -is:retweet           # English tweets about AI video
 from:elonmusk has:media                   # Elon's tweets with media
 #buildinpublic -is:reply                  # Hashtag, original tweets only
-"machine learning" has:links min_faves:10 # ML tweets with links, 10+ likes
 ```
 
-### Chain tools together
+### Post and engage
+```
+Post a tweet: "Shipping a new feature today 🚀"
+Reply to tweet 1234567890 saying "Great thread!"
+Like tweet 1234567890
+Retweet the latest tweet from @username
+```
+
+### Chain tools
 1. `get_user_profile` → get user ID from username
 2. `get_user_tweets` → get their recent tweets
-3. `get_tweet_replies` → see replies on a specific tweet
+3. `like_post` → like a specific tweet
+4. `create_post` → reply to it
 
-### Run directly (without Claude)
-```bash
-X_BEARER_TOKEN="your-token" npx x-mcp
-```
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `X_BEARER_TOKEN` | Yes | Bearer token for read-only API access |
+| `X_API_KEY` | For write | OAuth 1.0a consumer key (API Key) |
+| `X_API_SECRET` | For write | OAuth 1.0a consumer secret (API Secret) |
+| `X_ACCESS_TOKEN` | For write | OAuth 1.0a access token (per-user) |
+| `X_ACCESS_TOKEN_SECRET` | For write | OAuth 1.0a access token secret (per-user) |
 
 ## Requirements
 
 - **Node.js 18+** (for native `fetch`)
-- **X API Bearer Token** — [Get one here](https://developer.x.com)
+- **X API access** — [Get it here](https://developer.x.com)
 
 ## How It Works
 
-Single-file MCP server (~120 lines). No build step, no config files. Reads `X_BEARER_TOKEN` from environment, connects via stdio.
+Single-file MCP server (~430 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 v2
+Claude ↔ stdio ↔ x-mcp ↔ X API v1.1/v2
+                    ↑
+          Bearer (read) + OAuth 1.0a (write)
 ```
 
+## Contributing
+
+Contributions welcome! Feel free to open issues or submit PRs.
+
+1. Fork the repo
+2. Create your branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Push and open a Pull Request
+
+## Author
+
+Built by [@amanrawatamg](https://x.com/amanrawatamg)
+
 ## License
 
 MIT

package/index.js

@@ -1,18 +1,43 @@
 #!/usr/bin/env node
 
+// ─── Setup mode (npx @realaman90/x-mcp --setup) ───────────────────────────────
+
+if (process.argv.includes("--setup")) {
+  const { fileURLToPath } = await import("url");
+  const { dirname, join } = await import("path");
+  const dir = dirname(fileURLToPath(import.meta.url));
+  await import(join(dir, "setup.js"));
+  process.exit(0);
+}
+
+import { createHmac, randomBytes } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 
+// ─── Auth config ───────────────────────────────────────────────────────────────
+
 const BEARER_TOKEN = decodeURIComponent(process.env.X_BEARER_TOKEN || "");
 if (!BEARER_TOKEN) {
   console.error("X_BEARER_TOKEN environment variable is required");
   process.exit(1);
 }
 
+const OAUTH = {
+  consumerKey: process.env.X_API_KEY || "",
+  consumerSecret: process.env.X_API_SECRET || "",
+  token: process.env.X_ACCESS_TOKEN || "",
+  tokenSecret: process.env.X_ACCESS_TOKEN_SECRET || "",
+};
+const HAS_OAUTH = !!(OAUTH.consumerKey && OAUTH.consumerSecret && OAUTH.token && OAUTH.tokenSecret);
+
+// ─── Shared constants ──────────────────────────────────────────────────────────
+
 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";
 
+// ─── Bearer fetch (read-only, no user context) ────────────────────────────────
+
 async function xapi(endpoint, params = {}) {
   const url = new URL(`https://api.x.com/2${endpoint}`);
   for (const [k, v] of Object.entries(params)) {
@@ -28,11 +53,99 @@ async function xapi(endpoint, params = {}) {
   return res.json();
 }
 
+// ─── OAuth 1.0a signing (HMAC-SHA1) ───────────────────────────────────────────
+
+function enc(str) {
+  return encodeURIComponent(str).replace(/[!'()*]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+
+function oauthSign(method, url, queryParams = {}) {
+  const ts = Math.floor(Date.now() / 1000).toString();
+  const nonce = randomBytes(16).toString("hex");
+
+  const oauthParams = {
+    oauth_consumer_key: OAUTH.consumerKey,
+    oauth_nonce: nonce,
+    oauth_signature_method: "HMAC-SHA1",
+    oauth_timestamp: ts,
+    oauth_token: OAUTH.token,
+    oauth_version: "1.0",
+  };
+
+  // Combine oauth params + query params, sort, encode
+  const all = { ...oauthParams, ...queryParams };
+  const paramStr = Object.keys(all)
+    .sort()
+    .map(k => `${enc(k)}=${enc(all[k])}`)
+    .join("&");
+
+  const baseStr = `${method.toUpperCase()}&${enc(url)}&${enc(paramStr)}`;
+  const signingKey = `${enc(OAUTH.consumerSecret)}&${enc(OAUTH.tokenSecret)}`;
+  const sig = createHmac("sha1", signingKey).update(baseStr).digest("base64");
+
+  oauthParams.oauth_signature = sig;
+  const header = "OAuth " + Object.keys(oauthParams)
+    .sort()
+    .map(k => `${enc(k)}="${enc(oauthParams[k])}"`)
+    .join(", ");
+
+  return header;
+}
+
+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}`;
+
+  // Parse any query params from endpoint for signing
+  const urlObj = new URL(fullUrl);
+  const queryParams = {};
+  for (const [k, v] of urlObj.searchParams) queryParams[k] = v;
+
+  const authHeader = oauthSign(method, urlObj.origin + urlObj.pathname, queryParams);
+
+  const opts = {
+    method,
+    headers: { Authorization: authHeader },
+  };
+  if (body && (method === "POST" || method === "PUT")) {
+    opts.headers["Content-Type"] = "application/json";
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(fullUrl, opts);
+  // DELETE endpoints return 204 with empty body
+  if (res.status === 204) return { success: true };
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`X API ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+// ─── Cached authenticated user ID ──────────────────────────────────────────────
+
+let _myUserId = null;
+async function getMyUserId() {
+  if (_myUserId) return _myUserId;
+  const data = await xapiAuth("GET", "/users/me", null);
+  _myUserId = data.data.id;
+  return _myUserId;
+}
+
+// ─── MCP Server ────────────────────────────────────────────────────────────────
+
 const server = new McpServer({
   name: "x-mcp",
-  version: "1.0.0",
+  version: "2.0.0",
 });
 
+const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// BEARER-ONLY TOOLS (always registered)
+// ═══════════════════════════════════════════════════════════════════════════════
+
 // 1. Search tweets
 server.tool(
   "search_tweets",
@@ -43,13 +156,12 @@ server.tool(
   },
   async ({ query, max_results }) => {
     const data = await xapi("/tweets/search/recent", {
-      query,
-      max_results,
+      query, max_results,
       "tweet.fields": TWEET_FIELDS,
       expansions: "author_id",
       "user.fields": "username,name",
     });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    return ok(data);
   }
 );
 
@@ -57,14 +169,10 @@ server.tool(
 server.tool(
   "get_user_profile",
   "Get an X/Twitter user's profile by username. Returns bio, follower counts, and account details.",
-  {
-    username: z.string().describe("X username (without @)"),
-  },
+  { username: z.string().describe("X username (without @)") },
   async ({ username }) => {
-    const data = await xapi(`/users/by/username/${username}`, {
-      "user.fields": USER_FIELDS,
-    });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    const data = await xapi(`/users/by/username/${username}`, { "user.fields": USER_FIELDS });
+    return ok(data);
   }
 );
 
@@ -81,7 +189,7 @@ server.tool(
       max_results,
       "tweet.fields": TWEET_FIELDS,
     });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    return ok(data);
   }
 );
 
@@ -101,7 +209,7 @@ server.tool(
       expansions: "author_id",
       "user.fields": "username,name",
     });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    return ok(data);
   }
 );
 
@@ -109,18 +217,230 @@ server.tool(
 server.tool(
   "get_tweet",
   "Get a single tweet by ID with full details including metrics, author info, and conversation context.",
-  {
-    tweet_id: z.string().describe("Tweet ID"),
-  },
+  { tweet_id: z.string().describe("Tweet ID") },
   async ({ tweet_id }) => {
     const data = await xapi(`/tweets/${tweet_id}`, {
       "tweet.fields": TWEET_FIELDS,
       expansions: "author_id",
       "user.fields": "username,name",
     });
-    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    return ok(data);
+  }
+);
+
+// 6. Get user's followers
+server.tool(
+  "get_user_followers",
+  "Get a list of users who follow the specified 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(1000).default(100).describe("Number of results (1-1000)"),
+  },
+  async ({ user_id, max_results }) => {
+    const data = await xapi(`/users/${user_id}/followers`, {
+      max_results,
+      "user.fields": USER_FIELDS,
+    });
+    return ok(data);
   }
 );
 
+// 7. Get user's following
+server.tool(
+  "get_user_following",
+  "Get a list of users the specified user is following. 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(1000).default(100).describe("Number of results (1-1000)"),
+  },
+  async ({ user_id, max_results }) => {
+    const data = await xapi(`/users/${user_id}/following`, {
+      max_results,
+      "user.fields": USER_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// 8. Get users who liked a tweet
+server.tool(
+  "get_liking_users",
+  "Get a list of users who liked a specific tweet.",
+  {
+    tweet_id: z.string().describe("Tweet ID"),
+    max_results: z.number().min(1).max(100).default(100).describe("Number of results (1-100)"),
+  },
+  async ({ tweet_id, max_results }) => {
+    const data = await xapi(`/tweets/${tweet_id}/liking_users`, {
+      max_results,
+      "user.fields": USER_FIELDS,
+    });
+    return ok(data);
+  }
+);
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// OAUTH TOOLS (only registered when OAuth credentials are present)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+if (HAS_OAUTH) {
+
+  // ─── OAuth Read Tools ──────────────────────────────────────────────────────
+
+  // 9. Get my profile
+  server.tool(
+    "get_my_profile",
+    "Get the authenticated user's own profile. Requires OAuth — returns your user ID, bio, metrics, etc.",
+    {},
+    async () => {
+      const data = await xapiAuth("GET", "/users/me?user.fields=" + encodeURIComponent(USER_FIELDS), null);
+      return ok(data);
+    }
+  );
+
+  // 10. Get user mentions
+  server.tool(
+    "get_user_mentions",
+    "Get recent tweets mentioning a specific user. Requires OAuth for user-context access.",
+    {
+      user_id: z.string().describe("X user ID (numeric string)"),
+      max_results: z.number().min(5).max(100).default(10).describe("Number of results (5-100)"),
+    },
+    async ({ user_id, max_results }) => {
+      const data = await xapiAuth("GET",
+        `/users/${user_id}/mentions?max_results=${max_results}&tweet.fields=${encodeURIComponent(TWEET_FIELDS)}&expansions=author_id&user.fields=${encodeURIComponent("username,name")}`,
+        null
+      );
+      return ok(data);
+    }
+  );
+
+  // 11. Get quote tweets
+  server.tool(
+    "get_quote_tweets",
+    "Get tweets that quote a specific tweet. Requires OAuth for user-context access.",
+    {
+      tweet_id: z.string().describe("Tweet ID"),
+      max_results: z.number().min(10).max(100).default(10).describe("Number of results (10-100)"),
+    },
+    async ({ tweet_id, max_results }) => {
+      const data = await xapiAuth("GET",
+        `/tweets/${tweet_id}/quote_tweets?max_results=${max_results}&tweet.fields=${encodeURIComponent(TWEET_FIELDS)}&expansions=author_id&user.fields=${encodeURIComponent("username,name")}`,
+        null
+      );
+      return ok(data);
+    }
+  );
+
+  // 12. Get bookmarks
+  server.tool(
+    "get_bookmarks",
+    "Get the authenticated user's bookmarked tweets. Bearer token is explicitly forbidden for this endpoint.",
+    {
+      max_results: z.number().min(1).max(100).default(20).describe("Number of results (1-100)"),
+    },
+    async ({ max_results }) => {
+      const myId = await getMyUserId();
+      const data = await xapiAuth("GET",
+        `/users/${myId}/bookmarks?max_results=${max_results}&tweet.fields=${encodeURIComponent(TWEET_FIELDS)}&expansions=author_id&user.fields=${encodeURIComponent("username,name")}`,
+        null
+      );
+      return ok(data);
+    }
+  );
+
+  // 13. Get trending topics
+  server.tool(
+    "get_trending_topics",
+    "Get current trending topics for a location. Uses v1.1 API. Default WOEID 1 = worldwide, 23424977 = US.",
+    {
+      woeid: z.number().default(1).describe("Where On Earth ID (1=worldwide, 23424977=US, 23424975=UK)"),
+    },
+    async ({ woeid }) => {
+      const data = await xapiAuth("GET", `/1.1/trends/place.json?id=${woeid}`, null);
+      return ok(data);
+    }
+  );
+
+  // ─── OAuth Write Tools ─────────────────────────────────────────────────────
+
+  // 14. Create post (most complex write tool)
+  server.tool(
+    "create_post",
+    "Create a new tweet/post on X. Supports text, replies, quote tweets, and polls. 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)"),
+      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 }) => {
+      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 (poll_options) {
+        body.poll = {
+          options: poll_options,
+          duration_minutes: poll_duration_minutes || 1440,
+        };
+      }
+      const data = await xapiAuth("POST", "/tweets", body);
+      return ok(data);
+    }
+  );
+
+  // 15. Delete post
+  server.tool(
+    "delete_post",
+    "Delete one of your own tweets by ID. This action is irreversible.",
+    { tweet_id: z.string().describe("Tweet ID to delete (must be your own tweet)") },
+    async ({ tweet_id }) => {
+      const data = await xapiAuth("DELETE", `/tweets/${tweet_id}`, null);
+      return ok(data);
+    }
+  );
+
+  // 16-27. 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],
+    ["repost",          "Repost (retweet) a tweet",             "POST",   (me) => `/users/${me}/retweets`,             "tweet_id", (id) => ({ tweet_id: id })],
+    ["unrepost",        "Undo a repost (unretweet)",            "DELETE", (me) => `/users/${me}/retweets/${"{id}"}`,   "tweet_id", null],
+    ["follow_user",     "Follow a user",                        "POST",   (me) => `/users/${me}/following`,            "target_user_id", (id) => ({ target_user_id: id })],
+    ["unfollow_user",   "Unfollow a user",                      "DELETE", (me) => `/users/${me}/following/${"{id}"}`,  "target_user_id", null],
+    ["bookmark_post",   "Bookmark a tweet",                     "POST",   (me) => `/users/${me}/bookmarks`,            "tweet_id", (id) => ({ tweet_id: id })],
+    ["unbookmark_post", "Remove a tweet from bookmarks",        "DELETE", (me) => `/users/${me}/bookmarks/${"{id}"}`,  "tweet_id", null],
+    ["block_user",      "Block a user",                         "POST",   (me) => `/users/${me}/blocking`,             "target_user_id", (id) => ({ target_user_id: id })],
+    ["unblock_user",    "Unblock a user",                       "DELETE", (me) => `/users/${me}/blocking/${"{id}"}`,   "target_user_id", null],
+    ["mute_user",       "Mute a user",                          "POST",   (me) => `/users/${me}/muting`,              "target_user_id", (id) => ({ target_user_id: id })],
+    ["unmute_user",     "Unmute a user",                        "DELETE", (me) => `/users/${me}/muting/${"{id}"}`,     "target_user_id", null],
+  ];
+
+  for (const [name, desc, method, pathFn, paramName, bodyFn] of toggleTools) {
+    const paramDesc = paramName === "tweet_id" ? "Tweet ID" : "Target user ID (numeric string)";
+    server.tool(
+      name,
+      desc,
+      { [paramName]: z.string().describe(paramDesc) },
+      async (input) => {
+        const myId = await getMyUserId();
+        const id = input[paramName];
+        const path = pathFn(myId).replace("{id}", id);
+        const body = bodyFn ? bodyFn(id) : null;
+        const data = await xapiAuth(method, path, body);
+        return ok(data);
+      }
+    );
+  }
+}
+
+// ─── Start server ──────────────────────────────────────────────────────────────
+
+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");
+}
+
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@realaman90/x-mcp",
-  "version": "1.0.0",
-  "description": "MCP server for X/Twitter API — search tweets, read profiles, get timelines and replies",
+  "version": "2.0.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",
   "bin": {
     "x-mcp": "index.js"
   },
-  "keywords": ["mcp", "twitter", "x", "claude", "ai"],
+  "keywords": ["mcp", "twitter", "x", "claude", "ai", "oauth", "post", "tweet"],
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/setup.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+/**
+ * One-time OAuth 1.0a setup for x-mcp.
+ *
+ * Run this when a new user wants to connect their X account to your app.
+ * It opens a browser, user clicks "Authorize", and you get their Access Token/Secret.
+ *
+ * Prerequisites:
+ *   - X_API_KEY and X_API_SECRET env vars set (app's Consumer Key/Secret)
+ *   - App callback URL set to http://localhost:3456/callback in X Developer Portal
+ *
+ * Usage:
+ *   X_API_KEY=... X_API_SECRET=... node setup.js
+ */
+
+import { createHmac, randomBytes } from "crypto";
+import { createServer } from "http";
+
+const API_KEY = process.env.X_API_KEY;
+const API_SECRET = process.env.X_API_SECRET;
+const BEARER_TOKEN = process.env.X_BEARER_TOKEN;
+
+if (!API_KEY || !API_SECRET) {
+  console.error("\n  Missing env vars. Run with:\n");
+  console.error("  X_BEARER_TOKEN=... X_API_KEY=... X_API_SECRET=... node setup.js\n");
+  console.error("  (X_BEARER_TOKEN is optional here but needed for the MCP server)\n");
+  process.exit(1);
+}
+
+const CALLBACK_URL = "http://localhost:3456/callback";
+
+// ─── OAuth 1.0a helpers ────────────────────────────────────────────────────────
+
+function enc(str) {
+  return encodeURIComponent(str).replace(/[!'()*]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+
+function sign(method, url, params, tokenSecret = "") {
+  const ts = Math.floor(Date.now() / 1000).toString();
+  const nonce = randomBytes(16).toString("hex");
+
+  const oauthParams = {
+    oauth_consumer_key: API_KEY,
+    oauth_nonce: nonce,
+    oauth_signature_method: "HMAC-SHA1",
+    oauth_timestamp: ts,
+    oauth_version: "1.0",
+    ...params,
+  };
+
+  const all = { ...oauthParams };
+  const paramStr = Object.keys(all).sort().map(k => `${enc(k)}=${enc(all[k])}`).join("&");
+  const baseStr = `${method}&${enc(url)}&${enc(paramStr)}`;
+  const signingKey = `${enc(API_SECRET)}&${enc(tokenSecret)}`;
+  const sig = createHmac("sha1", signingKey).update(baseStr).digest("base64");
+
+  oauthParams.oauth_signature = sig;
+  return "OAuth " + Object.keys(oauthParams).sort().map(k => `${enc(k)}="${enc(oauthParams[k])}"`).join(", ");
+}
+
+// ─── Step 1: Get request token ─────────────────────────────────────────────────
+
+console.log("\n  🔑 x-mcp OAuth Setup\n");
+console.log("  Step 1/3: Requesting temporary token...");
+
+const reqTokenUrl = "https://api.x.com/oauth/request_token";
+const reqTokenAuth = sign("POST", reqTokenUrl, { oauth_callback: CALLBACK_URL });
+
+const reqTokenRes = await fetch(reqTokenUrl, {
+  method: "POST",
+  headers: { Authorization: reqTokenAuth },
+});
+
+if (!reqTokenRes.ok) {
+  const body = await reqTokenRes.text();
+  console.error(`\n  ❌ Failed to get request token: ${reqTokenRes.status}\n  ${body}`);
+  console.error("\n  Make sure your callback URL is set to http://localhost:3456/callback in X Developer Portal");
+  process.exit(1);
+}
+
+const reqTokenBody = await reqTokenRes.text();
+const reqTokenParams = new URLSearchParams(reqTokenBody);
+const oauthToken = reqTokenParams.get("oauth_token");
+const oauthTokenSecret = reqTokenParams.get("oauth_token_secret");
+
+// ─── Step 2: User authorizes in browser ────────────────────────────────────────
+
+const authorizeUrl = `https://api.x.com/oauth/authorize?oauth_token=${oauthToken}`;
+
+console.log("  Step 2/3: Opening browser for authorization...\n");
+console.log(`  If browser doesn't open, visit:\n  ${authorizeUrl}\n`);
+
+// Open browser cross-platform
+const { exec } = await import("child_process");
+const openCmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+exec(`${openCmd} "${authorizeUrl}"`);
+
+// ─── Step 3: Wait for callback, exchange for access token ──────────────────────
+
+const verifier = await new Promise((resolve, reject) => {
+  const srv = createServer((req, res) => {
+    const url = new URL(req.url, "http://localhost:3456");
+    if (url.pathname === "/callback") {
+      const v = url.searchParams.get("oauth_verifier");
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(`
+        <html><body style="background:#000;color:#fff;font-family:system-ui;display:flex;align-items:center;justify-content:center;height:100vh;margin:0">
+          <div style="text-align:center">
+            <h1>✅ Authorized!</h1>
+            <p>You can close this tab and return to your terminal.</p>
+          </div>
+        </body></html>
+      `);
+      srv.close();
+      resolve(v);
+    }
+  });
+  srv.listen(3456, () => {
+    console.log("  Waiting for authorization (listening on port 3456)...\n");
+  });
+  srv.on("error", (e) => {
+    if (e.code === "EADDRINUSE") {
+      console.error("  ❌ Port 3456 is in use. Close whatever is using it and try again.");
+      process.exit(1);
+    }
+    reject(e);
+  });
+  // Timeout after 5 minutes
+  setTimeout(() => { srv.close(); reject(new Error("Timeout — no authorization received after 5 minutes")); }, 300000);
+});
+
+console.log("  Step 3/3: Exchanging for access token...");
+
+const accessTokenUrl = "https://api.x.com/oauth/access_token";
+const accessAuth = sign("POST", accessTokenUrl, {
+  oauth_token: oauthToken,
+  oauth_verifier: verifier,
+}, oauthTokenSecret);
+
+const accessRes = await fetch(accessTokenUrl, {
+  method: "POST",
+  headers: { Authorization: accessAuth },
+});
+
+if (!accessRes.ok) {
+  const body = await accessRes.text();
+  console.error(`\n  ❌ Failed to get access token: ${accessRes.status}\n  ${body}`);
+  process.exit(1);
+}
+
+const accessBody = await accessRes.text();
+const accessParams = new URLSearchParams(accessBody);
+const accessToken = accessParams.get("oauth_token");
+const accessTokenSecret = accessParams.get("oauth_token_secret");
+const screenName = accessParams.get("screen_name");
+const userId = accessParams.get("user_id");
+
+console.log(`\n  ✅ Success! Authorized as @${screenName} (ID: ${userId})\n`);
+console.log("  ─────────────────────────────────────────────────");
+console.log("  Add these to your Claude config env:\n");
+console.log(`  X_BEARER_TOKEN=${BEARER_TOKEN || "<ask your app owner for this>"}`);
+console.log(`  X_API_KEY=${API_KEY}`);
+console.log(`  X_API_SECRET=${API_SECRET}`);
+console.log(`  X_ACCESS_TOKEN=${accessToken}`);
+console.log(`  X_ACCESS_TOKEN_SECRET=${accessTokenSecret}`);
+if (!BEARER_TOKEN) {
+  console.log("\n  ⚠️  X_BEARER_TOKEN was not provided. Ask your app owner for it.");
+}
+console.log("\n  ─────────────────────────────────────────────────");
+console.log("  These tokens don't expire. Store them securely.\n");