@twitterapis/mcp 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.6.0 (2026-07-20)
+
+### Fixed
+
+- **Removed three phantom parameters from the published tool schemas.** Eleven write tools (`twitter_create_tweet`, `twitter_delete_tweet`, `twitter_favorite_tweet` / `twitter_unfavorite_tweet`, `twitter_retweet` / `twitter_unretweet`, `twitter_bookmark_tweet` / `twitter_unbookmark_tweet`, `twitter_follow_user` / `twitter_unfollow_user`, `twitter_dm_send`) advertised an optional `account` parameter that the API never accepted, so agents that passed it were silently ignored. `twitter_tweet_replies` and `twitter_tweet_retweeters` advertised the full pagination shape when the endpoint only accepts `cursor`.
+- A fail-closed MCP-to-OpenAPI parity gate now runs on every `npm test`, so a tool schema can no longer drift from the live API contract unnoticed.
+- README: corrected the Links section (the REST base URL is `https://api.twitterapis.com`; removed a link to a status page that does not exist) and added an FAQ covering signup, read-vs-write scope, supported clients, billing, and data handling.
+
+### Breaking
+
+- If your client explicitly passed `account` to a write tool, or `count` to `twitter_tweet_replies` / `twitter_tweet_retweeters`, those keys are no longer part of the schema. They were never honoured by the API, so behaviour is unchanged; only the advertised schema is now accurate.
+
+## 0.5.0 (2026-07-06)
+
+### Added
+
+- `twitter_user_followers_v2` and `twitter_user_following_v2` — the v2 response shape (richer profile fields and more reliable cursoring for large follower/following audiences). Same inputs as the v1 tools (`username` / `user_id` + `cursor`). Catalog is now **40 tools** (29 reads + 11 write actions).
+
+### No breaking changes
+
 ## 0.3.0 (2026-06-29)
 
 ### Added

package/README.md

@@ -1,5 +1,9 @@
 # @twitterapis/mcp
 
