@twitterapis/mcp 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.14.0 (2026-09-29)
+
+- **`@twitterapis/mcp/server` export and `authHeaders`.** The package now
+  exports `createServer` at `@twitterapis/mcp/server`, so a host can serve the
+  same tools remotely. `createServer({ authHeaders })` authenticates each call
+  with headers the host supplies instead of an API key, for a host that has
+  already authenticated the caller another way (an OAuth token resolved to an
+  account). Without it, behavior is unchanged: the API key is sent as before.
+  The `exports` map keeps `.` (the stdio entry) and `./package.json`.
+
+- **Per-caller server state.** The server is now built by `createServer()` in
+  `src/server.js`, which holds the API key and the last-failed-call record in
+  its own closure instead of module globals. Under stdio nothing changes (one
+  process, one caller); it is the prerequisite for serving the same tools
+  remotely, where one process serves many callers and a global would send one
+  caller's requests with another's key. `src/index.js` is now only the stdio
+  entry and the one place config is read from the environment.
+  `test/per-caller-state.test.mjs` proves two servers in one process never
+  share a key or a failure record (red when `lastError` is hoisted back to
+  module scope).
+
+## 0.13.1 (2026-09-28)
+
+- **`twitter_user_search` no longer claims bio matching.** X's People search
+  matches display name and handle only; a term that appears only in a bio
+  returns no match (measured live 2026-09-28). The description and the `query`
+  arg now say so, and point to `twitter_user_followers` or
+  `twitter_advanced_search` plus a `description` filter for bio lookups. No
+  schema change; `test/openapi.snapshot.json` and the catalog baseline are
+  refreshed to the corrected docs SoT.
+
 ## 0.13.0 (2026-09-23)
 
 - **Every data read takes `fields` and `compact`.** The API added response

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@twitterapis/mcp",
   "mcpName": "io.github.TwitterAPIs/twitterapis-mcp",
-  "version": "0.13.0",
+  "version": "0.14.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",
@@ -12,6 +12,11 @@
     "twitterapis-mcp": "src/index.js"
   },
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "README.md",
@@ -28,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/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",
     "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/index.js

@@ -6,33 +6,29 @@
 // lists, mentions, likes, bookmarks, DMs, home timeline) plus write actions
 // (post/delete tweet, like, retweet, bookmark, follow, and their inverses).
 // Each tool is a thin, typed wrapper over a REST endpoint at
-// https://api.twitterapis.com. The server holds no state and forwards your API
-// key on every call. The tool catalog lives in ./tools.js.
+// https://api.twitterapis.com. The server forwards your API key on every call.
+// The tool catalog lives in ./tools.js; the server itself is built by
+// createServer() in ./server.js, which holds every per-caller value (key, last
+// failure) in its own closure so the same code can serve many callers.
 //
-// Config (env):
+// This file is the stdio entry point and the ONLY place config is read from
+// the environment:
 //   TWITTERAPIS_KEY        required. Your key from https://www.twitterapis.com/signup
 //   TWITTERAPIS_BASE_URL   optional. Defaults to https://api.twitterapis.com
 //   TWITTERAPIS_TIMEOUT_MS optional. Per-request timeout (default 30000)
 //
 // Run:  npx -y @twitterapis/mcp@latest   (stdio transport)
 
