@twitterapis/mcp 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.16.0 (2026-09-29)
+
+### Changed
+
+- **A read rides out an API restart.** A read (GET) that gets the gateway's
+  HTML 502/503, or a refused connection, is retried after 3 and
+  then 8 seconds, so a deploy restart no longer surfaces as a Bad Gateway error.
+  The API's own JSON errors, gateway timeouts, DNS or TLS failures
+  and every write are never retried, so a request the API may already have
+  handled is not sent twice.
+- `twitter_tweet_quotes` explains the Top fallback: an empty first Top page is
+  served from Latest (`product_used`, `top_fallback`) and its `next_cursor`
+  keeps paging that list.
+
+## 0.15.0 (2026-09-29)
+
+### Added
+
+- **Agent-actionable paywall.** A missing key, a rejected credential (401
+  unauthorized), an empty balance (402 insufficient_credits) and a missing or
+  expired X session (409 session_required, 401 session_dead) now return a structured payload
+  instead of a prose hint: `needs` (`account`, `valid_key`, `credits` or
+  `x_session`), the page to send the user to (`action_url`: signup, dashboard,
+  buy credits) or the tool to call next (`next_tool`: twitter_user_login), and
+  one sentence the agent can relay, both in the text and as `structuredContent`.
+  Other failures keep their existing hints.
+
 ## 0.14.0 (2026-09-29)
 
 - **`@twitterapis/mcp/server` export and `authHeaders`.** The package now

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -33,7 +33,7 @@
     "build": "node scripts/gen-tools.mjs --write && node scripts/gen-manifest-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 scripts/gen-manifest-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/feedback.test.mjs && node test/hint-for.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/snapshot-redaction.mjs && node test/per-caller-state.test.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs && node scripts/__tests__/reconcile-mcp-publish-chain.test.mjs",
+    "test": "node scripts/gen-tools.mjs --check && node scripts/gen-manifest-tools.mjs --check && node test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/feedback.test.mjs && node test/hint-for.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/snapshot-redaction.mjs && node test/per-caller-state.test.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs && node scripts/__tests__/reconcile-mcp-publish-chain.test.mjs && node test/paywall.test.mjs && node test/retry.test.mjs",
     "prepublishOnly": "npm test && node test/publish-provenance.mjs && node scripts/prepublish-version-class.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:body-mode-parity": "node test/body-mode-parity.mjs",

package/src/server.js

