@twitterapis/mcp 0.7.6 → 0.7.8

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.7.8 (2026-08-16)
+
+### Added
+
+- **`twitter_grok_chat`** (POST /twitter/grok/chat): ask X's own Grok a question as your authenticated account and get one complete JSON reply with the answer plus the sources it cited. Unlike a general LLM, Grok reads X in real time, so it can answer about what is being said right now, and passing a bare tweet or status URL as the message returns a structured summary of that post. Citations come back as `{url, title, snippet}`, merged and de-duplicated across every search Grok ran in that answer, and `title` is not always present. The response also reports the model that ACTUALLY answered, which can differ from the mode you asked for. Buffered, not streamed. STATELESS: nothing is stored on our side, so to continue a conversation you pass the prior turns back in `messages[]` with the `conversation_id`. $0.004 per answer, the same tier as `twitter_tweet_thread`, priced on our connection-holding cost rather than on model tokens, since the inference runs on your own X account.
+- **`twitter_grok_config`** (GET /twitter/grok/config): whether the authenticated account can use Grok, X's own reasons when it cannot, and the model options available. Eligibility is a property of the X ACCOUNT rather than of the API key, so ask it about the same account you intend to run `twitter_grok_chat` as. Free. 80 tools now: 49 reads and 31 writes.
+
+## 0.7.7 (2026-08-16)
+
+### Added
+
+- **`twitter_spaces_info`** (GET /twitter/spaces/info): metadata and the participant roster for one X Space, live or ended. Returns title, lifecycle state (`Scheduled` / `NotStarted` / `Running` / `Ended`), content type (`audio`, or `visual_audio` when the host enabled video), the host profile, topics, the wrapper tweet, scheduled and actual start/end times, peak live listener count, replay view count, and the admin, speaker and listener rosters. Takes the Space id from a `x.com/i/spaces/<id>` URL. Two things worth knowing before you read a response as wrong: X does NOT retain the per-person listener roster once a Space ends, so `listeners` comes back empty for an ended Space while `total_live_listeners` (peak concurrent) and `total_replay_watched` still reflect the real audience, and `admins` and `speakers` do survive; and every timestamp is a millisecond-epoch number, because X sends `started_at` as a number and `ended_at` as a string in the same payload and both are normalised so you can subtract them directly. Returns metadata only, not the Space audio.
+- **`twitter_article_update_cover_media`** (POST /twitter/article/update_cover_media): attach an already-uploaded image as a draft or published article's cover, completing the article write set. This attaches, it does not upload: call `twitter_media_upload` first and pass the `media_id` it returns. `media_category` defaults to `DraftTweetImage`, which is what X's own article editor sends. 78 tools now: 48 reads and 30 writes.
+
 ## 0.7.6 (2026-08-16)
 
 ### Added

package/README.md

@@ -91,7 +91,7 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-76 tools: 47 reads and 29 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`); the 14 monitoring tools are also free (account administration, not metered reads).
+80 tools: 49 reads and 31 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`); the 14 monitoring tools are also free (account administration, not metered reads).
 
 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 **most 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, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** tools (see below) are the one exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
 
@@ -133,6 +133,9 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 | `twitter_bookmark_folder_timeline` | Tweets inside one of your bookmark folders, by `folder_id` _(session)_ |
 | `twitter_dm_list` | Your DM conversations (inbox), read-only _(session)_ |
 | `twitter_dm_conversation` | Messages in one DM conversation, read-only _(session)_ |
