@twitterapis/mcp 0.9.3 → 0.9.6

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.9.6 (2026-09-04)
+
+### Added
+
+- **`twitter_feedback_send` and `twitter_feedback_get`, report a bug or a gap to the twitterapis.com team from inside the session you are already in.** Modelled on Claude Code's own feedback tool: the model drafts a report at a high-signal moment (a call failed in a way that is not your key, credits, session or a rate limit and you had to work around it; you asked for something no tool covers; a documented field came back empty or wrong; you were plainly frustrated with a result) into a local queue at `~/.twitterapis/feedback-queue.json`, and nothing is sent until you review the queue and name the drafts to send. Each draft carries the last failing call's endpoint, status and request id, your MCP client's name and this package's version, filled in automatically, so a report is actionable without a follow-up. `twitter_feedback_send` takes `action` (`draft`, `list`, `send`, `discard`); `twitter_feedback_get` reads a sent report's status and the team's response. Both are free. The trigger list also ships as the server's MCP `instructions`, so a client that honours them nudges its model at the right moments. Every non-credential error body now ends with a one-line pointer to the tool. This takes the catalog to 98 tools, 62 reads and 36 writes, still exact parity with the API's own endpoint count.
+- **Catalog support for local handlers.** A tool may declare `local: "<handler>"` in `scripts/tools.overrides.mjs`, and args flagged `local: true` are consumed in this package instead of being sent to the API. The generator refuses a `local: true` arg on a tool with no handler, and refuses a `local` handler name `src/index.js` does not implement at boot, so neither flag can turn into a silent passthrough. A new `strings` arg type renders `z.array(z.string())`.
+
+## 0.9.5 (2026-08-31)
+
+### Added
+
+- **`twitter_monitor_webhook_redrive`, replay the deliveries you missed while your endpoint was down.** A delivery is dead-lettered after it fails all 8 attempts across 21 minutes, so an outage longer than that window loses those events outright. This re-queues them with a full retry budget, oldest first, and is free per call. Bounded by default so a recovered endpoint is not flooded: `max_age_hours` defaults to 24 (1 to 168) and `limit` to 100 (1 to 1000). Returns `requeued` and `skipped_permanent`; a delivery that died for a permanent reason (a 410 Gone, a deleted webhook, or a URL egress refused) is not replayed, because it would fail the same way and spend the budget again. Replayed events carry the same signature and payload as the original, so make your handler idempotent on the event id if a duplicate would matter to you. This takes the catalog to 96 tools, 61 reads and 35 writes, which is exact parity with the API's own endpoint count.
+- **`include_replies` on `twitter_monitor_create` and `twitter_monitor_update`.** The parameter was added upstream and neither tool exposed it, so a caller could not turn replies off through the MCP at all. `true` delivers the account's replies as well as its own posts, which is the default and what every monitor has always done; `false` holds replies back. It must be a real boolean: the string `"false"` and the number `0` are rejected with a 400 rather than coerced, because coercing them would quietly give you the opposite of what you typed, and the wrong answer here is invisible since it looks exactly like the account not having posted. The generator is fail-closed on an unexposed spec param and refused to build until both were declared, which is how this surfaced.
+
+### Fixed
+
+- **The redrive tool would have 400'd on every call without `jsonBody: true`.** Its handler reads `max_age_hours` and `limit` from the body only, so the args would have gone out as a query string. Caught by `body-mode-parity`, which reads the backend's own generated route manifest rather than trusting this repo's view of it. That manifest was itself stale on the backend's main branch (the route landed without regenerating it), so the failure surfaced here first and was fixed upstream in twitterapis-backend#408 before this release.
+
+## 0.9.4 (2026-08-19)
+
+### Fixed
+
+- **A malformed `TWITTERAPIS_TIMEOUT_MS` silently timed out every single tool call.** `Number(process.env.TWITTERAPIS_TIMEOUT_MS || 30000)` had no validation: a non-numeric value (`"30000ms"`, `"60,000"`, a stray comma or unit) parses to `NaN`, and Node's `setTimeout` clamps a `NaN` delay to about 1ms, so the abort controller fired before any real request could complete. Every tool call failed with `Request failed: timed out after NaNms`, which reads as a live API outage rather than the config typo it actually is. An explicit `0` or negative value had the same effect with no typo required at all. The value is now validated as a finite, positive number before use, falls back to the documented 30000ms default otherwise, and logs a clear warning to stderr naming the bad value instead of silently breaking every call.
+- **8 tool args declared `optional: true` in `scripts/tools.overrides.mjs`, a key the generator never reads** (`with_listeners` / `with_replays` on `twitter_spaces_info`, `message` / `messages` / `conversation_id` / `mode` / `image_count` on `twitter_grok_chat`, `media_category` on `twitter_article_update_cover_media`). The render logic only ever checks `a.required`, so `optional: true` was silently a no-op; each of these 8 args happened to render as optional anyway only because the vendored spec's own `required` flag for that param already defaulted to false. A future spec refresh flipping one of those defaults would have silently made the arg required with no warning from any gate. Renamed to `required: false`, the property the generator actually reads. `src/tools.js` is byte-identical before and after (`catalog-identity` confirms), so this closes a live gap without changing today's behavior.
+- **The generator now fails the build on any unrecognized key in a `tools.overrides.mjs` arg entry** (`scripts/gen-tools.mjs`), so the class of bug above can't recur silently. Red-tested: reintroducing `optional: true` on a synthetic arg makes `npm run build:check` fail with `sets unrecognized key "optional" ... did you mean "required: false"?`.
+
 ## 0.9.3 (2026-08-18)
 
 PR #36 (3 new tools + openapi-parity fix) merged after 0.9.2 had already been

