@twitterapis/mcp 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.1 (2026-06-24)
+
+### Improvements
+
+- Tool descriptions rewritten. All 16 tool descriptions and parameter hints now use precise, concrete language matched to how MCP clients surface them. Removed hedging phrases, tightened scope statements, and added concrete value hints for paginated parameters (cursor, count limits).
+- Error hints added. Each tool now carries structured error guidance covering the five most common failure codes (401, 402, 403, 404, 429) with a plain-English fix per code, so agents can self-correct without a docs lookup.
+- README optimized. Quick-start, setup matrix (Claude Desktop, Cursor, Windsurf, VS Code), configuration table, full tool reference, usage examples, troubleshooting section, and pricing note all revised for clarity and scannability.
+- GitHub repository established. The package now carries a canonical repository field pointing to github.com/TwitterAPIs/twitterapis-mcp (public, MIT licensed).
+
+### No breaking changes
+
+All 16 tool names, parameter names, and API endpoint mappings are unchanged. Existing `npx @twitterapis/mcp@latest` invocations update automatically.
+
+## 0.1.0
+
+First public release of the `@twitterapis/mcp` npm package. 16 read-only Twitter/X tools: search, user info, timeline, followers and following, verified followers, media, mentions, tweet detail, replies, threads, retweeters, and list members.

package/README.md

@@ -1,16 +1,18 @@
 # @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, and any MCP client.
+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.
 
-Ask your agent to *"find the latest tweets about AI agents"* or *"pull @openai's followers"* 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 per call.
+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.
 
-## Install
+## Quick start
 