@@ -41,6 +41,95 @@ const NOT_FOUND_HINTS = [
 const DEFAULT_NOT_FOUND_HINT =
   " (not found. The user, tweet, or list may have been deleted or the id is wrong)";
 
+// AGENT-ACTIONABLE PAYWALL. A missing key, a rejected key, an empty balance and
+// a missing X session are the moments a user decides whether to keep going, and
+// they happen inside an agent's turn. The payload names the exact page (or tool)
+// so the agent can say "top up here, then I will retry". It is appended to the
+// text (every client reads that) and returned as structuredContent. Which
+// failures ARE a paywall is decided from the API's own response BODY, not the
+// status alone (the API's bodies, read 2026-09-29 from scraper/src/server/auth.ts
+// and routes/actions.ts): 401 {"error":"unauthorized"}, 402
+// {"error":"insufficient_credits"}, 409 {"error":"session_required"|"session_dead"}.
+export const SIGNUP_URL = "https://www.twitterapis.com/signup?utm_source=mcp&utm_medium=tool_error";
+export const API_KEYS_URL = "https://www.twitterapis.com/dashboard?utm_source=mcp&utm_medium=tool_error";
+export const TOP_UP_URL = "https://www.twitterapis.com/dashboard/buy-credits?utm_source=mcp&utm_medium=tool_error";
+
+export function paywallFor(kind) {
+  if (kind === "no_key") {
+    return {
+      needs: "account",
+      message:
+        "Missing TWITTERAPIS_KEY: no API key is set. Sign up free at twitterapis.com (new accounts start " +
+        "with free credit, no card), copy the key from the dashboard, set TWITTERAPIS_KEY in the MCP " +
+        "client config, then retry this call.",
+      action_url: SIGNUP_URL,
+      api_keys_url: API_KEYS_URL,
+      retry: "same call, after the key is set",
+    };
+  }
+  if (kind === "bad_key") {
+    return {
+      needs: "valid_key",
+      message:
+        "The twitterapis.com credential was rejected (the API key is invalid, revoked or rotated, or the " +
+        "connected app was disconnected). Copy a current key from the dashboard and set TWITTERAPIS_KEY, " +
+        "or reconnect the app, then retry this call.",
+      action_url: API_KEYS_URL,
+      retry: "same call, after the key is replaced or the app reconnected",
+    };
+  }
+  if (kind === "credits") {
+    return {
+      needs: "credits",
+      message:
+        "The twitterapis.com account is out of credits. Top up (pay as you go, no subscription), then " +
+        "retry this call; nothing was charged for the failed request. twitter_account_me shows the balance.",
+      action_url: TOP_UP_URL,
+      retry: "same call, after topping up",
+    };
+  }
+  if (kind === "x_session") {
+    return {
+      needs: "x_session",
+      message:
+        "This action needs a working linked X account: writes and account-only reads act as the user's " +
+        "own X session, and none is linked or the linked one has expired. Link or re-link it with the " +
+        "twitter_user_login tool (or twitter_customer_session with auth_token and ct0), then retry this call.",
+      next_tool: "twitter_user_login",
+      retry: "same call, after an X session is linked",
+    };
+  }
+  return null;
+}
+
+export function classifyPaywall(status, bodyText) {
+  let body = null;
+  try {
+    body = JSON.parse(bodyText);
+  } catch {
+    body = null;
+  }
+  const err = body && typeof body.error === "string" ? body.error : "";
+  // A dead X session is a 401 {"error":"session_dead"} (routes/actions.ts,
+  // routes/customer.ts), NOT a bad API key: telling the user to rotate a working
+  // key when their X cookies expired is the wrong fix. A 401 whose message is
+  // about the internal headers is a server wiring fault, not the user's key.
+  if (status === 401 && err === "session_dead") return "x_session";
+  if (status === 401 && err === "unauthorized" && !/x-internal/i.test(String(body?.message || ""))) return "bad_key";
+  if (status === 402 && err === "insufficient_credits") return "credits";
+  if (status === 409 && err === "session_required") return "x_session";
+  return null;
+}
+
+function paywallResult(kind, detail = "") {
+  const p = paywallFor(kind);
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${p.message}${detail ? ` (${detail})` : ""}\n\n${JSON.stringify(p)}` }],
+    structuredContent: p,
+  };
+}
+
 export function hintFor(status, path) {
   if (status === 401) return " (invalid or missing API key, verify TWITTERAPIS_KEY at https://www.twitterapis.com/dashboard)";
   if (status === 402) return " (insufficient credits, top up at https://www.twitterapis.com/dashboard)";
@@ -76,6 +165,9 @@ export const INSTRUCTIONS =
  *                                         (TWITTERAPIS_FEEDBACK_DIR); a remote host gives each
  *                                         caller its own directory
  * @param {typeof fetch} [opts.fetchImpl]  injectable for tests
+ * @param {(ms:number)=>Promise<void>} [opts.sleepImpl] injectable for tests
+ * @param {number[]} [opts.retryDelaysMs] waits before each retry of a read that
+ *        hit a gateway failure (deploy restart); default [3000, 8000]
  * @param {Record<string,string>} [opts.authHeaders]
  *        headers that authenticate each call INSTEAD of the API key. For a host
  *        that has already authenticated the caller some other way (an OAuth
@@ -89,6 +181,8 @@ export function createServer({
   feedbackEnv = process.env,
   fetchImpl = fetch,
   authHeaders = null,
+  sleepImpl = (ms) => new Promise((r) => setTimeout(r, ms)),
+  retryDelaysMs = [3000, 8000],
 } = {}) {
   const BASE_URL = String(baseUrl).replace(/\/+$/, "");
   const REQUEST_TIMEOUT_MS = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
@@ -111,15 +205,7 @@ export function createServer({
   // before building the query string or body, so a pathParams arg never leaks
   // into either.
   async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
-    if (!apiKey && !authHeaders) {
-      return {
-        isError: true,
-        content: [{
-          type: "text",
-          text: "Missing TWITTERAPIS_KEY (invalid or missing API key, get one at https://www.twitterapis.com/signup and set it in your MCP client config).",
-        }],
-      };
-    }
+    if (!apiKey && !authHeaders) return paywallResult("no_key");
     // Fill {name} URL segments from args and strip those keys, so a pathParams arg
     // (e.g. a monitor/webhook id) never also leaks into the query string or JSON
     // body. A missing value fails loudly rather than shipping a request that still
@@ -174,6 +260,26 @@ export function createServer({
       }
     }
 
+    // A DEPLOY RESTART IS NOT AN ERROR THE USER SHOULD SEE. While the API
+    // restarts (about 30 to 60 seconds, measured 2026-09-29) the gateway answers
+    // an HTML 502/503 or refuses the connection. A READ is retried through
+    // that window; the API's own JSON errors, timeouts and writes never are, so
+    // a request the API may already have handled is never sent twice (a gateway
+    // 504 is not retried for that reason).
+    const canRetry = method === "GET";
+    // Only a REFUSED connection is retried: the request never reached the API,
+    // so it cannot have been handled or billed. A reset, a broken pipe or a
+    // socket dropped mid-answer can all happen after the API did the work, and
+    // "fetch failed" alone also covers DNS and TLS errors that retrying cannot fix.
+    const RETRYABLE_NET = new Set(["ECONNREFUSED"]);
+    const gatewayFailure = (status, text) =>
+      (status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text);
+    const transientNetwork = (err) =>
+      !gotResponse && err?.name !== "AbortError" && RETRYABLE_NET.has(err?.cause?.code ?? err?.code);
+    let attempt = 0;
+    let gotResponse = false;
+    for (;;) {
+    gotResponse = false;
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
     try {
@@ -183,7 +289,13 @@ export function createServer({
         body: reqBody,
         signal: ctrl.signal,
       });
+      gotResponse = true;
       const body = await res.text();
+      if (canRetry && attempt < retryDelaysMs.length && gatewayFailure(res.status, body)) {
+        clearTimeout(timer);
+        await sleepImpl(retryDelaysMs[attempt++]);
+        continue;
+      }
       if (!res.ok) {
         const hint = hintFor(res.status, resolvedPath);
         lastError = {
@@ -201,6 +313,8 @@ export function createServer({
           res.status === 401 || res.status === 402 || res.status === 404 || res.status === 409 || res.status === 429
             ? ""
             : " If this blocked the user's task and looks like a defect or a missing capability, draft a report with twitter_feedback_send (queued locally until the user reviews it).";
+        const pw = classifyPaywall(res.status, body);
+        if (pw) return paywallResult(pw, `HTTP ${res.status}: ${body.slice(0, 1200)}`);
         return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}${feedbackHint}` }] };
       }
       // A success clears the record so a later draft never inherits an old