package/README.md

@@ -91,9 +91,9 @@ Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.
 
 ## Tools
 
-94 tools: 60 reads and 34 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. Two of the reads are free account/billing lookups (`twitter_account_me`, `twitter_account_payments`); the 14 monitoring tools are also free (account administration, not metered reads).
+98 tools: 62 reads and 36 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. Three of the reads are free account lookups (`twitter_account_me`, `twitter_account_payments`, `twitter_feedback_get`); the 14 monitoring tools and `twitter_feedback_send` are also free (account administration, not metered reads).
 
-Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** tools (see below) are the one exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
+Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** and **feedback** tools (see below) are the exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.
 
 ### Reads
 
@@ -204,6 +204,16 @@ Watch an X account for new posts and get them pushed to your own HTTPS endpoint,
 | `twitter_monitor_webhook_list` | List every webhook registered on your account |
 | `twitter_monitor_webhook_delete` | Soft-delete a webhook by id (irreversible from the caller's side) |
 | `twitter_monitor_webhook_test` | Send one signed test event to a webhook right now, synchronously |
+| `twitter_monitor_webhook_redrive` | Replay deliveries that dead-lettered while your endpoint was down, oldest first |
+
+### Feedback _(report a bug or a gap to the twitterapis.com team without leaving your session; free)_
+
+Modelled on Claude Code's own feedback tool. When a call fails in a way that is not your key, credits, session or a rate limit, when you ask for something no tool covers, or when a result is plainly wrong, the model can **draft** a report into a local queue (`~/.twitterapis/feedback-queue.json`, at most 10 drafts, override the directory with `TWITTERAPIS_FEEDBACK_DIR`). Nothing is sent until you ask to review the queue and name the drafts to send. Each report carries the last failing call's endpoint, status and request id, your client name and this package's version, so the team can act on it without a follow-up. Use `twitter_feedback_get` with the returned server id to see whether it was triaged, shipped or declined.
+
+| Tool | What it does |
+|---|---|
+| `twitter_feedback_send` | `action: "draft"` (default) queues a report locally and sends nothing; `"list"` shows the queue; `"send"` posts only the drafts you name to `POST /feedback`; `"discard"` drops them |
+| `twitter_feedback_get` | Read a sent report's status (`new`, `triaged`, `shipped`, `declined`) and the team's response |
 
 ### Session setup
 
@@ -212,6 +222,7 @@ Link an X account to your key once, so the account-only reads and write actions
 | Tool | What it does |
 |---|---|
 | `twitter_customer_session` | Register your x.com session cookies (`auth_token` + `ct0`) against your key |
+| `twitter_customer_session_status` | Read back the registered session without changing it: resolved account, live/dead status, timestamps, and which egress tier a write would use. Never returns the cookies. Free |
 | `twitter_customer_session_delete` | Revoke that stored session, deleting your `auth_token` + `ct0` from the service. Idempotent and free |
 | `twitter_user_login` | Log in with `username` + `password` (+ `totp_secret` for 2FA); stores the session against your key. Returns a confirmation, never the cookies |
 
@@ -295,7 +306,7 @@ Calls are billed to your twitterapis.com account. Almost every endpoint is $0.00
 
 **Do I need an X (Twitter) developer account?** No. Get an API key at [twitterapis.com/signup](https://www.twitterapis.com/signup); there is no application or approval step.
 
-**Is it read-only?** No. 60 read tools work with just your API key; 34 write actions (post, like, retweet, follow, DM, media upload, List create/add member/remove member, article create/edit/publish/delete, monitor/webhook create/update/delete) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD, which is account administration and needs only your API key.
+**Is it read-only?** No. 62 read tools work with just your API key; 36 write actions (post, like, retweet, follow, DM, media upload, List create/add member/remove member, article create/edit/publish/delete, monitor/webhook create/update/delete, feedback send) act as a linked X account or per-call inline credentials, except monitor/webhook CRUD and feedback, which are account administration and need only your API key.
 
 **Which clients are supported?** Claude Desktop, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.9.3",
+  "version": "0.9.6",
   "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",
@@ -16,7 +16,8 @@
     "src",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "icon.png"
   ],
   "engines": {
     "node": ">=18"
@@ -27,7 +28,7 @@
     "build": "node scripts/gen-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 test/gen-tools-endpoints.mjs && node test/catalog-identity.mjs && node test/tools.test.mjs && node test/smoke.mjs && node test/openapi-parity.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
+    "test": "node scripts/gen-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/smoke.mjs && node test/openapi-parity.mjs && node test/body-mode-parity.mjs && node test/readme-parity.mjs && node test/firewall.mjs && node test/registry-manifests.mjs",
     "prepublishOnly": "npm test && node test/publish-provenance.mjs",
     "check:openapi-parity": "node test/openapi-parity.mjs",
     "check:body-mode-parity": "node test/body-mode-parity.mjs",

package/src/feedback.js

@@ -0,0 +1,237 @@
+// src/feedback.js, the local half of twitter_feedback_send.
+//
+// Claude Code's own feedback tool works like this: the model drafts a report at
+// a high-signal moment, the harness writes it to a LOCAL queue, and nothing
+// leaves the machine until the user reviews the queue and approves. That
+// consent step is what makes it safe to let a model draft freely. This module
+// gives twitterapis.com customers the same loop inside whatever MCP client
+// they already use: action "draft" appends to ~/.twitterapis/feedback-queue.json
+// and sends nothing; "list" shows the drafts; "send" posts ONLY the ids the user
+// named to POST /feedback (free, not metered); "discard" drops them.
+//
+// The tool DESCRIPTION in scripts/tools.overrides.mjs is the product: it names
+// the trigger moments and the four-bullet format. This file enforces the same
+// rules mechanically so a draft that reaches the server is well-formed, and it
+// auto-attaches the evidence the server already holds (the last failing call,
+// the client name from the MCP handshake, this package's version), so the model
+// never has to type identifiers it might get wrong.
+//
+// STATE ON DISK, ON PURPOSE. The queue outlives the session: a user can review
+// tomorrow what an agent drafted today. Writes are atomic (temp file + rename)
+// because two MCP clients can share one home directory.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const QUEUE_CAP = 10;
+export const TYPES = ["bug", "idea", "missing_capability"];
+export const ACTIONS = ["draft", "list", "send", "discard"];
+const MAX = { title: 120, details: 8000, area: 80 };
+const EVIDENCE_MAX_BYTES = 4096;
+
+/** Where drafts live. TWITTERAPIS_FEEDBACK_DIR overrides the default ~/.twitterapis. */
+export function queuePath(env = process.env) {
+  const dir = env.TWITTERAPIS_FEEDBACK_DIR || join(homedir(), ".twitterapis");
+  return join(dir, "feedback-queue.json");
+}
+
+/** A draft this module can act on. Anything else in the file (a hand edit, an
+ * older shape, a null) is skipped rather than allowed to throw on every call. */
+function isDraft(d) {
+  return d && typeof d === "object" && !Array.isArray(d)
+    && typeof d.id === "string" && typeof d.type === "string"
+    && typeof d.title === "string" && typeof d.details === "string";
+}
+
+export function readQueue(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(parsed?.drafts) ? parsed.drafts.filter(isDraft) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(path, drafts) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, drafts }, null, 2) + "\n");
+  renameSync(tmp, path);
+}
+
+// Two MCP servers can share one home directory, and temp+rename only keeps the
+// file well-formed: without a lock a read-modify-write from each loses one
+// side's drafts (measured 2026-09-04: two writers, five of ten drafts gone).
+// mkdir is atomic on every platform node runs on, so a lock DIRECTORY is the
+// mutex; a holder that died leaves it behind, so one older than STALE_MS is
+// reclaimed.
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 3_000;
+async function withLock(path, fn) {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) { rmSync(lock, { recursive: true, force: true }); continue; }
+      } catch { /* vanished between checks; retry */ }
+      if (Date.now() > deadline) throw new Error(`feedback queue is locked by another process (${lock}); retry in a moment`);
+      await new Promise((r) => setTimeout(r, 25 + Math.floor(Math.random() * 50)));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/** Stable per-issue id: the same type + title redrafted replaces itself. */
+export function draftId(type, title) {
+  return createHash("sha256").update(`${type}\n${title.trim().toLowerCase()}`).digest("hex").slice(0, 8);
+}
+
+const CLIENT_MAX = 120; // billing rejects longer; the model never types this field
+function clientString(clientInfo, version) {
+  const name = clientInfo?.name ? `${clientInfo.name}${clientInfo.version ? `/${clientInfo.version}` : ""}` : "unknown-client";
+  return `${name} via @twitterapis/mcp@${version}`.slice(0, CLIENT_MAX);
+}
+
+// The last failing call is worth attaching only while it is plausibly the call
+// the draft is about: recent, and not the feedback endpoint's own failure.
+const LAST_ERROR_TTL_MS = 10 * 60 * 1000;
+function usableLastError(last) {
+  if (!last || typeof last !== "object") return null;
+  if (typeof last.ts === "number" && Date.now() - last.ts > LAST_ERROR_TTL_MS) return null;
+  if (last.path === "/feedback" || (typeof last.path === "string" && last.path.startsWith("/feedback/"))) return null;
+  return last;
+}
+
+const text = (t, isError = false) => ({ isError, content: [{ type: "text", text: t }] });
+
+function summarize(d) {
+  const first = d.details.split("\n")[0].slice(0, 140);
+  return `${d.id}  [${d.type}] ${d.title}${d.area ? ` (${d.area})` : ""}  drafted ${d.ts}\n    ${first}`;
+}
+
+/**
+ * @param {object} deps
+ * @param {(path:string, args:object, method:string, jsonBody:boolean)=>Promise<object>} deps.callEndpoint
+ * @param {string} deps.version            this package's version
+ * @param {() => ({name?:string, version?:string}|undefined)} [deps.getClientInfo]
+ * @param {() => (object|null)} [deps.getLastError]   the last failing tool call, if any
+ * @param {object} [deps.env]
+ */
+export function createFeedbackHandler({ callEndpoint, version, getClientInfo, getLastError, env = process.env }) {
+  return async function feedbackTool(args = {}) {
+    const action = args.action || "draft";
+    if (!ACTIONS.includes(action)) return text(`action must be one of ${ACTIONS.join(", ")}.`, true);
+    const path = queuePath(env);
+    try {
+      return await withLock(path, () => run(action, args, path));
+    } catch (err) {
+      return text(err?.message || String(err), true);
+    }
+  };
+
+  async function run(action, args, path) {
+    if (action === "draft") {
+      if (!TYPES.includes(args.type)) return text(`type is required for a draft and must be one of ${TYPES.join(", ")}.`, true);
+      const title = String(args.title ?? "").trim();
+      if (!title || title.length > MAX.title) return text(`title is required for a draft, at most ${MAX.title} characters.`, true);
+      const details = String(args.details ?? "").trim();
+      if (!details || details.length > MAX.details) return text(`details is required for a draft, at most ${MAX.details} characters. Use the four labelled bullets: What happened, What the user said, Repro, Evidence.`, true);
+      const area = args.area ? String(args.area).trim().slice(0, MAX.area) : undefined;
+
+      const client = clientString(getClientInfo?.(), version);
+      const evidence = { ...(args.evidence && typeof args.evidence === "object" && !Array.isArray(args.evidence) ? args.evidence : {}) };
+      const last = usableLastError(getLastError?.());
+      // Fill only what the model did not supply: its own evidence wins.
+      if (last) {
+        if (evidence.tool === undefined && last.tool) evidence.tool = last.tool;
+        if (evidence.endpoint === undefined && last.path) evidence.endpoint = last.path;
+        if (evidence.status === undefined && last.status) evidence.status = last.status;
+        if (evidence.request_id === undefined && last.requestId) evidence.request_id = last.requestId;
+      }
+      evidence.mcp_version = version;
+      evidence.client = client;
+      if (Buffer.byteLength(JSON.stringify(evidence), "utf8") > EVIDENCE_MAX_BYTES) {
+        return text(`evidence must serialize to ${EVIDENCE_MAX_BYTES} bytes or fewer. Send identifiers (tool, endpoint, status, request id), never payloads.`, true);
+      }
+
+      const drafts = readQueue(path);
+      const draft = { id: draftId(args.type, title), ts: new Date().toISOString(), type: args.type, title, details, area, evidence, client };
+      const idx = drafts.findIndex((d) => d.id === draft.id);
+      if (idx >= 0) {
+        drafts[idx] = draft;
+      } else {
+        if (drafts.length >= QUEUE_CAP) {
+          return text(`The local feedback queue already holds ${QUEUE_CAP} drafts. Ask the user to review them (action "list", then "send" or "discard") before drafting more.`, true);
+        }
+        drafts.push(draft);
+      }
+      writeQueue(path, drafts);
+      return text(
+        `Queued locally as draft ${draft.id}${idx >= 0 ? " (replaced an earlier draft with the same title)" : ""}. ${drafts.length} draft(s) pending in ${path}. ` +
+          `Nothing was sent and nothing needs to be said to the user right now. When the user asks to review or send feedback, call this tool with action "list", ` +
+          `then action "send" with only the ids the user names, or "discard".`,
+      );
+    }
+
+    const drafts = readQueue(path);
+
+    if (action === "list") {
+      if (drafts.length === 0) return text(`No feedback drafts pending (${path}).`);
+      return text(
+        `${drafts.length} feedback draft(s) pending in ${path}. Show these to the user and send only the ids they name:\n\n` +
+          drafts.map(summarize).join("\n"),
+      );
+    }
+
+    const ids = [...new Set((Array.isArray(args.ids) ? args.ids : []).map(String))];
+    if (ids.length === 0) return text(`action "${action}" needs ids: the draft ids the user named (from action "list").`, true);
+    const unknown = ids.filter((id) => !drafts.some((d) => d.id === id));
+    if (unknown.length) return text(`Unknown draft id(s): ${unknown.join(", ")}. Run action "list" to see the current ids.`, true);
+
+    if (action === "discard") {
+      const kept = drafts.filter((d) => !ids.includes(d.id));
+      writeQueue(path, kept);
+      return text(`Discarded ${ids.length} draft(s): ${ids.join(", ")}. ${kept.length} still pending.`);
+    }
+
+    // send
+    const sent = [];
+    const failed = [];
+    let remaining = drafts;
+    for (const id of ids) {
+      const d = drafts.find((x) => x.id === id);
+      const body = { type: d.type, title: d.title, details: d.details, evidence: d.evidence, client: d.client };
+      if (d.area) body.area = d.area;
+      const res = await callEndpoint("/feedback", body, "POST", true);
+      const out = res?.content?.[0]?.text ?? "";
+      if (res?.isError) {
+        failed.push(`${id}: ${out.slice(0, 300)}`);
+        continue;
+      }
+      let serverId = null;
+      try { serverId = JSON.parse(out).id ?? null; } catch { /* body was not JSON; keep null */ }
+      sent.push(`${id} -> ${serverId ?? "sent"}`);
+      remaining = remaining.filter((x) => x.id !== id);
+      // Persist after EACH success, so a process that dies mid-loop cannot
+      // re-send a report the server already holds.
+      writeQueue(path, remaining);
+    }
+    const lines = [];
+    if (sent.length) lines.push(`Sent ${sent.length} report(s) to twitterapis.com (free, not metered):\n  ${sent.join("\n  ")}\nCheck one later with twitter_feedback_get using the server id.`);
+    if (failed.length) lines.push(`${failed.length} draft(s) stayed in the queue because the send failed:\n  ${failed.join("\n  ")}`);
+    lines.push(`${remaining.length} draft(s) still pending.`);
+    return text(lines.join("\n\n"), sent.length === 0);
+  }
+}

