@twitterapis/mcp 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0 (2026-06-25)
+
+### Added (full API parity)
+
+- Grew the catalog from 16 to **37 tools**: 27 reads and 10 write actions.
+- New reads: `twitter_user_about`, `twitter_user_affiliates`, `twitter_check_follow_relationship`, `twitter_user_tweets_complete`, `twitter_user_likes`, `twitter_followers_you_know`, `twitter_home_timeline`, `twitter_bookmarks`, `twitter_bookmark_search`, `twitter_dm_list`, `twitter_dm_conversation`.
+- New write actions: `twitter_create_tweet` (with `reply_to` / `quote`), `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`.
+- Tool annotations: every write is `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark) are `destructiveHint: true` so MCP clients can prompt before a mutating call.
+- Account-only reads and all writes act AS a linked X session; added an HTTP 409 error hint pointing users to link a session.
+
+### No breaking changes
+
+All 16 prior tool names, parameter names, and endpoint mappings are unchanged. Existing `npx @twitterapis/mcp@latest` invocations update automatically.
+
 ## 0.1.1 (2026-06-24)
 
 ### Improvements

package/README.md

@@ -1,6 +1,6 @@
 # @twitterapis/mcp
 
-Official **Model Context Protocol** server for [twitterapis.com](https://www.twitterapis.com), the Twitter / X **read** API as native tools for Claude, Cursor, Windsurf, and any MCP client.
+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 +87,11 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-All 16 tools are read-only. User endpoints accept `username` (handle without @) **or** `user_id`; tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page.
+37 tools: 27 reads and 10 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) work with just your API key. The **account-only** reads (likes, 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). 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
 
 | Tool | What it does |
 |---|---|
@@ -95,18 +99,40 @@ All 16 tools are read-only. User endpoints accept `username` (handle without @)
 | `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_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) |
 | `twitter_user_tweets_and_replies` | A user's full timeline (tweets + replies) |
+| `twitter_user_tweets_complete` | A user's near-complete tweet history in one auto-paginated call |
+| `twitter_user_media` | Images and videos a user has posted |
+| `twitter_user_mentions` | Recent public tweets mentioning a user |
+| `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_verified_followers` | A user's verified followers only |
-| `twitter_user_media` | Images and videos a user has posted |
-| `twitter_user_mentions` | Recent public tweets mentioning a user |
+| `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 |
 | `twitter_tweet_replies` | Replies to a tweet |
 | `twitter_tweet_thread` | Full author thread (connected tweet chain by same author) |
 | `twitter_tweet_retweeters` | Accounts that retweeted a tweet |
 | `twitter_list_members` | Members of a Twitter/X List |
+| `twitter_home_timeline` | Your authenticated account's Home timeline _(session)_ |
+| `twitter_bookmarks` | Your authenticated account's bookmarks _(session)_ |
+| `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)_ |
+
+### Write actions _(require a linked X session)_
+
+| Tool | What it does |
+|---|---|
+| `twitter_create_tweet` | Post a tweet; set `reply_to` to reply or `quote` to quote-tweet |
+| `twitter_delete_tweet` | Delete one of your tweets (irreversible) |
+| `twitter_favorite_tweet` / `twitter_unfavorite_tweet` | Like / unlike a tweet |
+| `twitter_retweet` / `twitter_unretweet` | Retweet / undo retweet |
+| `twitter_bookmark_tweet` / `twitter_unbookmark_tweet` | Bookmark / remove bookmark |
+| `twitter_follow_user` / `twitter_unfollow_user` | Follow / unfollow a user by id |
 
 ## Usage examples
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.1.1",
-  "description": "Official MCP server for twitterapis.com, the Twitter/X read API (search, users, followers, tweets, threads, lists) as native tools for Claude, Cursor, and any MCP client.",
+  "version": "0.2.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"

package/src/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 // @twitterapis/mcp, official MCP server for twitterapis.com
 //