+| `twitter_spaces_info` | Metadata and participant roster for one X Space, live or ended (by Space `id`) |
+| `twitter_grok_chat` | Ask X's own Grok, grounded in live X data, and get the answer plus the sources it cited |
+| `twitter_grok_config` | Whether the authenticated account can use Grok, and which models it may pick |
 | `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) |
@@ -160,6 +163,7 @@ Public reads (search, profiles, tweets, followers, likes) work with just your AP
 |---|---|
 | `twitter_article_create` | Start a new draft article, returns its `id` |
 | `twitter_article_update_title` | Set a draft or published article's title |
+| `twitter_article_update_cover_media` | Attach an already-uploaded image as an article's cover (`media_id` from `twitter_media_upload`) |
 | `twitter_article_update_content` | Replace a draft or published article's body (Draft.js `content_state` you build) |
 | `twitter_article_publish` | Publish a draft, posting a **real public announcement tweet** (not fully reversible) |
 | `twitter_article_unpublish` | Revert a published article to draft (leaves the announcement tweet up) |
@@ -265,7 +269,7 @@ count: 50
 
 ## 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, a full tweet thread (`twitter_tweet_thread`) at $0.004/call, and the article-editing writes (`twitter_article_create`, `twitter_article_update_title`, `twitter_article_update_content`, `twitter_article_publish`, `twitter_article_unpublish`) at $0.0016/call (`twitter_article_get`, `twitter_article_list`, and `twitter_article_delete` stay at the standard $0.0008/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, a full tweet thread (`twitter_tweet_thread`) and a Grok answer (`twitter_grok_chat`) at $0.004/call, and the article-editing writes (`twitter_article_create`, `twitter_article_update_title`, `twitter_article_update_cover_media`, `twitter_article_update_content`, `twitter_article_publish`, `twitter_article_unpublish`) at $0.0016/call (`twitter_article_get`, `twitter_article_list`, and `twitter_article_delete` stay at the standard $0.0008/call). Your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
 
 ## Links
 
@@ -278,7 +282,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. 47 read tools work with just your API key; 29 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete, monitor/webhook create/update/delete) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD, which is account administration and needs only your API key.
+**Is it read-only?** No. 49 read tools work with just your API key; 31 write actions (post, like, retweet, follow, DM, media upload, article create/edit/publish/delete, monitor/webhook create/update/delete) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD, which is account administration and needs only your API key.
 
 **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.7.6",
+  "version": "0.7.8",
   "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",
@@ -26,9 +26,10 @@
     "build": "node scripts/gen-tools.mjs --write",
     "build:check": "node scripts/gen-tools.mjs --check",
     "openapi:refresh": "node scripts/openapi-refresh.mjs",
-    "test": "node scripts/gen-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
+    "test": "node scripts/gen-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
     "prepublishOnly": "npm test && node test/publish-provenance.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
+    "check:body-mode-parity": "node test/body-mode-parity.mjs",
     "check:firewall": "node test/firewall.mjs",
     "check:registry": "node test/registry-manifests.mjs",
     "check:publish-provenance": "node test/publish-provenance.mjs"

package/src/tools.js

@@ -8,7 +8,7 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 76 tools (47 reads, 29 writes).
+// Catalog: 80 tools (49 reads, 31 writes).
 //
 // Each tool maps 1:1 to a REST endpoint at https://api.twitterapis.com. Tool arg
 // names map 1:1 to endpoint query params (every endpoint, including the POST
@@ -467,6 +467,80 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_spaces_info",
+    path: "/twitter/spaces/info",
+    description:
+      "Get metadata and the participant roster for one X Space by id, live or ended: title, lifecycle state (Scheduled, NotStarted, Running or Ended), host, topics, scheduled and actual start/end times, peak live listener count, replay view count, and the admin, speaker and listener rosters. Returns metadata only, NOT the Space audio. Note that X does not retain the per-person listener roster once a Space ends, so listeners comes back empty for an ended Space while total_live_listeners and total_replay_watched still reflect the real audience. All timestamps are millisecond-epoch numbers.",
+    shape: {
+      id: z.string().describe(
+        "The Space id: the trailing token of a x.com/i/spaces/<id> URL, e.g. '1RKZzjkoYRAKB'. A '/peek' suffix on the URL is not part of the id.",
+      ),
+      with_listeners: z.string().optional().describe(
+        "Optional. Include the listener roster. Defaults to true. X drops this roster once a Space ends, so it is empty for an ended Space regardless of this flag.",
+      ),
+      with_replays: z.string().optional().describe(
+        "Optional. Include replay availability and related metadata. Defaults to true.",
+      ),
+    },
+  },
+  {
+    name: "twitter_grok_chat",
+    path: "/twitter/grok/chat",
+    method: "POST",
+    write: true,
+    description:
+      "Ask X's own Grok a question AS your authenticated account, and get ONE complete JSON reply with the answer plus the sources it cited. Unlike a general LLM, Grok reads X in real time, so it can answer about what is being said right now, and passing a bare tweet or status URL as the message returns a structured summary of that post. Returns answer text, citations (url, title, snippet) merged and de-duplicated across every search Grok ran, the searches themselves, and the model that ACTUALLY answered (which can differ from the one you asked for). Buffered, not streamed. STATELESS: nothing is stored, so to continue a conversation pass the prior turns back in messages[] along with conversation_id. Requires an authenticated session for the acting account.",
+    shape: {
+      message: z.string().optional().describe(
+        "The prompt, for a single-turn question. A bare tweet or status URL is a first-class input and comes back as a summary of that post. Provide either this or messages[].",
+      ),
+      messages: z.string().optional().describe(
+        "Prior turns for a multi-turn conversation, oldest first, each { role: 'user' | 'grok', content: '...' }. The endpoint stores nothing, so the full history you want Grok to see must travel in this array. Provide either this or message.",
+      ),
+      conversation_id: z.string().optional().describe(
+        "Conversation id returned by a previous call. Omit on the first turn and one is created for you.",
+      ),
+      mode: z.string().optional().describe(
+        "Which Grok to use: 'auto' (default, balanced), 'fast' (quicker, less thorough) or 'expert' (slowest, most thorough). The response reports the model that actually answered, which can differ from the mode requested.",
+      ),
+      image_count: z.number().int().optional().describe(
+        "How many images Grok may generate if the prompt calls for one. Defaults to the value X's own client sends. Set 0 for a text-only answer.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
+  {
+    name: "twitter_grok_config",
+    path: "/twitter/grok/config",
+    description:
+      "Check whether the authenticated account can use Grok, and which models it may pick. Returns eligibility, X's own reasons when it is NOT eligible (passed through verbatim, since we cannot know X's policy), whether free access is enabled, and the available model options. Eligibility is a property of the X ACCOUNT rather than of the API key, so ask this about the same account you intend to run twitter_grok_chat as. Free.",
+    shape: {
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
   {
     name: "twitter_trends",
     path: "/twitter/trends",
@@ -1169,6 +1243,37 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_article_update_cover_media",
+    path: "/twitter/article/update_cover_media",
+    method: "POST",
+    write: true,
+    description:
+      "Attach an ALREADY-UPLOADED image as the cover of a DRAFT or PUBLISHED article, AS your authenticated account. This does NOT upload: call twitter_media_upload first and pass the media_id it returns. Provide the article's id (from twitter_article_create or twitter_article_list). Requires an authenticated session with write capability behind your key. Returns the updated article object with cover_media populated.",
+    shape: {
+      id: z.string().describe(
+        "The article's entity id, from twitter_article_create or twitter_article_list (e.g. 'ArticleEntity:1234567890123456789').",
+      ),
+      media_id: z.string().describe(
+        "The media id returned by twitter_media_upload for the image to use as the cover.",
+      ),
+      media_category: z.string().optional().describe(
+        "Optional. X's media category for the upload. Defaults to 'DraftTweetImage', which is what X's own article editor sends for a cover image. Only set this if you know X expects a different category.",
+      ),
+      auth_token: z.string().optional().describe(
+        "Optional. The account's auth_token cookie, to act AS that account for this call (must be paired with ct0). Sent as the x-auth-token header; never placed in the URL.",
+      ),
+      ct0: z.string().optional().describe(
+        "Optional. The account's ct0 cookie, paired with auth_token. Sent as the x-ct0 header.",
+      ),
+      proxy_url: z.string().optional().describe(
+        "Optional. Residential proxy URL to egress this call through. Recommended for writes: X soft-blocks writes from datacenter IPs as automated. Sent as the x-proxy-url header.",
+      ),
+      user_agent: z.string().optional().describe(
+        "Optional. User-Agent string to send for this session. Sent as the x-user-agent header.",
+      ),
+    },
+  },
   {
     name: "twitter_article_update_title",
     path: "/twitter/article/update_title",