package/src/index.js

@@ -25,12 +25,36 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // outbound user-agent both still advertised 0.3.0.
 const VERSION = createRequire(import.meta.url)("../package.json").version;
 import { TOOLS, buildQuery, resolvePathParams, MissingPathParamError } from "./tools.js";
+import { createFeedbackHandler } from "./feedback.js";
 
 const API_KEY = process.env.TWITTERAPIS_KEY;
 const BASE_URL = (
   process.env.TWITTERAPIS_BASE_URL || "https://api.twitterapis.com"
 ).replace(/\/+$/, "");
-const REQUEST_TIMEOUT_MS = Number(process.env.TWITTERAPIS_TIMEOUT_MS || 30000);
+
+const DEFAULT_TIMEOUT_MS = 30000;
+// A malformed TWITTERAPIS_TIMEOUT_MS (non-numeric, or <= 0) used to reach
+// setTimeout() unvalidated. Number("30000ms") and Number("60,000") are both
+// NaN, and Node clamps a NaN or sub-1 delay to ~1ms (verified directly:
+// `setTimeout(fn, NaN)` fires in under 1ms), so every tool call aborted
+// almost immediately with "Request failed: timed out after NaNms" -- which
+// reads as a live outage, not the config typo it actually is. An explicit 0
+// or negative value has the same effect with no typo needed at all. Fall
+// back to the documented default on anything that is not a finite, positive
+// number, and say so loudly rather than silently eating every call.
+let REQUEST_TIMEOUT_MS = DEFAULT_TIMEOUT_MS;
+const rawTimeoutEnv = process.env.TWITTERAPIS_TIMEOUT_MS;
+if (rawTimeoutEnv) {
+  const parsed = Number(rawTimeoutEnv);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    REQUEST_TIMEOUT_MS = parsed;
+  } else {
+    console.error(
+      `[twitterapis-mcp] TWITTERAPIS_TIMEOUT_MS="${rawTimeoutEnv}" is not a positive number; ` +
+        `falling back to the default ${DEFAULT_TIMEOUT_MS}ms instead of timing out every call immediately.`,
+    );
+  }
+}
 
 // Lazy validation, not exit-on-boot: an MCP registry scanner (Smithery, Glama,
 // the official registry, Claude Connectors) connects the stdio transport with