-// Exposes the Twitter / X READ API as native MCP tools (search, users,
-// followers/following, tweets, threads, lists, mentions) for Claude, Cursor,
-// and any MCP client. Each tool is a thin, typed wrapper over a REST endpoint
-// at https://api.twitterapis.com. The server holds no state and forwards your
-// API key on every call. The tool catalog lives in ./tools.js.
+// Exposes the Twitter / X API as native MCP tools for Claude, Cursor, and any
+// MCP client: reads (search, users, followers/following, tweets, threads,
+// lists, mentions, likes, bookmarks, DMs, home timeline) plus write actions
+// (post/delete tweet, like, retweet, bookmark, follow, and their inverses).
+// Each tool is a thin, typed wrapper over a REST endpoint at
+// https://api.twitterapis.com. The server holds no state and forwards your API
+// key on every call. The tool catalog lives in ./tools.js.
 //
 // Config (env):
 //   TWITTERAPIS_KEY        required. Your key from https://www.twitterapis.com/signup
@@ -32,7 +34,10 @@ if (!API_KEY) {
 }
 
 // ── REST call ────────────────────────────────────────────────────────────────
-async function callEndpoint(path, args) {
+// 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") {
   const q = buildQuery(args);
   const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
 
@@ -40,13 +45,13 @@ async function callEndpoint(path, args) {
   const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
   try {
     const res = await fetch(url, {
-      method: "GET",
+      method,
       headers: {
         // The API accepts either header; send both for maximum compatibility.
         Authorization: `Bearer ${API_KEY}`,
         "x-api-key": API_KEY,
         accept: "application/json",
-        "user-agent": "twitterapis-mcp/0.1.1",
+        "user-agent": "twitterapis-mcp/0.2.0",
       },
       signal: ctrl.signal,
     });
@@ -61,7 +66,9 @@ async function callEndpoint(path, args) {
               ? " (access forbidden. The resource may be private or your plan does not include this endpoint)"
               : res.status === 404
                 ? " (not found. The user, tweet, or list may have been deleted or the id is wrong)"
-                : res.status === 429
+                : res.status === 409
+                  ? " (no authenticated X session for this key. Write actions and account-only reads (likes, bookmarks, DMs, home timeline, follow, post) require linking an X account/session to your key first; see https://www.twitterapis.com/dashboard)"
+                  : res.status === 429
                   ? " (rate limited. Wait a few seconds and retry; reduce request frequency or increase TWITTERAPIS_TIMEOUT_MS if needed)"
                   : res.status >= 500
                     ? " (upstream API error. Retry in a moment; if persistent, check https://www.twitterapis.com/status)"
@@ -78,13 +85,22 @@ async function callEndpoint(path, args) {
 }
 
 // ── MCP server ───────────────────────────────────────────────────────────────
-const server = new McpServer({ name: "twitterapis", version: "0.1.1" });
+const server = new McpServer({ name: "twitterapis", version: "0.2.0" });
 
 for (const tool of TOOLS) {
+  const method = tool.method || "GET";
+  // Surface read/write/destructive intent so MCP clients can warn before a
+  // mutating call (default = read-only).
+  const annotations = {
+    title: tool.name,
+    readOnlyHint: !tool.write,
+    destructiveHint: Boolean(tool.destructive),
+    openWorldHint: true,
+  };
   server.registerTool(
     tool.name,
-    { description: tool.description, inputSchema: tool.shape },
-    async (args) => callEndpoint(tool.path, args),
+    { description: tool.description, inputSchema: tool.shape, annotations },
+    async (args) => callEndpoint(tool.path, args, method),
   );
 }
 

package/src/tools.js

@@ -1,6 +1,12 @@
 // Tool catalog + pure query-builder for @twitterapis/mcp.
 // Kept separate from the server wiring (index.js) so it can be unit-tested
 // without spawning the stdio transport.
+//
+// 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 write actions, reads its params from the query string). A tool with
+// `method: "POST"` is a write that acts on behalf of the authenticated account
+// behind your API key; reads are GET and default when `method` is omitted.
 import { z } from "zod";
 
 // ── Shared Zod input-schema fragments ───────────────────────────────────────
@@ -28,9 +34,20 @@ 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.",
+  ),
+};
 
-// ── Read-only tool catalog. Tool arg names map 1:1 to endpoint query params. ─
+// ── Tool catalog. Reads are GET (default); writes set method:"POST". ─────────
+// write:true   -> action mutates account/Twitter state (annotated readOnlyHint:false)
+// destructive:true -> action removes/reverses state (delete, un-follow/like/RT/bookmark)
 export const TOOLS = [
+  // ── Reads: search + discovery ──────────────────────────────────────────────
   {
     name: "twitter_advanced_search",
     path: "/twitter/tweet/advanced_search",
@@ -80,11 +97,46 @@ 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.",
+    shape: { ...USER_REF },
+  },
+  {
+    name: "twitter_user_affiliates",
+    path: "/twitter/user/affiliates",
+    description:
+      "List the affiliated accounts of an organization profile (the smaller accounts X displays under a company's 'Affiliated' badge, e.g. employees or sub-brands). Provide a username or user_id. Returns profile data per affiliate plus a pagination cursor. Returns empty for accounts with no affiliations.",
+    shape: {
+      ...USER_REF,
+      team: z.string().optional().describe(
+        "Optional team/sub-group name to filter affiliates by, when the org exposes named teams.",
+      ),
+      ...PAGINATION,
+    },
+  },
+  {
+    name: "twitter_check_follow_relationship",
+    path: "/twitter/user/check_follow_relationship",
+    description:
+      "Check the follow relationship between two accounts by numeric user id: whether the source follows the target, whether the target follows the source, blocking/muting flags where available. Both ids are required. Use this to verify a follow before/after a follow action, or to detect mutuals.",
+    shape: {
+      source_user_id: z.string().describe(
+        "Numeric user id of the SOURCE account (the 'is this account following...' subject).",
+      ),
+      target_user_id: z.string().describe(
+        "Numeric user id of the TARGET account (the '...the target?' object).",
+      ),
+    },
+  },
+  // ── Reads: a user's tweets / timeline ──────────────────────────────────────
   {
     name: "twitter_user_tweets",
     path: "/twitter/user/tweets",
     description:
-      "Get a user's recent original tweets, excluding replies and retweets. Returns tweet text, id, timestamp, and engagement metrics. Paginate with cursor to go further back. Use this to analyse a user's own content, opinions, or posting cadence. For replies too, use twitter_user_tweets_and_replies.",
+      "Get a user's recent original tweets, excluding replies and retweets. Returns tweet text, id, timestamp, and engagement metrics. Paginate with cursor to go further back. Use this to analyse a user's own content, opinions, or posting cadence. For replies too, use twitter_user_tweets_and_replies; for the full back-catalogue in one call, use twitter_user_tweets_complete.",
     shape: { ...USER_REF, ...PAGINATION },
   },
   {
@@ -94,6 +146,52 @@ export const TOOLS = [
       "Get a user's full activity timeline: their original tweets AND replies to others. Useful for understanding how someone engages with a community, not just what they post. Paginate with cursor. To see only original tweets, use twitter_user_tweets.",
     shape: { ...USER_REF, ...PAGINATION },
   },
+  {
+    name: "twitter_user_tweets_complete",
+    path: "/twitter/user/tweets/complete",
+    description:
+      "Get a user's near-complete original-tweet history in a single call, auto-paginating server-side up to a cap (Twitter's ~3200-tweet per-user ceiling). Heavier than twitter_user_tweets; use when you want the whole back-catalogue at once rather than page-by-page. Returns a flat tweet array. Requires the numeric user_id (resolve a handle first with twitter_user_info).",
+    shape: {
+      user_id: z.string().describe(
+        "Numeric Twitter/X user id. Required: this endpoint does not accept a username. Resolve a handle to a user_id first with twitter_user_info.",
+      ),
+      max: z.number().int().min(1).max(3200).optional().describe(
+        "Maximum number of tweets to collect (default 800, hard ceiling 3200). Higher values take longer and cost more.",
+      ),
+    },
+  },
+  {
+    name: "twitter_user_media",
+    path: "/twitter/user/media",
+    description:
+      "Get the images and videos a user has posted. Returns media-containing tweets with URLs to the media files, dimensions, and type (photo/video/animated_gif). Paginate with cursor. Use this to pull a user's visual content history.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_user_mentions",
+    path: "/twitter/user/mentions",
+    description:
+      "Get recent public tweets that mention (@ tag) a user. Searches for tweets directed at the username using the to: operator. Returns matching tweets with author info and metrics. Paginate with cursor. Use this to monitor brand mentions, replies directed at an account, or public conversations about a person.",
+    shape: {
+      username: z.string().describe(
+        "Twitter/X handle WITHOUT the leading @ of the user to find mentions for (e.g. 'openai' to find tweets mentioning @openai).",
+      ),
+      ...PAGINATION,
+    },
+  },
+  {
+    name: "twitter_user_likes",
+    path: "/twitter/user/likes",
+    description:
+      "Get the tweets a user has liked (their public Likes tab), most recent first. Returns each liked tweet with author and metrics, plus a pagination cursor. Use this to infer interests or find content a user has endorsed. Returns empty if the account hides its likes. Requires the numeric user_id (resolve a handle first with twitter_user_info).",
+    shape: {
+      user_id: z.string().describe(
+        "Numeric Twitter/X user id (e.g. '44196397'). Required: this endpoint does not accept a username. Resolve a handle to a user_id first with twitter_user_info.",
+      ),
+      ...PAGINATION,
+    },
+  },
+  // ── Reads: followers / following graph ─────────────────────────────────────
   {
     name: "twitter_user_followers",
     path: "/twitter/user/followers",
@@ -116,24 +214,18 @@ export const TOOLS = [
     shape: { ...USER_REF, ...PAGINATION },
   },
   {
-    name: "twitter_user_media",
-    path: "/twitter/user/media",
+    name: "twitter_followers_you_know",
+    path: "/twitter/user/followers_you_know",
     description:
-      "Get the images and videos a user has posted. Returns media-containing tweets with URLs to the media files, dimensions, and type (photo/video/animated_gif). Paginate with cursor. Use this to pull a user's visual content history.",
-    shape: { ...USER_REF, ...PAGINATION },
-  },
-  {
-    name: "twitter_user_mentions",
-    path: "/twitter/user/mentions",
-    description:
-      "Get recent public tweets that mention (@ tag) a user. Searches for tweets directed at the username using the to: operator. Returns matching tweets with author info and metrics. Paginate with cursor. Use this to monitor brand mentions, replies directed at an account, or public conversations about a person.",
+      "List the 'Followers you know' for a target user id: the followers of that account that YOUR authenticated account also follows (mutual-connection overlap). Requires an authenticated session behind your key. Returns profile data per overlap account plus a cursor.",
     shape: {
-      username: z.string().describe(
-        "Twitter/X handle WITHOUT the leading @ of the user to find mentions for (e.g. 'openai' to find tweets mentioning @openai).",
+      user_id: z.string().describe(
+        "Numeric user id of the target account to compute shared followers against.",
       ),
       ...PAGINATION,
     },
   },
+  // ── Reads: a single tweet + its conversation ───────────────────────────────
   {
     name: "twitter_tweet_detail",
     path: "/twitter/tweet/detail",
@@ -174,6 +266,174 @@ export const TOOLS = [
       ...PAGINATION,
     },
   },
+  // ── Reads: authenticated-account surfaces (require a session behind your key) ─
+  {
+    name: "twitter_home_timeline",
+    path: "/twitter/user/home_timeline",
+    description:
+      "Get YOUR authenticated account's Home timeline (the 'Following'/'For you' feed), most recent first. Requires an authenticated session behind your key. Returns tweets with author and metrics plus a cursor. Use this to read what your account would see when it opens X.",
+    shape: { ...PAGINATION },
+  },
+  {
+    name: "twitter_bookmarks",
+    path: "/twitter/user/bookmarks",
+    description:
+      "List YOUR authenticated account's bookmarked tweets, most recent first. Requires an authenticated session behind your key. Returns each bookmarked tweet with author and metrics plus a cursor.",
+    shape: { ...PAGINATION },
+  },
+  {
+    name: "twitter_bookmark_search",
+    path: "/twitter/user/bookmark_search",
+    description:
+      "Full-text search within YOUR authenticated account's bookmarks. Requires an authenticated session behind your key. Returns matching bookmarked tweets plus a cursor. Use this to retrieve a previously bookmarked tweet by keyword.",
+    shape: {
+      query: z.string().describe(
+        "Search terms to match against your bookmarked tweets' text.",
+      ),
+      ...PAGINATION,
+    },
+  },
+  {
+    name: "twitter_dm_list",
+    path: "/twitter/dm/list",
+    description:
+      "List YOUR authenticated account's Direct Message conversations (inbox), each with the participant and a conversation_id you can pass to twitter_dm_conversation. Requires an authenticated session behind your key. Read-only: this does not send DMs.",
+    shape: {},
+  },
+  {
+    name: "twitter_dm_conversation",
+    path: "/twitter/dm/conversation",
+    description:
+      "Get the messages in one Direct Message conversation by its conversation_id (from twitter_dm_list). Requires an authenticated session behind your key. Returns each message with sender id, time, and text. Read-only: this does not send DMs.",
+    shape: {
+      conversation_id: z.string().describe(
+        "The conversation_id from a twitter_dm_list entry identifying which DM thread to read.",
+      ),
+    },
+  },
+
+  // ── Writes: tweet authoring ────────────────────────────────────────────────
+  {
+    name: "twitter_create_tweet",
+    path: "/twitter/tweet/create",
+    method: "POST",
+    write: true,
+    description:
+      "Post a new tweet AS your authenticated account. Set reply_to to post a reply, or quote to post a quote-tweet. This publishes publicly and is not silently reversible (use twitter_delete_tweet to remove it). Requires an authenticated session with write capability behind your key. Returns the new tweet_id and url.",
+    shape: {
+      text: z.string().min(1).describe(
+        "The tweet body text (1 to 280 characters, or longer if the account has extended limits).",
+      ),
+      reply_to: z.string().optional().describe(
+        "Optional. Numeric id of the tweet to reply to. When set, this tweet is posted as a reply in that conversation.",
+      ),
+      quote: z.string().optional().describe(
+        "Optional. Numeric id of the tweet to quote. When set, this tweet quote-tweets that tweet.",
+      ),
+      media_ids: z.string().optional().describe(
+        "Optional. Comma-separated media id(s) from a prior media upload to attach (images/video).",
+      ),
+      ...ACCOUNT,
+    },
+  },
+  {
+    name: "twitter_delete_tweet",
+    path: "/twitter/tweet/delete",
+    method: "POST",
+    write: true,
+    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 },
+  },
+  // ── Writes: engagement (favorite / retweet / bookmark) + inverses ──────────
+  {
+    name: "twitter_favorite_tweet",
+    path: "/twitter/tweet/favorite",
+    method: "POST",
+    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 },
+  },
+  {
+    name: "twitter_unfavorite_tweet",
+    path: "/twitter/tweet/unfavorite",
+    method: "POST",
+    write: true,
+    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 },
+  },
+  {
+    name: "twitter_retweet",
+    path: "/twitter/tweet/retweet",
+    method: "POST",
+    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 },
+  },
+  {
+    name: "twitter_unretweet",
+    path: "/twitter/tweet/unretweet",
+    method: "POST",
+    write: true,
+    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 },
+  },
+  {
+    name: "twitter_bookmark_tweet",
+    path: "/twitter/tweet/bookmark",
+    method: "POST",
+    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 },
+  },
+  {
+    name: "twitter_unbookmark_tweet",
+    path: "/twitter/tweet/unbookmark",
+    method: "POST",
+    write: true,
+    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 },
+  },
+  // ── Writes: follow graph ───────────────────────────────────────────────────
+  {
+    name: "twitter_follow_user",
+    path: "/twitter/user/follow",
+    method: "POST",
+    write: true,
+    description:
+      "Follow a user AS your authenticated account, by numeric user_id. Requires write capability behind your key. Reverse with twitter_unfollow_user.",
+    shape: {
+      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,
+    },
+  },
+  {
+    name: "twitter_unfollow_user",
+    path: "/twitter/user/unfollow",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Unfollow a user AS your authenticated account, by numeric user_id. Requires write capability behind your key.",
+    shape: {
+      user_id: z.string().describe(
+        "Numeric user id of the account to unfollow.",
+      ),
+      ...ACCOUNT,
+    },
+  },
 ];
 
 // Pure query-string builder: drops undefined/null/empty values, URL-encodes the rest.