@@ -209,12 +323,21 @@ export function createServer({
       lastError = null;
       return { content: [{ type: "text", text: body }] };
     } catch (err) {
-      const msg = err?.name === "AbortError" ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : err?.message || String(err);
+      if (canRetry && attempt < retryDelaysMs.length && transientNetwork(err)) {
+        clearTimeout(timer);
+        await sleepImpl(retryDelaysMs[attempt++]);
+        continue;
+      }
+      const code = err?.cause?.code ?? err?.code;
+      const msg = err?.name === "AbortError"
+        ? `timed out after ${REQUEST_TIMEOUT_MS}ms`
+        : `${err?.message || String(err)}${code ? ` (${code})` : ""}`;
       lastError = { path: resolvedPath, method, status: null, error: msg.slice(0, 200), ts: Date.now() };
       return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
     } finally {
       clearTimeout(timer);
     }
+    }
   }
 
   const server = new McpServer({ name: "twitterapis", version: VERSION }, { instructions: INSTRUCTIONS });

package/src/tools.js

@@ -605,7 +605,7 @@ export const TOOLS = [
     name: "twitter_tweet_quotes",
     path: "/twitter/tweet/quotes",
     description:
-      "List the tweets that QUOTE a specific tweet, cursor-paginated as full tweet objects, so you get the commentary people attached rather than just a number. Different from twitter_tweet_retweeters (a plain retweet carries no text) and from twitter_tweet_replies (a reply is not a quote). IMPORTANT, state this to the user whenever you report a number from it: this endpoint is SEARCH-BACKED, because X exposes no dedicated quote-tweets operation, so it runs the query quoted_tweet_id:<id> against X's search index. The returned 'count' is therefore how many quotes THIS SEARCH returned, never the tweet's true total; the authoritative total is 'quote_count' on the tweet object from twitter_tweet_detail, and the two WILL differ because of index lag and because deleted, protected, suspended and region-withheld quotes are absent from search. Every response carries 'source' (always \"search\"), 'search_query' (the exact query sent), and 'quote_matched' (how many returned tweets demonstrably quote the requested id). quote_matched equal to count means every row is genuine; quote_matched 0 on a NON-EMPTY page means X stopped honouring the operator and the rows are junk, so discard that page rather than reporting it.",
+      "List the tweets that QUOTE a specific tweet, cursor-paginated as full tweet objects, so you get the commentary people attached rather than just a number. Different from twitter_tweet_retweeters (a plain retweet carries no text) and from twitter_tweet_replies (a reply is not a quote). IMPORTANT, state this to the user whenever you report a number from it: this endpoint is SEARCH-BACKED, because X exposes no dedicated quote-tweets operation, so it runs the query quoted_tweet_id:<id> against X's search index. The returned 'count' is therefore how many quotes THIS SEARCH returned, never the tweet's true total; the authoritative total is 'quote_count' on the tweet object from twitter_tweet_detail, and the two WILL differ because of index lag and because deleted, protected, suspended and region-withheld quotes are absent from search. Every response carries 'source' (always \"search\"), 'search_query' (the exact query sent), and 'quote_matched' (how many returned tweets demonstrably quote the requested id). quote_matched equal to count means every row is genuine; quote_matched 0 on a NON-EMPTY page means X stopped honouring the operator and the rows are junk, so discard that page rather than reporting it. An empty first Top page is served from Latest instead of reading as zero quotes: the response then says product_used \"Latest\" and top_fallback true, and its next_cursor keeps paging that Latest list, so pass it back unchanged.",
     shape: {
       id: z.string().optional().describe(
         "Tweet/post numeric id (e.g. \"1789012345678901234\"). Provide exactly one of id or url.",