@twitterapis/mcp 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- **Seven new tools, closing the gap between the MCP surface and the endpoints the API serves.** Reads: `twitter_trends` (top trends for a location, by `country` or `woeid`), `twitter_trends_locations` (every location X publishes trends for, each with its WOEID), and `twitter_account_me` / `twitter_account_payments` (your twitterapis.com account details and payment history; both free, and served on the un-prefixed `/account/*` path). Session and write: `twitter_customer_session` (register your x.com cookies against your key), `twitter_user_login` (log in with username/password, plus `totp_secret` for 2FA), and `twitter_media_upload` (upload a base64 image, returns a `media_id` for `twitter_create_tweet`). The catalog is now 47 tools: 33 reads and 14 write actions.
+- **A JSON-request-body transport for the three endpoints whose handler reads one.** `twitter_customer_session`, `twitter_user_login`, and `twitter_media_upload` set `jsonBody: true`, so their arguments are sent in the JSON body rather than the query string, matching the routes that read `c.req.json()`. For these tools the credential fields are the body payload and are not diverted into `x-*` headers.
+- `twitter_user_login` documents its REAL response contract, `{ ok, username, message }`. The account cookies it mints are stored server-side against your key and are never returned to the caller. (The published OpenAPI still describes an `{ auth_token, ct0, twid }` response for this endpoint, which the live handler does not send; a code comment on the tool flags the mismatch for maintainers.)
+
+### Fixed
+
+- **`twitter_tweet_thread` no longer advertises a `cursor` it ignores.** `/twitter/tweet/thread` returns the whole ordered thread in a single response and accepts only `id`/`url`, so the tool's `cursor` argument and its "paginate with cursor" wording were removed to match the contract (the live `openapi.json` had already dropped `cursor` here).
+- **`twitter_user_about` description refreshed** to cover the fields the endpoint returns today: verification and identity-verification flags, linked website, and X's "About this account" transparency panel (account country, how the account was created, and username-change history).
+- **`test/openapi.snapshot.json` regenerated from the live `openapi.json`**, bringing the vendored offline copy back in sync. It had drifted on 23 endpoints' fields, and now also carries the four new paths and the `Trend` component schemas.
+
+### Changed
+
+- The publish firewall now runs on `npm publish` itself, via `prepublishOnly`, not only on a manual `npm test`. A release that skips the test step can no longer reach the registry unchecked. Verified: with a competitor reference reintroduced into the README, `npm publish` aborts before the tarball stage.
+- The firewall no longer carries its own list of banned terms. It delegates to the maintainer's isolation registry, which is the single place those rules live, so the gate and everything else that enforces them cannot drift apart. If the registry cannot be located, the gate fails rather than passing.
+
+The two firewall changes above are release tooling only.
+
 ## 0.6.1 (2026-07-20)
 
 ### Fixed

package/README.md

@@ -91,9 +91,9 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-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.
+47 tools: 33 reads and 14 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. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`).
 
-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.
+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). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). 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.
 
 ### Reads
 
@@ -103,7 +103,7 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_user_search` | Find user accounts by name or keyword |
 | `twitter_user_info` | Full profile by handle (bio, counts, verification, location) |
 | `twitter_user_info_by_id` | Full profile by numeric user id |
-| `twitter_user_about` | A user's structured About panel (category, professional labels, joined date) |
+| `twitter_user_about` | A user's structured About object (category, professional/business labels, verification + identity-verification flags, joined date, and X's 'About this account' transparency panel) |
 | `twitter_user_affiliates` | Accounts affiliated with an organization profile |
 | `twitter_check_follow_relationship` | Follow relationship between two user ids (who follows whom) |
 | `twitter_user_tweets` | A user's recent original tweets (replies excluded) |
@@ -128,6 +128,10 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_bookmark_search` | Full-text search within your bookmarks _(session)_ |
 | `twitter_dm_list` | Your DM conversations (inbox), read-only _(session)_ |
 | `twitter_dm_conversation` | Messages in one DM conversation, read-only _(session)_ |
+| `twitter_trends` | Current top trends for a location (by `country` or `woeid`) |
+| `twitter_trends_locations` | Every location X has trends for, each with its WOEID |
+| `twitter_account_me` | Your twitterapis.com account: credits, usage, email (free) |
+| `twitter_account_payments` | Your twitterapis.com payment history (free) |
 
 ### Write actions _(require a linked X session)_
 
@@ -140,6 +144,16 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_bookmark_tweet` / `twitter_unbookmark_tweet` | Bookmark / remove bookmark |
 | `twitter_follow_user` / `twitter_unfollow_user` | Follow / unfollow a user by id |
 | `twitter_dm_send` | Send a Direct Message to a user by their numeric `recipient_id` |