-import { createRequire } from "node:module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOLS } from "./tools.js";
+import { createServer, hintFor, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from "./server.js";
 
-// Single source of truth for the version. Previously this was a literal in two
-// places and drifted: the package shipped 0.5.0 while the MCP handshake and the
-// 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";
+// Re-exported so existing importers of the entry point keep working.
+export { hintFor };
 
 const API_KEY = process.env.TWITTERAPIS_KEY;
-const BASE_URL = (
-  process.env.TWITTERAPIS_BASE_URL || "https://api.twitterapis.com"
-).replace(/\/+$/, "");
+const BASE_URL = process.env.TWITTERAPIS_BASE_URL || DEFAULT_BASE_URL;
 
-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:
@@ -64,228 +60,24 @@ if (rawTimeoutEnv) {
 // confirmed live 2026-08-18 (Smithery: "Initialization failed... could not be
 // automatically scanned", HTTP 405). Warn and continue; a real tool CALL made
 // with no key still fails clearly, at the point of the call, same as it
-// already does for a bad key (see the 401 branch below).
+// already does for a bad key (see the 401 branch in server.js).
 if (!API_KEY) {
   console.error(
     "[twitterapis-mcp] Missing TWITTERAPIS_KEY. Get a key at https://www.twitterapis.com/signup and set it in your MCP client config. Tools are registered but every call will fail until it is set.",
   );
 }
 
-// ── REST call ────────────────────────────────────────────────────────────────
-// Most endpoints (GET reads and the simple POST writes alike) read their params
-// from the query string, so the same buildQuery path serves both and only the
-// HTTP method differs. A few POST endpoints (customer/session, user_login,
-// media/upload) instead read a JSON request body; those tools set jsonBody:true
-// and callEndpoint sends the args in the body rather than the query string. A
-// handful of monitoring endpoints (/monitor/{id}, /webhook/{id}, ...) carry a
-// REST path parameter instead: those tools set pathParams (the arg names to
-// 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;
-
-// The 404 hint used to be a flat status-only ternary telling EVERY caller that
-// "the user, tweet, or list may have been deleted or the id is wrong". For a
-// feedback id that sentence is simply wrong, and it sends a customer chasing a
-// report id off to look at a tweet. The feedback routes are the first mounted
-// outside the /twitter surface, so they are the first place the assumption is
-// plainly visible; /account/* would have been next.
-//
-// ONLY THE 404 VARIES. Every other status is about the KEY, the CREDIT
-// balance, the caller's SESSION, or OUR service, and each of those reads
-// identically on every endpoint. Adding per-path branches for them would be
-// surface area with no reader.
-const NOT_FOUND_HINTS = [
-  [/^\/feedback/, " (not found. No feedback report with that id on this account, and an id from another account will not resolve here. Use the id returned by twitter_feedback_send action=send.)"],
-  [/^\/account/, " (not found. That account resource does not exist for this key.)"],
-];
-const DEFAULT_NOT_FOUND_HINT =
-  " (not found. The user, tweet, or list may have been deleted or the id is wrong)";
-
-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)";
-  if (status === 403) return " (access forbidden. The resource may be private or your plan does not include this endpoint)";
-  if (status === 404) {
-    for (const [re, h] of NOT_FOUND_HINTS) if (re.test(path || "")) return h;
-    return DEFAULT_NOT_FOUND_HINT;
-  }
-  if (status === 409) return " (no authenticated X session for this key. Write actions and account-only reads (likes, bookmarks, DMs, home timeline, follow, post) require linking an X account/session to your key first; see https://www.twitterapis.com/dashboard)";
-  if (status === 429) return " (rate limited. Wait a few seconds and retry; reduce request frequency or increase TWITTERAPIS_TIMEOUT_MS if needed)";
-  if (status >= 500) return " (upstream API error. Retry in a moment; if persistent, check https://www.twitterapis.com/status)";
-  return "";
-}
-
-async function callEndpoint(path, args, method = "GET", jsonBody = false, pathParams = []) {
-  if (!API_KEY) {
-    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).",
-      }],
-    };
-  }
-  // 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
-  // contains the literal "{id}" against the API.
-  let resolvedPath, all;
-  try {
-    ({ path: resolvedPath, args: all } = resolvePathParams(path, pathParams, args));
-  } catch (err) {
-    if (err instanceof MissingPathParamError) {
-      return { isError: true, content: [{ type: "text", text: err.message }] };
-    }
-    throw err;
-  }
-
-  const headers = {
-    // The API accepts either header; send both for maximum compatibility.
-    Authorization: `Bearer ${API_KEY}`,
-    "x-api-key": API_KEY,
-    accept: "application/json",
-    "user-agent": `twitterapis-mcp/${VERSION}`,
-  };
-
-  let url;
-  let reqBody;
-  if (jsonBody) {
-    // Endpoints whose handler reads a JSON request body (customer/session,
-    // user_login, media/upload). Send every arg in the body: for customer/session
-    // and user_login the credentials ARE the payload the handler reads from the
-    // body, so they must NOT be diverted into x-* headers the way per-call inline
-    // creds are on the query-string tools.
-    url = `${BASE_URL}${resolvedPath}`;
-    headers["content-type"] = "application/json";
-    reqBody = JSON.stringify(all);
-  } else {
-    // Pull per-call inline credentials out of args so they travel as request
-    // headers, never the query string (the API reads x-auth-token / x-ct0; passing
-    // them as query params would leak them into URLs and access logs). When
-    // supplied, this one API key acts as that account; otherwise the key's linked
-    // session is used. Lets a single key act as many accounts.
-    const { auth_token, ct0, user_agent, proxy_url, ...rest } = all;
-    const q = buildQuery(rest);
-    url = `${BASE_URL}${resolvedPath}${q ? `?${q}` : ""}`;
-    if (auth_token && ct0) {
-      headers["x-auth-token"] = auth_token;
-      headers["x-ct0"] = ct0;
-      if (user_agent) headers["x-user-agent"] = user_agent;
-      if (proxy_url) headers["x-proxy-url"] = proxy_url;
-    }
-  }
-
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
-  try {
-    const res = await fetch(url, {
-      method,
-      headers,
-      body: reqBody,
-      signal: ctrl.signal,
-    });
-    const body = await res.text();
-    if (!res.ok) {
-      const hint = hintFor(res.status, resolvedPath);
-      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);
-  }
-}
-
-// ── MCP server ───────────────────────────────────────────────────────────────
-// 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\". " +
-  "Before drafting a report that a parameter is IGNORED or a field is EMPTY, re-run the call with a distinctive value that could only match if the parameter was honoured, and with the phrase quoted; " +
-  "if either comes back on topic the issue is ranking or matching, so title it that way and say what the control showed.";
-
-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";
-  // Surface read/write/destructive intent so MCP clients can warn before a
-  // mutating call (default = read-only).
-  const annotations = {
-    title: tool.name,
-    readOnlyHint: !tool.write,
-    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 },
-    handler,
-  );
-}
-
 async function main() {
+  const { server, baseUrl } = createServer({
+    apiKey: API_KEY,
+    baseUrl: BASE_URL,
+    timeoutMs: REQUEST_TIMEOUT_MS,
+    feedbackEnv: process.env,
+  });
   const transport = new StdioServerTransport();
   await server.connect(transport);
   // Logs go to stderr so they never corrupt the stdio JSON-RPC stream.
-  console.error(`[twitterapis-mcp] ready · ${TOOLS.length} tools · base ${BASE_URL}`);
+  console.error(`[twitterapis-mcp] ready · ${TOOLS.length} tools · base ${baseUrl}`);
 }
 
 main().catch((err) => {

package/src/server.js

@@ -0,0 +1,270 @@
+// createServer(): one McpServer per caller, holding that caller's key and last
+// failure in its own closure.
+//
+// WHY A FACTORY: the key and the last-failed-call record used to be module
+// globals. Under stdio there is one process per user, so that was harmless;
+// served remotely, one process serves many users, and a module global would
+// send one caller's requests with another caller's key and hand one caller's
+// failure (path, request id) to another caller's feedback draft. Every piece
+// of per-caller state now lives inside createServer, and nothing in this file
+// reads process.env: the entry point (index.js for stdio) resolves config and
+// passes it in.
+
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TOOLS, buildQuery, resolvePathParams, MissingPathParamError } from "./tools.js";
+import { createFeedbackHandler } from "./feedback.js";
+
+// Single source of truth for the version. Previously this was a literal in two
+// places and drifted: the package shipped 0.5.0 while the MCP handshake and the
+// outbound user-agent both still advertised 0.3.0.
+export const VERSION = createRequire(import.meta.url)("../package.json").version;
+
+export const DEFAULT_BASE_URL = "https://api.twitterapis.com";
+export const DEFAULT_TIMEOUT_MS = 30000;
+
+// The 404 hint used to be a flat status-only ternary telling EVERY caller that
+// "the user, tweet, or list may have been deleted or the id is wrong". For a
+// feedback id that sentence is simply wrong, and it sends a customer chasing a
+// report id off to look at a tweet. The feedback routes are the first mounted
+// outside the /twitter surface, so they are the first place the assumption is
+// plainly visible; /account/* would have been next.
+//
+// ONLY THE 404 VARIES. Every other status is about the KEY, the CREDIT
+// balance, the caller's SESSION, or OUR service, and each of those reads
+// identically on every endpoint. Adding per-path branches for them would be
+// surface area with no reader.
+const NOT_FOUND_HINTS = [
+  [/^\/feedback/, " (not found. No feedback report with that id on this account, and an id from another account will not resolve here. Use the id returned by twitter_feedback_send action=send.)"],
+  [/^\/account/, " (not found. That account resource does not exist for this key.)"],
+];
+const DEFAULT_NOT_FOUND_HINT =
+  " (not found. The user, tweet, or list may have been deleted or the id is wrong)";
+
+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)";
+  if (status === 403) return " (access forbidden. The resource may be private or your plan does not include this endpoint)";
+  if (status === 404) {
+    for (const [re, h] of NOT_FOUND_HINTS) if (re.test(path || "")) return h;
+    return DEFAULT_NOT_FOUND_HINT;
+  }
+  if (status === 409) return " (no authenticated X session for this key. Write actions and account-only reads (likes, bookmarks, DMs, home timeline, follow, post) require linking an X account/session to your key first; see https://www.twitterapis.com/dashboard)";
+  if (status === 429) return " (rate limited. Wait a few seconds and retry; reduce request frequency or increase TWITTERAPIS_TIMEOUT_MS if needed)";
+  if (status >= 500) return " (upstream API error. Retry in a moment; if persistent, check https://www.twitterapis.com/status)";
+  return "";
+}
+
+// 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.
+export 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\". " +
+  "Before drafting a report that a parameter is IGNORED or a field is EMPTY, re-run the call with a distinctive value that could only match if the parameter was honoured, and with the phrase quoted; " +
+  "if either comes back on topic the issue is ranking or matching, so title it that way and say what the control showed.";
+
+/**
+ * Build one server for one caller.
+ *
+ * @param {object} opts
+ * @param {string|undefined} opts.apiKey   the caller's key; calls fail clearly without one
+ * @param {string} [opts.baseUrl]          API origin, default https://api.twitterapis.com
+ * @param {number} [opts.timeoutMs]        per-request timeout, must be > 0
+ * @param {object} [opts.feedbackEnv]      env-shaped object for the feedback queue location
+ *                                         (TWITTERAPIS_FEEDBACK_DIR); a remote host gives each
+ *                                         caller its own directory
+ * @param {typeof fetch} [opts.fetchImpl]  injectable for tests
+ * @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
+ *        token resolved to an account) and forwards calls over its own trusted
+ *        channel. When set, no API key is required or sent.
+ */
+export function createServer({
+  apiKey,
+  baseUrl = DEFAULT_BASE_URL,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  feedbackEnv = process.env,
+  fetchImpl = fetch,
+  authHeaders = null,
+} = {}) {
+  const BASE_URL = String(baseUrl).replace(/\/+$/, "");
+  const REQUEST_TIMEOUT_MS = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  // 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.
+  // Per server, so one caller's failure never reaches another caller's draft.
+  let lastError = null;
+
+  // ── REST call ──────────────────────────────────────────────────────────────
+  // Most endpoints (GET reads and the simple POST writes alike) read their params
+  // from the query string, so the same buildQuery path serves both and only the
+  // HTTP method differs. A few POST endpoints (customer/session, user_login,
+  // media/upload) instead read a JSON request body; those tools set jsonBody:true
+  // and callEndpoint sends the args in the body rather than the query string. A
+  // handful of monitoring endpoints (/monitor/{id}, /webhook/{id}, ...) carry a
+  // REST path parameter instead: those tools set pathParams (the arg names to
+  // 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 = []) {
+    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).",
+        }],
+      };
+    }
+    // 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
+    // contains the literal "{id}" against the API.
+    let resolvedPath, all;
+    try {
+      ({ path: resolvedPath, args: all } = resolvePathParams(path, pathParams, args));
+    } catch (err) {
+      if (err instanceof MissingPathParamError) {
+        return { isError: true, content: [{ type: "text", text: err.message }] };
+      }
+      throw err;
+    }
+
+    const headers = {
+      ...(authHeaders
+        ? { ...authHeaders }
+        : {
+            // The API accepts either header; send both for maximum compatibility.
+            Authorization: `Bearer ${apiKey}`,
+            "x-api-key": apiKey,
+          }),
+      accept: "application/json",
+      "user-agent": `twitterapis-mcp/${VERSION}`,
+    };
+
+    let url;
+    let reqBody;
+    if (jsonBody) {
+      // Endpoints whose handler reads a JSON request body (customer/session,
+      // user_login, media/upload). Send every arg in the body: for customer/session
+      // and user_login the credentials ARE the payload the handler reads from the
+      // body, so they must NOT be diverted into x-* headers the way per-call inline
+      // creds are on the query-string tools.
+      url = `${BASE_URL}${resolvedPath}`;
+      headers["content-type"] = "application/json";
+      reqBody = JSON.stringify(all);
+    } else {
+      // Pull per-call inline credentials out of args so they travel as request
+      // headers, never the query string (the API reads x-auth-token / x-ct0; passing
+      // them as query params would leak them into URLs and access logs). When
+      // supplied, this one API key acts as that account; otherwise the key's linked
+      // session is used. Lets a single key act as many accounts.
+      const { auth_token, ct0, user_agent, proxy_url, ...rest } = all;
+      const q = buildQuery(rest);
+      url = `${BASE_URL}${resolvedPath}${q ? `?${q}` : ""}`;
+      if (auth_token && ct0) {
+        headers["x-auth-token"] = auth_token;
+        headers["x-ct0"] = ct0;
+        if (user_agent) headers["x-user-agent"] = user_agent;
+        if (proxy_url) headers["x-proxy-url"] = proxy_url;
+      }
+    }
+
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetchImpl(url, {
+        method,
+        headers,
+        body: reqBody,
+        signal: ctrl.signal,
+      });
+      const body = await res.text();
+      if (!res.ok) {
+        const hint = hintFor(res.status, resolvedPath);
+        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);
+    }
+  }
+
+  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,
+      env: feedbackEnv,
+    }),
+  };
+
+  for (const tool of TOOLS) {
+    const method = tool.method || "GET";
+    // Surface read/write/destructive intent so MCP clients can warn before a
+    // mutating call (default = read-only).
+    const annotations = {
+      title: tool.name,
+      readOnlyHint: !tool.write,
+      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/server.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 },
+      handler,
+    );
+  }
+
+  return { server, callEndpoint, getLastError: () => lastError, baseUrl: BASE_URL, timeoutMs: REQUEST_TIMEOUT_MS };
+}

package/src/tools.js

@@ -61,10 +61,10 @@ export const TOOLS = [
     name: "twitter_user_search",
     path: "/twitter/user/search",
     description:
-      "Search for Twitter/X user accounts by name, keyword, or topic. Returns matching profiles (username, display name, bio, follower count, verification status) with a pagination cursor. Use this to discover accounts in a niche, find brand handles, or locate a person when you only know their name.",
+      "Search for Twitter/X user accounts by display name or handle (X's People search; bio text is NOT searched, so a word that appears only in a bio returns no match). Returns matching profiles (username, display name, bio, follower count, verification status) with a pagination cursor. Use this to find brand handles, resolve a partial handle, or locate a person when you only know their name. To find accounts by what their bio says, use twitter_user_followers on a relevant account or twitter_advanced_search for tweets mentioning it, then filter the description field.",
     shape: {
       query: z.string().describe(
-        "Name, keyword, or topic to search accounts for. Examples: 'OpenAI', 'AI researcher', 'tech founder'.",
+        "Name, brand, or partial handle to search accounts for, matched against display name and handle. Examples: 'OpenAI', 'Sam Altman', 'stablecoin'.",
       ),
       count: z.number().int().min(1).max(200).optional().describe(
         "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.",