-No install needed — run it on demand with `npx`. You only need an API key (free `$0.50` in credits, no card): **https://www.twitterapis.com/signup**.
+No install needed. Run with `npx`. You need one thing: an API key (free $0.50 in credits, no card required): **[twitterapis.com/signup](https://www.twitterapis.com/signup)**.
+
+## Setup
 
 ### Claude Desktop
 
-Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 ```json
 {
@@ -24,9 +26,27 @@ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 }
 ```
 
+Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
+
 ### Cursor
 
-`~/.cursor/mcp.json` (or Settings → MCP → Add):
+`~/.cursor/mcp.json` (or Settings → MCP → Add New Server):
+
+```json
+{
+  "mcpServers": {
+    "twitterapis": {
+      "command": "npx",
+      "args": ["-y", "@twitterapis/mcp@latest"],
+      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
@@ -40,48 +60,129 @@ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 }
 ```
 
-Restart the client and the `twitter_*` tools appear.
+### VS Code (Copilot / agent mode)
+
+`.vscode/mcp.json` in your workspace, or the user-level MCP settings:
+
+```json
+{
+  "servers": {
+    "twitterapis": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@twitterapis/mcp@latest"],
+      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
+    }
+  }
+}
+```
 
 ## Configuration
 
 | Env var | Required | Default | Purpose |
 |---|---|---|---|
-| `TWITTERAPIS_KEY` | ✅ | — | Your API key from the dashboard |
-| `TWITTERAPIS_BASE_URL` | | `https://api.twitterapis.com` | Override the API host |
-| `TWITTERAPIS_TIMEOUT_MS` | | `30000` | Per-request timeout |
+| `TWITTERAPIS_KEY` | Yes | (none) | API key from [dashboard](https://www.twitterapis.com/dashboard) |
+| `TWITTERAPIS_BASE_URL` | No | `https://api.twitterapis.com` | Override the API host |
+| `TWITTERAPIS_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds |
 
 ## Tools
 
-All read-only. User endpoints take `username` **or** `user_id`; tweet endpoints take `id` **or** `url`; list endpoints page with `count` + `cursor`.
+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.
 
 | Tool | What it does |
 |---|---|
-| `twitter_advanced_search` | Search tweets with X operators (`from:`, `min_faves:`, `filter:`, …) |
-| `twitter_user_search` | Search accounts by name/keyword |
-| `twitter_user_info` | Full profile by handle |
-| `twitter_user_info_by_id` | Full profile by numeric id |
-| `twitter_user_tweets` | A user's recent tweets (no replies) |
+| `twitter_advanced_search` | Search tweets with X operators (`from:`, `min_faves:`, `since:`, `filter:links`, etc.) |
+| `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_tweets` | A user's recent original tweets (replies excluded) |
 | `twitter_user_tweets_and_replies` | A user's full timeline (tweets + replies) |
 | `twitter_user_followers` | Accounts that follow a user |
 | `twitter_user_following` | Accounts a user follows |
-| `twitter_user_verified_followers` | A user's verified followers |
-| `twitter_user_media` | Media a user has posted |
-| `twitter_user_mentions` | Recent tweets mentioning a user |
-| `twitter_tweet_detail` | One tweet's full detail |
+| `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_tweet_detail` | Single tweet: text, author, metrics, media, quoted/reply context |
 | `twitter_tweet_replies` | Replies to a tweet |
-| `twitter_tweet_thread` | A tweet's self-thread |
+| `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 List |
+| `twitter_list_members` | Members of a Twitter/X List |
+
+## Usage examples
+
+### Search for trending AI tweets
+
+> "Find the most popular tweets about AI agents posted this week"
+
+The agent calls `twitter_advanced_search` with:
+```
+query: "AI agents min_faves:200 since:2024-01-01"
+product: "Top"
+count: 20
+```
+
+### Pull a user's recent posts
+
+> "Get the last 10 tweets from @sama"
+
+The agent calls `twitter_user_tweets` with:
+```
+username: "sama"
+count: 10
+```
+
+### Read a full thread
+
+> "Get the full thread for this tweet: https://x.com/karpathy/status/1849....."
+
+The agent calls `twitter_tweet_thread` with:
+```
+url: "https://x.com/karpathy/status/1849....."
+```
+
+### Paginate through followers
+
+> "List the first 100 followers of @openai, then the next 100"
+
+First call, `twitter_user_followers`: `{ username: "openai", count: 100 }`
+Second call, pass back the `cursor` from the first response: `{ username: "openai", count: 100, cursor: "<cursor from response>" }`
+
+### Monitor brand mentions
+
+> "Show me recent tweets mentioning @twitterapis"
+
+The agent calls `twitter_user_mentions` with:
+```
+username: "twitterapis"
+count: 50
+```
+
+## Troubleshooting
+
+**`HTTP 401 (invalid or missing API key)`** Check that `TWITTERAPIS_KEY` is set correctly in your MCP client config and matches the key shown in your [dashboard](https://www.twitterapis.com/dashboard).
+
+**`HTTP 402 (insufficient credits)`** Top up at [twitterapis.com/dashboard](https://www.twitterapis.com/dashboard). Your first $0.50 is free at signup.
+
+**`HTTP 403 (access forbidden)`** The account or tweet may be private/protected, or your plan does not include this endpoint.
+
+**`HTTP 404 (not found)`** The user, tweet, or list may have been deleted, suspended, or the id/handle is wrong.
+
+**`HTTP 429 (rate limited)`** Wait a few seconds and retry. If you hit this frequently, add `"TWITTERAPIS_TIMEOUT_MS": "60000"` to your env config and space out bulk requests.
+
+**`Request failed: timed out after 30000ms`** The default timeout is 30 s. For large paginated fetches set `TWITTERAPIS_TIMEOUT_MS` to a higher value (e.g. `60000`).
+
+**Tools do not appear in Claude / Cursor** Ensure `npx` is on your PATH and Node.js 18+ is installed (`node --version`). Check MCP client logs for startup errors.
 
 ## Pricing
 
-Calls are billed to your twitterapis.com account at the standard read rate (`$0.0008`/call); your first `$0.50` is free. See [pricing](https://www.twitterapis.com/pricing).
+Calls are billed to your twitterapis.com account at the standard read rate ($0.0008/call, or $0.04 per 1,000 tweets (each call returns about 20 tweets)); your first $0.50 is free. See [twitterapis.com/pricing](https://www.twitterapis.com/pricing).
 
 ## Links
 
-- Docs — https://docs.twitterapis.com
-- Dashboard / keys — https://www.twitterapis.com/dashboard
-- REST API (no MCP needed) — https://api.twitterapis.com
+- 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)
 
 ## License
 

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@twitterapis/mcp",
-  "version": "0.1.0",
-  "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.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.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TwitterAPIs/twitterapis-mcp.git"
+  },
   "type": "module",
   "bin": {
     "twitterapis-mcp": "src/index.js"
@@ -10,7 +14,8 @@
   "files": [
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"

package/src/index.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-// @twitterapis/mcp — official MCP server for twitterapis.com
+// @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
+// 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
-//   TWITTERAPIS_BASE_URL   optional — defaults to https://api.twitterapis.com
-//   TWITTERAPIS_TIMEOUT_MS optional — per-request timeout (default 30000)
+//   TWITTERAPIS_KEY        required. Your key from https://www.twitterapis.com/signup
+//   TWITTERAPIS_BASE_URL   optional. Defaults to https://api.twitterapis.com
+//   TWITTERAPIS_TIMEOUT_MS optional. Per-request timeout (default 30000)
 //
 // Run:  npx -y @twitterapis/mcp@latest   (stdio transport)
 
@@ -46,7 +46,7 @@ async function callEndpoint(path, args) {
         Authorization: `Bearer ${API_KEY}`,
         "x-api-key": API_KEY,
         accept: "application/json",
-        "user-agent": "twitterapis-mcp/0.1.0",
+        "user-agent": "twitterapis-mcp/0.1.1",
       },
       signal: ctrl.signal,
     });
@@ -54,12 +54,18 @@ async function callEndpoint(path, args) {
     if (!res.ok) {
       const hint =
         res.status === 401
-          ? " (check TWITTERAPIS_KEY)"
+          ? " (invalid or missing API key, verify TWITTERAPIS_KEY at https://www.twitterapis.com/dashboard)"
           : res.status === 402
-            ? " (insufficient credits — top up at https://www.twitterapis.com/dashboard)"
-            : res.status === 429
-              ? " (rate limited — retry shortly)"
-              : "";
+            ? " (insufficient credits, top up at https://www.twitterapis.com/dashboard)"
+            : res.status === 403
+              ? " (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
+                  ? " (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)"
+                    : "";
       return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}` }] };
     }
     return { content: [{ type: "text", text: body }] };
@@ -72,7 +78,7 @@ async function callEndpoint(path, args) {
 }
 
 // ── MCP server ───────────────────────────────────────────────────────────────
-const server = new McpServer({ name: "twitterapis", version: "0.1.0" });
+const server = new McpServer({ name: "twitterapis", version: "0.1.1" });
 
 for (const tool of TOOLS) {
   server.registerTool(

package/src/tools.js

@@ -5,68 +5,175 @@ import { z } from "zod";
 
 // ── Shared Zod input-schema fragments ───────────────────────────────────────
 const PAGINATION = {
-  count: z.number().int().positive().optional().describe("Max items to return for this page (endpoint default applies if omitted)."),
-  cursor: z.string().optional().describe("Pagination cursor returned by a previous call to fetch the next page."),
+  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.",
+  ),
 };
 const USER_REF = {
-  username: z.string().optional().describe('Twitter/X handle, without the leading @ (e.g. "elonmusk"). Provide this OR user_id.'),
-  user_id: z.string().optional().describe("Numeric user id. Provide this OR username."),
+  username: z.string().optional().describe(
+    'Twitter/X handle WITHOUT the leading @ (e.g. "elonmusk", "openai"). Provide exactly one of username or user_id.',
+  ),
+  user_id: z.string().optional().describe(
+    'Numeric Twitter/X user id (e.g. "44196397"). Provide exactly one of username or user_id.',
+  ),
 };
 const TWEET_REF = {
-  id: z.string().optional().describe('Tweet id (e.g. "1789..."). Provide this OR url.'),
-  url: z.string().optional().describe("Full tweet URL (https://x.com/<user>/status/<id>). Provide this OR id."),
+  id: z.string().optional().describe(
+    'Tweet/post numeric id (e.g. "1789012345678901234"). Provide exactly one of id or url.',
+  ),
+  url: z.string().optional().describe(
+    'Full tweet URL, e.g. "https://x.com/elonmusk/status/1789012345678901234". Provide exactly one of id or url.',
+  ),
 };
 
 // ── Read-only tool catalog. Tool arg names map 1:1 to endpoint query params. ─
 export const TOOLS = [
-  { name: "twitter_advanced_search", path: "/twitter/tweet/advanced_search",
-    description: "Search recent tweets with X's advanced-search syntax (operators like from:, to:, since:, until:, min_faves:, filter:). Returns matching tweets with author, metrics, and a cursor for paging.",
-    shape: { query: z.string().describe('Search query, e.g. "AI agents min_faves:100" or "from:openai".'), product: z.enum(["Top", "Latest", "Media", "People"]).optional().describe('Result tab. "Latest" for reverse-chron, "Top" for ranked (default).'), ...PAGINATION } },
-  { name: "twitter_user_search", path: "/twitter/user/search",
-    description: "Search for users/accounts by name or keyword. Returns matching profiles with a paging cursor.",
-    shape: { query: z.string().describe("Name or keyword to search accounts for."), ...PAGINATION } },
-  { name: "twitter_user_info", path: "/twitter/user/info",
-    description: "Get a user's full profile by handle: bio, follower/following counts, verification, location, created date, pinned tweet.",
-    shape: { username: z.string().describe("Twitter/X handle without the leading @.") } },
-  { name: "twitter_user_info_by_id", path: "/twitter/user/info_by_id",
-    description: "Get a user's full profile by numeric user id (use when you have the id but not the handle).",
-    shape: { user_id: z.string().describe("Numeric user id.") } },
-  { name: "twitter_user_tweets", path: "/twitter/user/tweets",
-    description: "Get a user's recent original tweets (no replies). Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_tweets_and_replies", path: "/twitter/user/tweets_and_replies",
-    description: "Get a user's recent tweets AND replies (their full timeline). Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_followers", path: "/twitter/user/followers",
-    description: "List the accounts that follow a user. Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_following", path: "/twitter/user/following",
-    description: "List the accounts a user follows. Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_verified_followers", path: "/twitter/user/verified_followers",
-    description: "List a user's verified (blue/business) followers. Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_media", path: "/twitter/user/media",
-    description: "Get the media (images/videos) a user has posted. Cursored.",
-    shape: { ...USER_REF, ...PAGINATION } },
-  { name: "twitter_user_mentions", path: "/twitter/user/mentions",
-    description: "Get recent tweets that mention a user (implemented as a to:<username> search). Cursored.",
-    shape: { username: z.string().describe("Twitter/X handle without the leading @."), ...PAGINATION } },
-  { name: "twitter_tweet_detail", path: "/twitter/tweet/detail",
-    description: "Get a single tweet's full detail: text, author, metrics, media, and quoted/replied context.",
-    shape: { ...TWEET_REF } },
-  { name: "twitter_tweet_replies", path: "/twitter/tweet/replies",
-    description: "Get the replies to a tweet. Cursored.",
-    shape: { ...TWEET_REF, ...PAGINATION } },
-  { name: "twitter_tweet_thread", path: "/twitter/tweet/thread",
-    description: "Get the full self-thread for a tweet (the author's connected chain). Cursored.",
-    shape: { ...TWEET_REF, ...PAGINATION } },
-  { name: "twitter_tweet_retweeters", path: "/twitter/tweet/retweeters",
-    description: "List the accounts that retweeted a tweet. Cursored.",
-    shape: { ...TWEET_REF, ...PAGINATION } },
-  { name: "twitter_list_members", path: "/twitter/list/members",
-    description: "List the members of a Twitter/X List by list id. Cursored.",
-    shape: { list_id: z.string().describe("Numeric List id."), ...PAGINATION } },
+  {
+    name: "twitter_advanced_search",
+    path: "/twitter/tweet/advanced_search",
+    description:
+      "Search recent tweets using X's advanced-search operators. Supports from:, to:, since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, min_retweets:N, filter:links, -filter:replies, lang:en, and free-text. Returns tweet text, author info, engagement metrics, and a pagination cursor. Use product='Latest' for chronological results; 'Top' (default) for engagement-ranked. Example queries: 'AI agents min_faves:100', 'from:openai filter:links since:2024-01-01', '#buildinpublic -filter:replies lang:en'.",
+    shape: {
+      query: z.string().describe(
+        "Full advanced-search query string. Supports X operators: from:handle, to:handle, since:YYYY-MM-DD, until:YYYY-MM-DD, min_faves:N, min_retweets:N, filter:links, filter:images, filter:videos, -filter:replies, lang:en, #hashtag, \"exact phrase\". Example: 'from:openai min_faves:500 since:2024-01-01'.",
+      ),
+      product: z.enum(["Top", "Latest", "Media", "People"]).optional().describe(
+        "Result ranking mode. 'Latest' = reverse-chronological (best for monitoring). 'Top' = engagement-ranked (best for finding popular tweets, default when omitted). 'Media' = tweets with images/video. 'People' = matching user accounts.",
+      ),
+      ...PAGINATION,
+    },
+  },
+  {
+    name: "twitter_user_search",
+    path: "/twitter/user/search",
+    description:
+      "Search for Twitter/X user accounts by name, keyword, or topic. Returns matching profiles (username, display name, bio, follower count, verification status) with a pagination cursor. Use this to discover accounts in a niche, find brand handles, or locate a person when you only know their name.",
+    shape: {
+      query: z.string().describe(
+        "Name, keyword, or topic to search accounts for. Examples: 'OpenAI', 'AI researcher', 'tech founder'.",
+      ),
+      ...PAGINATION,
+    },
+  },
+  {
+    name: "twitter_user_info",
+    path: "/twitter/user/info",
+    description:
+      "Get a user's complete public profile by their @handle: display name, bio, follower count, following count, verification status, location, website, account creation date, and pinned tweet. Use this before fetching tweets or followers to confirm the account exists and resolve the numeric user_id.",
+    shape: {
+      username: z.string().describe(
+        "Twitter/X handle WITHOUT the leading @ (e.g. 'elonmusk', 'openai', 'sama').",
+      ),
+    },
+  },
+  {
+    name: "twitter_user_info_by_id",
+    path: "/twitter/user/info_by_id",
+    description:
+      "Get a user's complete public profile by their numeric user id. Identical response to twitter_user_info. Use this when you already have a user_id from a previous API response and want to avoid a handle lookup.",
+    shape: {
+      user_id: z.string().describe(
+        "Numeric Twitter/X user id (e.g. '44196397' for @elonmusk). Found in responses from other tools as user_id or author_id.",
+      ),
+    },
+  },
+  {
+    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.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_user_tweets_and_replies",
+    path: "/twitter/user/tweets_and_replies",
+    description:
+      "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_followers",
+    path: "/twitter/user/followers",
+    description:
+      "List the accounts that follow a given user. Returns profile data for each follower (username, display name, bio, follower count). Paginate with cursor for large audiences. Useful for audience analysis, finding who follows a brand or influencer.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_user_following",
+    path: "/twitter/user/following",
+    description:
+      "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_verified_followers",
+    path: "/twitter/user/verified_followers",
+    description:
+      "List a user's followers who have a verified account (checkmark). Filters the follower list to verified accounts only, useful for identifying notable or institutional followers. Paginate with cursor.",
+    shape: { ...USER_REF, ...PAGINATION },
+  },
+  {
+    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_tweet_detail",
+    path: "/twitter/tweet/detail",
+    description:
+      "Get the full detail of a single tweet: text, author profile, post timestamp, like/retweet/reply/quote counts, attached media, referenced quoted tweet, and parent reply context. Use this to inspect a specific tweet before fetching its replies or thread. Accepts either the tweet id or its full URL.",
+    shape: { ...TWEET_REF },
+  },
+  {
+    name: "twitter_tweet_replies",
+    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 },
+  },
+  {
+    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 },
+  },
+  {
+    name: "twitter_tweet_retweeters",
+    path: "/twitter/tweet/retweeters",
+    description:
+      "List the accounts that retweeted a specific tweet. Returns profile data for each retweeter. Paginate with cursor. Useful for finding who amplified a piece of content or mapping a tweet's distribution network.",
+    shape: { ...TWEET_REF, ...PAGINATION },
+  },
+  {
+    name: "twitter_list_members",
+    path: "/twitter/list/members",
+    description:
+      "List the members of a Twitter/X List by its numeric list id. Returns profile data for each member. Paginate with cursor. Use this to enumerate curated account sets, including competitor lists, industry watchlists, or media outlet lists. The list_id appears in the X.com list URL (x.com/i/lists/<list_id>).",
+    shape: {
+      list_id: z.string().describe(
+        "Numeric Twitter/X List id. Found in the list URL: x.com/i/lists/<list_id>.",
+      ),
+      ...PAGINATION,
+    },
+  },
 ];
 
 // Pure query-string builder: drops undefined/null/empty values, URL-encodes the rest.