@twitterapis/mcp 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.15.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 && node test/paywall.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

@@ -165,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
@@ -178,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;
@@ -255,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 {
@@ -264,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 = {
@@ -292,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.",