+[![npm version](https://img.shields.io/npm/v/@twitterapis/mcp)](https://www.npmjs.com/package/@twitterapis/mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@twitterapis/mcp)](https://www.npmjs.com/package/@twitterapis/mcp)
+[![license](https://img.shields.io/npm/l/@twitterapis/mcp)](./LICENSE)
+
 Official **Model Context Protocol** server for [twitterapis.com](https://www.twitterapis.com), the Twitter / X API as native tools for Claude, Cursor, Windsurf, and any MCP client. Reads (search, profiles, timelines, followers, DMs) plus write actions (post, like, retweet, follow).
 
 Ask your agent to search tweets, pull a user's profile or timeline, list followers/following, fetch thread context, or enumerate list members and it calls the API directly. Every tool maps to a REST endpoint at `https://api.twitterapis.com`; the server holds no state and forwards your API key on each call.
@@ -87,7 +91,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-38 tools: 27 reads and 11 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page.
+40 tools: 29 reads and 11 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page.
 
 Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **all write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark) are annotated `destructiveHint: true` so MCP clients can prompt before running them.
 
@@ -110,6 +114,8 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_user_likes` | Tweets a user has liked (public Likes tab) |
 | `twitter_user_followers` | Accounts that follow a user |
 | `twitter_user_following` | Accounts a user follows |
+| `twitter_user_followers_v2` | Followers with the v2 response shape (richer fields, deeper cursoring) |
+| `twitter_user_following_v2` | Following with the v2 response shape (richer fields, deeper cursoring) |
 | `twitter_user_verified_followers` | A user's verified followers only |
 | `twitter_followers_you_know` | Followers of a target that your authenticated account also follows |
 | `twitter_tweet_detail` | Single tweet: text, author, metrics, media, quoted/reply context |
@@ -202,14 +208,26 @@ count: 50
 
 ## Pricing
 
-Calls are billed to your twitterapis.com account, every price 20% below getxapi.com per endpoint. Almost every endpoint is $0.0008/call: all reads (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation, sending a DM (`twitter_dm_send`), and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, and a full tweet thread (`twitter_tweet_thread`) at $0.004/call. Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
+Calls are billed to your twitterapis.com account. Almost every endpoint is $0.0008/call: all reads (search, profiles, tweets, followers, likes) plus the simple write actions (like, retweet, bookmark, follow and their undos, delete). At the read rate that works out to $0.04 per 1,000 tweets, since each call returns about 20 tweets. The premium endpoints cost a little more: tweet creation, sending a DM (`twitter_dm_send`), and DM reads (`twitter_dm_list`, `twitter_dm_conversation`) at $0.0016/call, full tweet history (`twitter_user_tweets_complete`) at $0.0024/call, and a full tweet thread (`twitter_tweet_thread`) at $0.004/call. Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
 
 ## Links
 
 - Docs: [docs.twitterapis.com](https://docs.twitterapis.com)
 - Dashboard / API keys: [twitterapis.com/dashboard](https://www.twitterapis.com/dashboard)
-- REST API (without MCP): [api.twitterapis.com](https://api.twitterapis.com)
-- Status: [twitterapis.com/status](https://www.twitterapis.com/status)
+- Pricing: [twitterapis.com/pricing](https://www.twitterapis.com/pricing)
+- REST API base URL (call it directly, without MCP): `https://api.twitterapis.com`
+
+## FAQ
+
+**Do I need an X (Twitter) developer account?** No. Get an API key at [twitterapis.com/signup](https://www.twitterapis.com/signup); there is no application or approval step.
+
+**Is it read-only?** No. 29 read tools work with just your API key; 11 write actions (post, like, retweet, follow, DM) act as a linked X account or per-call inline credentials.
+
+**Which clients are supported?** Claude Desktop, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
+
+**How is it billed?** Per request. New keys start with $0.50 in free credits, no card required. See [pricing](https://www.twitterapis.com/pricing).
+
+**Does it store my key or data?** No. The server holds no state and forwards your API key on each call.
 
 ## License
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Official MCP server for twitterapis.com, the Twitter/X API (search, users, followers, tweets, threads, lists, likes, bookmarks, DMs) plus write actions (post/like/retweet/follow) as native tools for Claude, Cursor, and any MCP client.",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TwitterAPIs/twitterapis-mcp.git"
+    "url": "git+https://github.com/TwitterAPIs/twitterapis-mcp.git"
   },
   "type": "module",
   "bin": {
@@ -23,7 +23,9 @@
   "scripts": {
     "start": "node src/index.js",
     "check": "node --check src/index.js && node --check src/tools.js",
-    "test": "node test/tools.test.mjs && node test/smoke.mjs"
+    "test": "node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/firewall.mjs",
+    "check:openapi-parity": "node test/openapi-parity.mjs",
+    "check:firewall": "node test/firewall.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/tools.js

@@ -10,13 +10,16 @@
 import { z } from "zod";
 
 // ── Shared Zod input-schema fragments ───────────────────────────────────────
+const CURSOR = {
+  cursor: z.string().optional().describe(
+    "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
+  ),
+};
 const PAGINATION = {
   count: z.number().int().min(1).max(200).optional().describe(
     "Max items to return for this page. Typical range 1 to 200; endpoint default (20) applies if omitted. To page through results, pass the cursor from the previous response.",
   ),
-  cursor: z.string().optional().describe(
-    "Opaque pagination cursor from a previous response's next_cursor field. Omit on the first call; pass on subsequent calls to fetch the next page.",
-  ),
+  ...CURSOR,
 };
 const USER_REF = {
   username: z.string().optional().describe(
@@ -34,14 +37,6 @@ const TWEET_REF = {
     'Full tweet URL, e.g. "https://x.com/elonmusk/status/1789012345678901234". Provide exactly one of id or url.',
   ),
 };
-// Optional pooled-session selector, shared by every write action. A customer
-// key maps to a default authenticated session; pass account only to target a
-// specific handle in a multi-account pool.
-const ACCOUNT = {
-  account: z.string().optional().describe(
-    "Optional. The @handle (without @) of the authenticated account to act AS, when your key manages more than one session. Omit to use your key's default session.",
-  ),
-};
 // Per-call inline credentials. Pass an account's own X session cookies to act AS
 // that account for this one call, without pre-registering a session, so a single
 // API key can act as many accounts (e.g. polling several inboxes or posting from
@@ -225,6 +220,20 @@ export const TOOLS = [
       "List the accounts that a given user follows. Returns profile data for each account followed. Paginate with cursor. Useful for mapping a user's information sources, influencer networks, or competitor monitoring lists.",
     shape: { ...USER_REF, ...PAGINATION },
   },
+  {
+    name: "twitter_user_followers_v2",
+    path: "/twitter/user/followers_v2",
+    description:
+      "List a user's followers using the v2 response shape (richer profile fields and more reliable cursoring for large audiences). Same inputs as twitter_user_followers; prefer this when you need the fuller v2 payload or are paging deep follower lists.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_user_following_v2",
+    path: "/twitter/user/following_v2",
+    description:
+      "List the accounts a user follows using the v2 response shape (richer profile fields and more reliable cursoring). Same inputs as twitter_user_following; prefer this when you need the fuller v2 payload or are paging deep following lists.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
   {
     name: "twitter_user_verified_followers",
     path: "/twitter/user/verified_followers",
@@ -258,14 +267,14 @@ export const TOOLS = [
     path: "/twitter/tweet/replies",
     description:
       "Get replies to a specific tweet. Returns each reply tweet with author, text, and metrics. Paginate with cursor to load more. Use this to read the conversation under a tweet, gauge sentiment, or find notable responses.",
-    shape: { ...TWEET_REF, ...PAGINATION },
+    shape: { ...TWEET_REF, ...CURSOR },
   },
   {
     name: "twitter_tweet_thread",
     path: "/twitter/tweet/thread",
     description:
       "Get all tweets in a thread: the connected chain of tweets posted by the SAME author in sequence (a tweetstorm or numbered thread). Pass any tweet id/url from the thread and the API returns the full ordered sequence. Paginate with cursor for long threads. Does NOT return replies from other users, use twitter_tweet_replies for that.",
-    shape: { ...TWEET_REF, ...PAGINATION },
+    shape: { ...TWEET_REF, ...CURSOR },
   },
   {
     name: "twitter_tweet_retweeters",
@@ -347,7 +356,7 @@ export const TOOLS = [
       text: z.string().min(1).describe(
         "The Direct Message body text to send (non-empty).",
       ),
-      ...ACCOUNT, ...INLINE,
+      ...INLINE,
     },
   },
 
@@ -372,7 +381,7 @@ export const TOOLS = [
       media_ids: z.string().optional().describe(
         "Optional. Comma-separated media id(s) from a prior media upload to attach (images/video).",
       ),
-      ...ACCOUNT, ...INLINE,
+      ...INLINE,
     },
   },
   {
@@ -383,7 +392,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Delete a tweet AS your authenticated account. Irreversible: the tweet is permanently removed. You can only delete tweets your authenticated account authored. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   // ── Writes: engagement (favorite / retweet / bookmark) + inverses ──────────
   {
@@ -393,7 +402,7 @@ export const TOOLS = [
     write: true,
     description:
       "Like (favorite) a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unfavorite_tweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   {
     name: "twitter_unfavorite_tweet",
@@ -403,7 +412,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Remove a like (unfavorite) from a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   {
     name: "twitter_retweet",
@@ -412,7 +421,7 @@ export const TOOLS = [
     write: true,
     description:
       "Retweet a tweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unretweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   {
     name: "twitter_unretweet",
@@ -422,7 +431,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Undo a retweet AS your authenticated account. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   {
     name: "twitter_bookmark_tweet",
@@ -431,7 +440,7 @@ export const TOOLS = [
     write: true,
     description:
       "Bookmark a tweet to YOUR authenticated account's private bookmarks. Provide the tweet id or url. Requires write capability behind your key. Reverse with twitter_unbookmark_tweet.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   {
     name: "twitter_unbookmark_tweet",
@@ -441,7 +450,7 @@ export const TOOLS = [
     destructive: true,
     description:
       "Remove a tweet from YOUR authenticated account's bookmarks. Provide the tweet id or url. Requires write capability behind your key.",
-    shape: { ...TWEET_REF, ...ACCOUNT, ...INLINE },
+    shape: { ...TWEET_REF, ...INLINE },
   },
   // ── Writes: follow graph ───────────────────────────────────────────────────
   {
@@ -455,7 +464,7 @@ export const TOOLS = [
       user_id: z.string().describe(
         "Numeric user id of the account to follow. Resolve a handle to a user_id first with twitter_user_info.",
       ),
-      ...ACCOUNT, ...INLINE,
+      ...INLINE,
     },
   },
   {
@@ -470,7 +479,7 @@ export const TOOLS = [
       user_id: z.string().describe(
         "Numeric user id of the account to unfollow.",
       ),
-      ...ACCOUNT, ...INLINE,
+      ...INLINE,
     },
   },
 ];