@twitterapis/mcp 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.16.1 (2026-09-29)
+
+### Changed
+
+- **A restart answered in JSON is ridden out too.** The gateway now answers a
+  restart with a JSON 503 (`"error": "gateway_restarting"`, `Retry-After`)
+  instead of its HTML page; a read retries on either. Any other JSON 503 from
+  the API, and that code on any other status, is still never retried.
+- **A cancelled call stops.** When the MCP client cancels a tool call, the
+  request in flight is aborted and the wait before a retry ends at once; the
+  result says "Request cancelled by the caller." instead of reporting a timeout.
+
+## 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.1",
   "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;
@@ -199,7 +204,7 @@ export function createServer({
   // substitute into the URL template) and callEndpoint splices them into path
   // 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 = []) {
+  async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = [], { signal: callerSignal } = {}) {
     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
@@ -255,8 +260,46 @@ 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"]);
+    // The gateway answers a restart two ways: nginx's stock HTML 502/503 page,
+    // or (since 2026-09-29) its own JSON 503 whose error is "gateway_restarting".
+    // Nginx sends that JSON only when it could not reach the API at all, so the
+    // API's own JSON errors (which never use that code) are still never retried.
+    const gatewayFailure = (status, text) => {
+      if ((status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text)) return true;
+      if (status !== 503) return false;
+      try { return JSON.parse(text)?.error === "gateway_restarting"; } catch { return false; }
+    };
+    // The MCP caller's cancel (notifications/cancelled) aborts the request in
+    // flight and any wait between retries, so a cancelled call stops at once.
+    const cancelled = () => Boolean(callerSignal?.aborted);
+    const pause = (ms) => cancelled() ? Promise.resolve() : new Promise((resolve) => {
+      const done = () => { callerSignal?.removeEventListener?.("abort", done); resolve(); };
+      Promise.resolve(sleepImpl(ms)).then(done, done);
+      callerSignal?.addEventListener?.("abort", done, { once: true });
+    });
+    const transientNetwork = (err) =>
+      !gotResponse && err?.name !== "AbortError" && RETRYABLE_NET.has(err?.cause?.code ?? err?.code);
+    let attempt = 0;
+    let gotResponse = false;
+    for (;;) {
+    gotResponse = false;
+    if (cancelled()) return { isError: true, content: [{ type: "text", text: "Request cancelled by the caller." }] };
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    const onCancel = () => ctrl.abort();
+    callerSignal?.addEventListener?.("abort", onCancel, { once: true });
     try {
       const res = await fetchImpl(url, {
         method,
@@ -264,7 +307,14 @@ export function createServer({
         body: reqBody,
         signal: ctrl.signal,
       });
+      gotResponse = true;
       const body = await res.text();
+      if (canRetry && !cancelled() && attempt < retryDelaysMs.length && gatewayFailure(res.status, body)) {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener?.("abort", onCancel);
+        await pause(retryDelaysMs[attempt++]);
+        continue;
+      }
       if (!res.ok) {
         const hint = hintFor(res.status, resolvedPath);
         lastError = {
@@ -292,11 +342,23 @@ 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 && !cancelled() && attempt < retryDelaysMs.length && transientNetwork(err)) {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener?.("abort", onCancel);
+        await pause(retryDelaysMs[attempt++]);
+        continue;
+      }
+      if (cancelled()) return { isError: true, content: [{ type: "text", text: "Request cancelled by the caller." }] };
+      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);
+      callerSignal?.removeEventListener?.("abort", onCancel);
+    }
     }
   }
 
@@ -330,8 +392,8 @@ export function createServer({
       handler = LOCAL_HANDLERS[tool.local];
       if (!handler) throw new Error(`[twitterapis-mcp] tool ${tool.name} declares local handler "${tool.local}" but src/server.js has none`);
     } else {
-      handler = async (args) => {
-        const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []);
+      handler = async (args, extra) => {
+        const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || [], { signal: extra?.signal });
         if (result?.isError && lastError) {
           let resolved = null;
           try { resolved = resolvePathParams(tool.path, tool.pathParams || [], args).path; } catch { resolved = null; }

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.",