@@ -58,6 +82,11 @@ if (!API_KEY) {
 // 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.
+// The last tool call that failed, so a feedback draft can carry the endpoint,
+// status and request id without the model retyping them. Set in callEndpoint's
+// error branch; the tool name is added by the registration wrapper below.
+let lastError = null;
+
 async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
   if (!API_KEY) {
     return {
@@ -145,11 +174,31 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false, pathPa
                   : 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)}` }] };
+      lastError = {
+        path: resolvedPath,
+        method,
+        status: res.status,
+        requestId: res.headers.get("x-request-id") || undefined,
+        ts: Date.now(),
+      };
+      // Credential, credit, session, rate-limit and not-found failures are the
+      // caller's situation (a 404 is almost always a wrong id), not a product
+      // defect; everything else may be one, and the model reads error bodies
+      // closely, so the pointer lives here.
+      const feedbackHint =
+        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).";
+      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
+    // failure's endpoint or request id (review 2026-09-04: a delete's draft
+    // carried the previous update's 404).
+    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);
+    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);
@@ -157,7 +206,27 @@ async function callEndpoint(path, args, method = "GET", jsonBody = false, pathPa
 }
 
 // ── MCP server ───────────────────────────────────────────────────────────────
-const server = new McpServer({ name: "twitterapis", version: VERSION });
+// Standing instructions the client hands its model alongside the tool list.
+// This is the trigger list for feedback, in the place a model actually reads.
+const INSTRUCTIONS =
+  "twitterapis.com MCP server. Read tools cost credits per call (most $0.0008); account, monitoring and feedback tools are free. " +
+  "If a twitterapis tool call fails with an error other than 401/402/409/429 and the user has to work around it, if the user asks for something no twitterapis tool covers, " +
+  "if a documented field comes back empty or wrong, or if the user is clearly frustrated with a result, draft a report with twitter_feedback_send (action \"draft\"). " +
+  "Drafting is local and silent; never send a draft unless the user names it after reviewing action \"list\".";
+
+const server = new McpServer({ name: "twitterapis", version: VERSION }, { instructions: INSTRUCTIONS });
+
+// Handlers for tools that carry local: "<name>" in the catalog. A name the
+// catalog uses and this map lacks is a boot-time failure, never a silent
+// passthrough to the API with the local args attached.
+const LOCAL_HANDLERS = {
+  feedback: createFeedbackHandler({
+    callEndpoint,
+    version: VERSION,
+    getClientInfo: () => server.server.getClientVersion(),
+    getLastError: () => lastError,
+  }),
+};
 
 for (const tool of TOOLS) {
   const method = tool.method || "GET";
@@ -169,10 +238,27 @@ for (const tool of TOOLS) {
     destructiveHint: Boolean(tool.destructive),
     openWorldHint: true,
   };
+  let handler;
+  if (tool.local) {
+    handler = LOCAL_HANDLERS[tool.local];
+    if (!handler) throw new Error(`[twitterapis-mcp] tool ${tool.name} declares local handler "${tool.local}" but src/index.js has none`);
+  } else {
+    handler = async (args) => {
+      const result = await callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []);
+      if (result?.isError && lastError) {
+        let resolved = null;
+        try { resolved = resolvePathParams(tool.path, tool.pathParams || [], args).path; } catch { resolved = null; }
+        // Name the tool only when BOTH method and path match the recorded
+        // failure; two tools share /monitor/{id} (POST update, DELETE remove).
+        if (resolved === lastError.path && method === lastError.method) lastError.tool = tool.name;
+      }
+      return result;
+    };
+  }
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method, Boolean(tool.jsonBody), tool.pathParams || []),
+    handler,
   );
 }
 

package/src/tools.js

@@ -8,12 +8,12 @@
 // file in memory and fails if it does not match what is committed, so a hand edit
 // here is caught rather than shipped.
 //
-// Catalog: 94 tools (60 reads, 34 writes).
+// Catalog: 98 tools (62 reads, 36 writes).
 //
 // 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), except the per-call
-// inline credentials, which travel as x-* request headers, the 9
+// inline credentials, which travel as x-* request headers, the 11
 // jsonBody tools, whose fields travel in a JSON request body, and any arg listed
 // in pathParams, which is substituted into the URL path (e.g. {id}) instead. A
 // tool with `method: "POST"` or `method: "DELETE"` is a write that acts on
@@ -22,6 +22,10 @@
 //
 // write:true       -> action mutates account/Twitter state (readOnlyHint:false)
 // destructive:true -> action removes/reverses state (delete, un-follow/like/RT/bookmark)
+// local:"<name>"   -> src/index.js dispatches the call to a handler in this
+//                     package instead of a plain passthrough (feedback's draft
+//                     queue); args flagged local:true in the overrides are
+//                     consumed there and never reach the API
 // pathParams        -> arg names substituted into the URL template, not sent as
 //                      query-string or body fields (e.g. ["id"] for /monitor/{id})
 import { z } from "zod";
@@ -40,7 +44,7 @@ export const TOOLS = [
         "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.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -57,7 +61,7 @@ export const TOOLS = [
         "Name, keyword, or topic to search accounts for. Examples: 'OpenAI', 'AI researcher', 'tech founder'.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -127,7 +131,7 @@ export const TOOLS = [
         "Optional team/sub-group name to filter affiliates by, when the org exposes named teams.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -161,7 +165,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -181,7 +185,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -215,7 +219,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -232,7 +236,7 @@ export const TOOLS = [
         "Twitter/X handle WITHOUT the leading @ of the user to find mentions for (e.g. 'openai' to find tweets mentioning @openai).",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -249,7 +253,7 @@ export const TOOLS = [
         "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.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -269,7 +273,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -289,7 +293,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -309,7 +313,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -329,7 +333,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -349,7 +353,7 @@ export const TOOLS = [
         "Numeric Twitter/X user id (e.g. \"44196397\"). Provide exactly one of username or user_id.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -366,7 +370,7 @@ export const TOOLS = [
         "Numeric user id of the target account to compute shared followers against.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -443,7 +447,7 @@ export const TOOLS = [
         "Full tweet URL, e.g. \"https://x.com/elonmusk/status/1789012345678901234\". Provide exactly one of id or url.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -486,7 +490,7 @@ export const TOOLS = [
         "Numeric Twitter/X List id. Found in the list URL: x.com/i/lists/<list_id>.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -775,6 +779,52 @@ export const TOOLS = [
       "Get YOUR twitterapis.com payment history: the list of top-ups and charges on your account. Authenticated by your API key. This is an account read, not Twitter data, and is free (it does not spend credits).",
     shape: {},
   },
+  {
+    name: "twitter_feedback_send",
+    path: "/feedback",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    local: "feedback",
+    localArgs: ["action","ids"],
+    description:
+      "Report a product problem or gap in twitterapis.com to its team from inside this session, the way Claude Code's own feedback tool works: a report is DRAFTED to a local queue first (action \"draft\", the default) and SENT only after the user reviews it. Drafting sends nothing, needs no confirmation, and should not be announced mid-task. WHEN TO DRAFT, only at high-signal moments: a twitterapis tool call failed with an error that was not a missing key (401), credits (402), no linked session (409) or a rate limit (429), and the user had to work around it; the user asked for something no twitterapis tool covers; a documented field came back empty or wrong; the user was clearly frustrated with a result. One draft per distinct issue, never twice for the same one. FORMAT for details, four labelled bullets in this order: 'What happened:' observed vs expected, exact error text if short. 'What the user said:' quoted verbatim, or 'user did not comment'. 'Repro:' the minimal call that reproduces it. 'Evidence:' tool name, endpoint, HTTP status, request id (the last failing call is attached automatically where you leave a gap). Facts only: no guessing, no API keys or secrets, no personal names. REVIEW: when the user asks to see or send feedback, call action \"list\", then action \"send\" with ONLY the draft ids the user named in their own message, or action \"discard\". Sending posts each draft to POST /feedback (free) and returns a server id that twitter_feedback_get can check later.",
+    shape: {
+      action: z.enum(["draft","list","send","discard"]).optional().describe(
+        "What to do. \"draft\" (default) queues a new report locally and sends nothing. \"list\" shows the pending drafts with their ids. \"send\" posts the drafts named in ids to twitterapis.com; use it only for ids the user named. \"discard\" drops the drafts named in ids.",
+      ),
+      type: z.enum(["bug","idea","missing_capability"]).optional().describe(
+        "Required for a draft. \"bug\": a tool or endpoint misbehaved. \"idea\": a change that would have made the task easier. \"missing_capability\": the user needed something no tool provides.",
+      ),
+      title: z.string().optional().describe(
+        "Required for a draft. One specific line, at most 120 characters, naming the tool or endpoint and the defect, e.g. \"twitter_tweet_thread returns 502 when the root tweet is deleted\".",
+      ),
+      details: z.string().optional().describe(
+        "Required for a draft. At most 8000 characters, four labelled bullets in order: What happened, What the user said (verbatim), Repro, Evidence.",
+      ),
+      area: z.string().optional().describe(
+        "Optional. The endpoint or feature the report is about, e.g. \"tweet/thread\" or \"monitoring\". At most 80 characters.",
+      ),
+      evidence: z.record(z.string(), z.unknown()).optional().describe(
+        "Optional identifiers only, never payloads: {tool, endpoint, status, request_id}. Whatever you leave out is filled from the last failing call in this session; mcp_version and client are always attached.",
+      ),
+      ids: z.array(z.string()).optional().describe(
+        "For action \"send\" or \"discard\": the draft ids to act on, exactly as shown by action \"list\" and named by the user.",
+      ),
+    },
+  },
+  {
+    name: "twitter_feedback_get",
+    path: "/feedback/{id}",
+    pathParams: ["id"],
+    description:
+      "Check the status of a feedback report this account sent earlier (the server id returned by twitter_feedback_send action \"send\"): status new, triaged, shipped or declined, the team's response text if any, and updated_at, which moves only when the team acts on it. Free per call. 404 if the id is not on this account.",
+    shape: {
+      id: z.string().describe(
+        "The server id of a sent report, as returned by twitter_feedback_send action \"send\" (a UUID). Not a local draft id.",
+      ),
+    },
+  },
   {
     name: "twitter_home_timeline",
     path: "/twitter/user/home_timeline",
@@ -782,7 +832,7 @@ export const TOOLS = [
       "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: {
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -808,7 +858,7 @@ export const TOOLS = [
       "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: {
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -834,7 +884,7 @@ export const TOOLS = [
       "List the accounts YOUR authenticated account has BLOCKED, as full user objects, cursor-paginated. Requires an authenticated session behind your key. There is no user_id argument: X provides no way to read another account's block list, so this reads yours only. An empty users array is a real answer meaning you block nobody, never a silent failure, because the endpoint returns an error status rather than an empty page when it cannot read the list.",
     shape: {
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -860,7 +910,7 @@ export const TOOLS = [
       "List the accounts YOUR authenticated account has MUTED, as full user objects, cursor-paginated. Muting hides an account's posts from your timeline without blocking it, so this is a different list from twitter_blocking and an account can appear in one and not the other. Requires an authenticated session behind your key. There is no user_id argument: X provides no way to read another account's mute list. An empty users array means you mute nobody, never a silent failure.",
     shape: {
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -889,7 +939,7 @@ export const TOOLS = [
         "Search terms to match against your bookmarked tweets' text.",
       ),
       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.",
+        "Requested page size, capped at 200. Advisory only for this endpoint: X's own search backend typically returns around 13 to 20 tweets per page regardless of the value requested here, an upstream limit, not something this API controls. To retrieve more results, page with the cursor from the previous response rather than raising this value.",
       ),
       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.",
@@ -1421,6 +1471,13 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_customer_session_status",
+    path: "/twitter/customer/session/status",
+    description:
+      "Read back the X account session you registered with twitter_customer_session, without changing it. Returns registered (false if you never registered one), the resolved username and twitter_user_id the session actually maps to, status ('ok', or 'dead' once X has rejected the cookies), created_at, updated_at, last_used_at, and an egress block: source (one of session, sticky_residential, pool_residential, direct), customer_proxy_in_use (true when the proxy_url you registered is the one your writes leave from), and a note explaining that tier. Never returns auth_token, ct0, or any proxy URL. Use it to answer 'am I posting as the account I think I am', 'has my session expired', and 'is the proxy I supplied actually being used' without opening a support ticket. Free, and scoped to your own API key by construction: it takes no account identifier of any kind, so it cannot read another key's session.",
+    shape: {},
+  },
   {
     name: "twitter_customer_session_delete",
     path: "/twitter/customer/session/delete",
@@ -1780,6 +1837,9 @@ export const TOOLS = [
       webhook_ids: z.string().optional().describe(
         "Optional. Comma-separated webhook id(s) from twitter_monitor_webhook_create to restrict this monitor's deliveries to. Omit to deliver to every active webhook on the account (the default).",
       ),
+      include_replies: z.string().optional().describe(
+        "Optional boolean. true delivers the account's replies as well as its own posts, which is the default and what every monitor has always done; false holds replies back and delivers only the account's own posts. Must be a real boolean: the string \"false\" and the number 0 are rejected with a 400 rather than coerced, because coercing them would quietly give you the opposite of what you typed, and the wrong answer here is invisible since it looks exactly like the account not having posted.",
+      ),
       domain_filter: z.string().optional().describe(
         "Optional. A bare hostname ('example.com') or a full URL ('https://example.com/blog') to restrict delivery to only the new posts that link to that host or a subdomain of it (e.g. 'example.com' matches both example.com and blog.example.com). Normalized server-side: lowercased, scheme/path/query/fragment/leading www./trailing :port stripped. Omit for no filter, the default (deliver every new post). Rejected with a 400 if what remains after normalization is not a valid hostname shape. A post with no matching link is filtered out of delivery, never silently dropped: it still advances the monitor's cursor and counts toward the account's tweets_domain_filtered health metric.",
       ),
@@ -1814,6 +1874,9 @@ export const TOOLS = [
       domain_filter: z.string().nullable().optional().describe(
         "Optional. A bare hostname or full URL to restrict delivery to, same shape and normalization as twitter_monitor_create's domain_filter. Pass an empty string (or null) to clear an existing filter back to 'deliver every new post'. Omit entirely to leave the current filter unchanged. Rejected with a 400 if a non-empty value does not normalize to a valid hostname.",
       ),
+      include_replies: z.string().optional().describe(
+        "Optional boolean. true delivers the account's replies as well as its own posts, false holds replies back and delivers only its own posts. Omit the field entirely to leave it unchanged. Same boolean-only validation as twitter_monitor_create: a non-boolean is a 400 rather than a coercion.",
+      ),
     },
   },
   {
@@ -1947,6 +2010,27 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "twitter_monitor_webhook_redrive",
+    path: "/twitter/webhook/{id}/redrive",
+    method: "POST",
+    write: true,
+    jsonBody: true,
+    pathParams: ["id"],
+    description:
+      "Replay deliveries that dead-lettered while your endpoint was down. A delivery is dead-lettered after it fails all 8 attempts across 21 minutes, so an outage longer than that window loses those events; this re-queues them with a full retry budget, oldest first. Bounded by default so a recovered endpoint is not flooded: max_age_hours defaults to 24 and limit to 100. Returns requeued and skipped_permanent. A delivery that died for a permanent reason, a 410 Gone, a deleted webhook, or a URL egress refused, is not replayed, because it would fail the same way and spend the budget again. Replayed events carry the same signature and payload as the original, so make your handler idempotent on the event id if a duplicate would matter. Returns 409 if the webhook is disabled, which happens after your endpoint answers 410 Gone: re-register it first. Free per call.",
+    shape: {
+      id: z.string().describe(
+        "The webhook's id, from twitter_monitor_webhook_create or twitter_monitor_webhook_list.",
+      ),
+      max_age_hours: z.number().int().optional().describe(
+        "Optional. How far back to look for dead-lettered deliveries, 1 to 168 hours. Defaults to 24.",
+      ),
+      limit: z.number().int().optional().describe(
+        "Optional. Most deliveries to replay in one call, 1 to 1000, oldest first. Defaults to 100.",
+      ),
+    },
+  },
 ];
 
 // The query-string builder and the path-param substitution helper are