+| `twitter_media_upload` | Upload a base64 image, returns a `media_id` for `twitter_create_tweet` |
+
+### Session setup
+
+Link an X account to your key once, so the account-only reads and write actions act as it (or pass per-call `auth_token`/`ct0` instead).
+
+| Tool | What it does |
+|---|---|
+| `twitter_customer_session` | Register your x.com session cookies (`auth_token` + `ct0`) against your key |
+| `twitter_user_login` | Log in with `username` + `password` (+ `totp_secret` for 2FA); stores the session against your key. Returns a confirmation, never the cookies |
 
 ## Usage examples
 
@@ -221,7 +235,7 @@ Calls are billed to your twitterapis.com account. Almost every endpoint is $0.00
 
 **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.
+**Is it read-only?** No. 33 read tools work with just your API key; 14 write actions (post, like, retweet, follow, DM, media upload) 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "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",
@@ -24,6 +24,7 @@
     "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 && node test/openapi-parity.mjs && node test/firewall.mjs",
+    "prepublishOnly": "npm test",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:firewall": "node test/firewall.mjs"
   },

package/src/index.js

@@ -40,18 +40,13 @@ if (!API_KEY) {
 }
 
 // ── REST call ────────────────────────────────────────────────────────────────
-// Every endpoint (GET reads and POST writes alike) reads its params from the
-// query string, so the same buildQuery path serves both; only the HTTP method
-// differs per tool.
-async function callEndpoint(path, args, method = "GET") {
-  // Pull per-call inline credentials out of args so they travel as request
-  // headers, never the query string (the API reads x-auth-token / x-ct0; passing
-  // them as query params would leak them into URLs and access logs). When
-  // supplied, this one API key acts as that account; otherwise the key's linked
-  // session is used. Lets a single key act as many accounts.
-  const { auth_token, ct0, user_agent, proxy_url, ...rest } = args || {};
-  const q = buildQuery(rest);
-  const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+// Most endpoints (GET reads and the simple POST writes alike) read their params
+// from the query string, so the same buildQuery path serves both and only the
+// HTTP method differs. A few POST endpoints (customer/session, user_login,
+// media/upload) instead read a JSON request body; those tools set jsonBody:true
+// and callEndpoint sends the args in the body rather than the query string.
+async function callEndpoint(path, args, method = "GET", jsonBody = false) {
+  const all = args || {};
 
   const headers = {
     // The API accepts either header; send both for maximum compatibility.
@@ -60,11 +55,33 @@ async function callEndpoint(path, args, method = "GET") {
     accept: "application/json",
     "user-agent": `twitterapis-mcp/${VERSION}`,
   };
-  if (auth_token && ct0) {
-    headers["x-auth-token"] = auth_token;
-    headers["x-ct0"] = ct0;
-    if (user_agent) headers["x-user-agent"] = user_agent;
-    if (proxy_url) headers["x-proxy-url"] = proxy_url;
+
+  let url;
+  let reqBody;
+  if (jsonBody) {
+    // Endpoints whose handler reads a JSON request body (customer/session,
+    // user_login, media/upload). Send every arg in the body: for customer/session
+    // and user_login the credentials ARE the payload the handler reads from the
+    // body, so they must NOT be diverted into x-* headers the way per-call inline
+    // creds are on the query-string tools.
+    url = `${BASE_URL}${path}`;
+    headers["content-type"] = "application/json";
+    reqBody = JSON.stringify(all);
+  } else {
+    // Pull per-call inline credentials out of args so they travel as request
+    // headers, never the query string (the API reads x-auth-token / x-ct0; passing
+    // them as query params would leak them into URLs and access logs). When
+    // supplied, this one API key acts as that account; otherwise the key's linked
+    // session is used. Lets a single key act as many accounts.
+    const { auth_token, ct0, user_agent, proxy_url, ...rest } = all;
+    const q = buildQuery(rest);
+    url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+    if (auth_token && ct0) {
+      headers["x-auth-token"] = auth_token;
+      headers["x-ct0"] = ct0;
+      if (user_agent) headers["x-user-agent"] = user_agent;
+      if (proxy_url) headers["x-proxy-url"] = proxy_url;
+    }
   }
 
   const ctrl = new AbortController();
@@ -73,6 +90,7 @@ async function callEndpoint(path, args, method = "GET") {
     const res = await fetch(url, {
       method,
       headers,
+      body: reqBody,
       signal: ctrl.signal,
     });
     const body = await res.text();
@@ -120,7 +138,7 @@ for (const tool of TOOLS) {
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method),
+    async (args) => callEndpoint(tool.path, args, method, Boolean(tool.jsonBody)),
   );
 }
 

package/src/tools.js

@@ -115,7 +115,7 @@ export const TOOLS = [
     name: "twitter_user_about",
     path: "/twitter/user/user_about",
     description:
-      "Get a user's 'About' panel: the structured profile facts X surfaces beyond the bio, such as account category, professional/business labels, joined date, and location when present. Provide a username or a user_id. Use this to enrich a profile beyond what twitter_user_info returns.",
+      "Get a user's full 'About' object: the structured profile facts X surfaces beyond the bio, including account category and professional/business labels, verification and identity-verification flags, joined date, location and linked website, follower/following counts, and X's 'About this account' transparency panel (the account's country, how the account was created, and its username-change history). Provide a username or a user_id. Use this to enrich a profile beyond what twitter_user_info returns.",
     shape: { ...USER_REF },
   },
   {
@@ -273,8 +273,12 @@ export const TOOLS = [
     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, ...CURSOR },
+      "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 in a single call. Does NOT return replies from other users, use twitter_tweet_replies for that. Accepts either the tweet id or its full URL.",
+    // No cursor: /twitter/tweet/thread returns the whole ordered thread in one
+    // response and takes no pagination param (openapi lists only id/url). The
+    // previous ...CURSOR advertised a cursor the endpoint ignores and drove a
+    // false "paginate with cursor" claim; removed to match the real contract.
+    shape: { ...TWEET_REF },
   },
   {
     name: "twitter_tweet_retweeters",
@@ -295,6 +299,46 @@ export const TOOLS = [
       ...PAGINATION,
     },
   },
+  // ── Reads: trends ──────────────────────────────────────────────────────────
+  {
+    name: "twitter_trends",
+    path: "/twitter/trends",
+    description:
+      "Get the current top trends for a location. With no location parameter, returns Worldwide (WOEID 1, X's own default). Pass country (an ISO code or country name, e.g. 'US' or 'Japan') or a numeric woeid from twitter_trends_locations; woeid wins when both are given. Returns the resolved location, the as_of / created_at timestamps, and the ranked trends list. Use count to truncate the list. A location X will not serve returns a 400.",
+    shape: {
+      country: z.string().optional().describe(
+        "Country name or ISO code to get trends for, e.g. 'US' or 'Japan'. Resolved against the trends locations list. Omit for Worldwide.",
+      ),
+      woeid: z.string().optional().describe(
+        "Numeric WOEID from twitter_trends_locations. Takes precedence over country when both are supplied.",
+      ),
+      count: z.number().int().min(1).optional().describe(
+        "Truncate the returned trends list to at most this many. Omit to return X's full list for the location.",
+      ),
+    },
+  },
+  {
+    name: "twitter_trends_locations",
+    path: "/twitter/trends/locations",
+    description:
+      "List every location X publishes trends for, each with the numeric WOEID to pass back to twitter_trends as woeid. Takes no parameters. Use this to resolve a country or city to its WOEID before requesting trends for that place.",
+    shape: {},
+  },
+  // ── Reads: your twitterapis.com account (billing; not Twitter data) ─────────
+  {
+    name: "twitter_account_me",
+    path: "/account/me",
+    description:
+      "Get YOUR twitterapis.com account details: email, name, credits remaining, credits used, total requests made, and account creation date. Authenticated by your API key. This is an account read, not Twitter data, and is free (it does not spend credits).",
+    shape: {},
+  },
+  {
+    name: "twitter_account_payments",
+    path: "/account/payments",
+    description:
+      "Get YOUR twitterapis.com payment history: the list of top-ups and charges on your account. Authenticated by your API key. This is an account read, not Twitter data, and is free (it does not spend credits).",
+    shape: {},
+  },
   // ── Reads: authenticated-account surfaces (require a session behind your key) ─
   {
     name: "twitter_home_timeline",
@@ -482,6 +526,76 @@ export const TOOLS = [
       ...INLINE,
     },
   },
+  // ── Session bootstrap + media: link an X account to your key, then act as it ─
+  // Once a session is linked (via twitter_customer_session or twitter_user_login)
+  // the authenticated-account reads and the write actions run AS that account.
+  // These three send a JSON request body (jsonBody:true), so the fields travel
+  // in the body, not the query string, matching the backend routes that read
+  // c.req.json().
+  {
+    name: "twitter_customer_session",
+    path: "/twitter/customer/session",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    description:
+      "Register YOUR OWN X account session against your API key, so the authenticated-account tools (twitter_home_timeline, twitter_bookmarks, twitter_dm_list, twitter_dm_conversation, twitter_user_likes) and the write tools (twitter_create_tweet, twitter_dm_send, twitter_follow_user, twitter_favorite_tweet, twitter_retweet, twitter_media_upload) act as your account. Provide your x.com session cookies auth_token and ct0 (copy them from a logged-in browser); optionally a user_agent and a residential proxy_url. The cookies are stored server-side against your key and are never returned. Returns ok, the resolved username, and whether the session validated live. Prefer twitter_user_login if you would rather pass a username/password than raw cookies. Most tools also accept auth_token/ct0 per-call without registering.",
+    shape: {
+      auth_token: z.string().describe(
+        "Your x.com auth_token cookie value, from a logged-in browser session. Stored server-side against your key; never returned.",
+      ),
+      ct0: z.string().describe(
+        "Your x.com ct0 (CSRF) cookie value, from the same browser session. Paired with auth_token.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. Browser User-Agent to send with this session's requests. Defaults to a current Chrome UA.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. HTTP or SOCKS proxy URL to route this session's traffic through, e.g. 'http://user:pass@host:port'.",
+      ),
+    },
+  },
+  {
+    name: "twitter_user_login",
+    path: "/twitter/user/user_login",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    // CONTRACT NOTE (maintainers): the published openapi documents an
+    // {auth_token, ct0, twid} response for this endpoint. That is WRONG. The
+    // live handler (backend routes/user-login.ts) returns {ok, username,
+    // message} and stores the minted session server-side; it never returns the
+    // cookies. The description below documents the REAL contract, not the
+    // openapi's. Fixing the openapi response schema is a docs/website change.
+    description:
+      "Log in to X with a username and password (plus totp_secret if the account has 2FA) and store the resulting session against your API key, so the authenticated-account reads and the write tools then act as that account. On success returns { ok, username, message }; it does NOT return the session cookies (auth_token/ct0 are minted and kept server-side, never sent back). Typical failures: bad_credentials (401), two_factor_required (400, add totp_secret), captcha_required (422), acid_challenge (409, confirm the login from the account then retry). This handles real account credentials; never log or echo the values you pass.",
+    shape: {
+      username: z.string().describe(
+        "The X account username/handle (without the leading @). Some accounts also accept the login email here.",
+      ),
+      password: z.string().describe(
+        "The X account password.",
+      ),
+      totp_secret: z.string().optional().describe(
+        "The account's base32 two-factor (TOTP) secret. Required only when the account has 2FA enabled.",
+      ),
+    },
+  },
+  {
+    name: "twitter_media_upload",
+    path: "/twitter/media/upload",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    description:
+      "Upload an image to X and get a media_id to attach to a tweet via twitter_create_tweet's media_ids. Provide media_data as base64-encoded image bytes. Acts as your registered account session (register first with twitter_customer_session or twitter_user_login, or pass auth_token/ct0 for this call). Returns ok and the media_id. Only base64 image data is supported over this tool's JSON transport.",
+    shape: {
+      media_data: z.string().describe(
+        "Base64-encoded image bytes to upload. Sent in the JSON request body.",
+      ),
+      ...INLINE,
+    },
+  },
 ];
 
 // Pure query-string builder: drops undefined/null/empty values, URL-encodes the rest.