redditapis-mcp 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.8.0 (2026-09-29)
+
+### Added
+
+- **Remote hosting.** `redditapis-mcp/server` exports `createServer`, and an
+  `authHeaders` option authenticates calls with headers the host supplies
+  instead of an API key, for a remote MCP endpoint that has already signed the
+  caller in (a connected app over OAuth).
+
+### Changed
+
+- **A read rides out an API restart.** A read that gets the gateway's HTML
+  502/503, or a refused connection, is retried after 3 and then 8
+  seconds. The API's own JSON errors, gateway timeouts, DNS or TLS failures
+  and every write are never retried, so a request the API may already have
+  handled is not sent twice.
+
+## 0.7.0 (2026-09-29)
+
+### Added
+
+- **Agent-actionable paywall.** A missing key, a rejected key (403 Invalid token)
+  and an empty balance (402 Insufficient credits) now return a structured payload
+  instead of a prose hint:
+  `needs` (`account`, `valid_key` or `credits`), the exact page to send the user
+  to (`action_url`: signup, API keys, or buy credits), and one sentence the
+  agent can relay, both in the text and as `structuredContent`. An agent that
+  runs out of credit mid-task can now tell the user where to top up and retry
+  the same call. Other failures keep their existing hints, including a 402 for
+  a monitoring plan or slot limit, which buying credits would not fix.
+- The MCP SDK floor is pinned to ^1.29.0.
+
+### Changed
+
+- **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. `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.
+
 ## 0.6.1 (2026-09-11)
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "mcpName": "io.github.redditapis/redditapis-mcp",
   "description": "Official MCP server for redditapis.com. Search Reddit posts, comments, communities, users and media; read subreddits, comment trees, top posts and profiles; create and manage monitors and webhooks. Native tools for Claude, Cursor and any MCP client.",
   "repository": {
@@ -13,6 +13,11 @@
     "redditapis-mcp": "src/index.js"
   },
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src",
     "README.md",
@@ -26,11 +31,11 @@
   "scripts": {
     "start": "node src/index.js",
     "check": "node --check src/index.js && node --check src/tools.js && node --check src/feedback.js",
-    "test": "node test/tools.test.mjs && node test/feedback.test.mjs && node test/index-lasterror.test.mjs && node test/scannable-without-key.test.mjs",
+    "test": "node test/tools.test.mjs && node test/feedback.test.mjs && node test/index-lasterror.test.mjs && node test/scannable-without-key.test.mjs && node test/per-caller-state.test.mjs && node test/paywall.test.mjs && node test/remote-host.test.mjs",
     "prepublishOnly": "node scripts/prepublish-tenant-check.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.23.8 || ^4.0.0"
   },
   "keywords": [

package/src/index.js

@@ -10,10 +10,12 @@
 // user has reviewed. Each tool is a thin, typed wrapper over a REST endpoint at
 // https://api.redditapis.com, except reddit_feedback_send, whose draft queue
 // lives on this machine (./feedback.js) and posts only on the user's say. The
-// server holds no other state and forwards your API key on every call. The
-// tool catalog lives in ./tools.js.
+// 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:
 //   REDDITAPIS_KEY        required. Your key from https://www.redditapis.com
 //                         (REDDIT_APIS_KEY is accepted as an alias).
 //   REDDITAPIS_BASE_URL   optional. Defaults to https://api.redditapis.com
@@ -23,21 +25,16 @@
 //
 // Run:  npx -y redditapis-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, buildQuery, buildPath, buildBody, buildHeaders } from "./tools.js";
-import { createFeedbackHandler, sameFailure } from "./feedback.js";
+import { TOOLS } from "./tools.js";
+import { createServer, hintFor, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from "./server.js";
+
+// Re-exported so existing importers of the entry point keep working.
+export { hintFor };
 
 const API_KEY = process.env.REDDITAPIS_KEY || process.env.REDDIT_APIS_KEY;
-const BASE_URL = (
-  process.env.REDDITAPIS_BASE_URL || "https://api.redditapis.com"
-).replace(/\/+$/, "");
-const REQUEST_TIMEOUT_MS = Number(process.env.REDDITAPIS_TIMEOUT_MS || 30000);
-// Read from package.json rather than a hand-maintained literal -- this drifted
-// silently to "0.1.0" while the published package reached 0.1.12, so every
-// User-Agent and MCP server handshake understated its own version for months.
-const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+const BASE_URL = process.env.REDDITAPIS_BASE_URL || DEFAULT_BASE_URL;
+const REQUEST_TIMEOUT_MS = Number(process.env.REDDITAPIS_TIMEOUT_MS || DEFAULT_TIMEOUT_MS);
 
 // WARN AND CONTINUE, NEVER exit. A registry scanner spawns the server and calls
 // tools/list to enumerate what it offers, and tools/list is the DISCOVERY step
@@ -53,192 +50,25 @@ const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 // NOT a security relaxation. This is a stdio server: whoever spawns it already
 // has local execution, so there is no unauthenticated party to expose anything
 // to. A real tool CALL with no key still fails clearly, at the point of the
-// call, exactly as it already does for a WRONG key (see the 401 branch below).
+// call, exactly as it already does for a WRONG key (see the 401 branch in
+// server.js).
 if (!API_KEY) {
   console.error(
     "[reddit-mcp] Missing REDDITAPIS_KEY. Get a key at https://www.redditapis.com and set it in your MCP client config. Tools are registered but every call will fail until it is set.",
   );
 }
 
-// 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;
-
-// REST call. Resolves any {param} path placeholders from args, and for GET
-// sends the rest as a query string; for POST it sends the rest as a JSON body
-// (see buildBody -- `tool` is passed through only to read its
-// `filterSpecFields`). Forwards the API key as a Bearer token (redditapis.com
-// authenticates via `Authorization: Bearer <key>` only).
-// The trailing sentence appended to a failed call, so the model reads an error
-// it can act on rather than a bare status.
-//
-// A 404 HINT HAS TO KNOW WHICH ENDPOINT WAS CALLED. This was a flat status-only
-// ternary, so every 404 in the catalog got the listing-shaped sentence, and a
-// caller whose FEEDBACK id was not found was told to check their subreddit,
-// post id or permalink. None of those are involved. The feedback endpoints are
-// the first mounted outside the /api/reddit surface, so they are the first
-// place that assumption is plainly wrong; /account/* would have been next.
-//
-// Only the 404 varies, because it is the only status whose useful advice
-// depends on what was being looked up. Everything else is about the KEY, the
-// CREDIT balance or OUR service and reads the same on every endpoint.
-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 reddit_feedback_send action=send.)"],
-  [/^\/account/, " (not found. That account resource does not exist for this key.)"],
-];
-const DEFAULT_NOT_FOUND_HINT =
-  " (not found. The subreddit, post id, user, or permalink may be wrong or deleted)";
-
-export function hintFor(status, path) {
-  if (status === 401) return " (invalid or missing API key, verify REDDITAPIS_KEY at https://www.redditapis.com)";
-  if (status === 402) return " (insufficient credits, top up at https://www.redditapis.com)";
-  if (status === 403) return " (access forbidden. The subreddit/user may be private, banned, or quarantined)";
-  if (status === 404) {
-    for (const [re, hint] of NOT_FOUND_HINTS) if (re.test(path || "")) return hint;
-    return DEFAULT_NOT_FOUND_HINT;
-  }
-  if (status === 429) return " (rate limited. Wait a few seconds and retry, or reduce request frequency)";
-  if (status >= 500) return " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)";
-  return "";
-}
-
-async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
-  // The credential check MOVED HERE from startup, so listing tools needs no key
-  // and calling one still cannot silently proceed without it. Without this the
-  // relaxation above would send an Authorization header reading "Bearer
-  // undefined" and the caller would read a 401 about an INVALID key when the
-  // real answer is that no key was ever set.
-  if (!API_KEY) {
-    return {
-      isError: true,
-      content: [{
-        type: "text",
-        text: "Missing REDDITAPIS_KEY (no API key is set; get one at https://www.redditapis.com and set it in your MCP client config).",
-      }],
-    };
-  }
-  const { path, rest: pathRest } = buildPath(pathTemplate, args);
-  // A tool that declares `sessionHeaders` has its Reddit session args lifted
-  // out of the query and onto headers. For every other tool this is the
-  // identity, so the request is byte-for-byte what it was before.
-  const { headers: sessionHeaders, rest } = buildHeaders(tool, pathRest);
-  const isWrite = method !== "GET";
-  const q = isWrite ? "" : buildQuery(rest);
-  const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
-
-  const headers = {
-    Authorization: `Bearer ${API_KEY}`,
-    accept: "application/json",
-    "user-agent": `reddit-mcp/${VERSION}`,
-    ...sessionHeaders,
-  };
-  let requestBody;
-  if (isWrite) {
-    headers["content-type"] = "application/json";
-    requestBody = JSON.stringify(buildBody(tool || {}, rest));
-  }
-
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
-  try {
-    const res = await fetch(url, { method, headers, body: requestBody, signal: ctrl.signal });
-    const body = await res.text();
-    if (!res.ok) {
-      const hint = hintFor(res.status, path);
-      lastError = {
-        path,
-        method,
-        status: res.status,
-        requestId: res.headers.get("x-request-id") || undefined,
-        ts: Date.now(),
-      };
-      // Credential, credit, rate-limit and not-found failures are the caller's
-      // situation (a 404 is almost always a wrong id or a deleted thing, a 409
-      // a conflict with the caller's own state), 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 reddit_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 remove'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, method, status: null, error: msg.slice(0, 200), ts: Date.now() };
-    return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-// 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 =
-  "redditapis.com MCP server. Read tools cost credits per call (most $0.002); monitor, webhook and feedback tools are free. " +
-  "If a redditapis tool call fails with an error other than 401/402/429 and the user has to work around it, if the user asks for something no redditapis 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 reddit_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: "redditapis", 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";
-  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(`[reddit-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, tool);
-      if (result?.isError && lastError) {
-        let resolved = null;
-        try { resolved = buildPath(tool.path, args).path; } catch { resolved = null; }
-        // Name the tool only when BOTH method and path match the recorded
-        // failure; a GET and a POST can share a path.
-        if (sameFailure(lastError, resolved, 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(`[reddit-mcp] ready · ${TOOLS.length} tools · base ${BASE_URL}`);
+  console.error(`[reddit-mcp] ready · ${TOOLS.length} tools · base ${baseUrl}`);
 }
 
 main().catch((err) => {

package/src/server.js

@@ -0,0 +1,344 @@
+// 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, buildPath, buildBody, buildHeaders } from "./tools.js";
+import { createFeedbackHandler, sameFailure } from "./feedback.js";
+
+// Read from package.json rather than a hand-maintained literal -- this drifted
+// silently to "0.1.0" while the published package reached 0.1.12, so every
+// User-Agent and MCP server handshake understated its own version for months.
+export const { version: VERSION } = createRequire(import.meta.url)("../package.json");
+
+export const DEFAULT_BASE_URL = "https://api.redditapis.com";
+export const DEFAULT_TIMEOUT_MS = 30000;
+
+// The trailing sentence appended to a failed call, so the model reads an error
+// it can act on rather than a bare status.
+//
+// A 404 HINT HAS TO KNOW WHICH ENDPOINT WAS CALLED. This was a flat status-only
+// ternary, so every 404 in the catalog got the listing-shaped sentence, and a
+// caller whose FEEDBACK id was not found was told to check their subreddit,
+// post id or permalink. None of those are involved. The feedback endpoints are
+// the first mounted outside the /api/reddit surface, so they are the first
+// place that assumption is plainly wrong; /account/* would have been next.
+//
+// Only the 404 varies, because it is the only status whose useful advice
+// depends on what was being looked up. Everything else is about the KEY, the
+// CREDIT balance or OUR service and reads the same on every endpoint.
+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 reddit_feedback_send action=send.)"],
+  [/^\/account/, " (not found. That account resource does not exist for this key.)"],
+];
+const DEFAULT_NOT_FOUND_HINT =
+  " (not found. The subreddit, post id, user, or permalink may be wrong or deleted)";
+
+// AGENT-ACTIONABLE PAYWALL. A missing key, a rejected key and an empty balance
+// are the moments a user decides whether to keep using the product, and they
+// happen inside an agent's turn. Prose like "top up at redditapis.com" leaves
+// the agent guessing where to send the user; a structured payload names the
+// exact page, so the agent can say "you have used your free credit, top up
+// here" and resume after. The payload is both appended to the text (every
+// client reads that) and returned as structuredContent (clients that parse it).
+export const SIGNUP_URL = "https://www.redditapis.com/signup?utm_source=mcp&utm_medium=tool_error";
+export const API_KEYS_URL = "https://www.redditapis.com/dashboard/api-keys?utm_source=mcp&utm_medium=tool_error";
+export const TOP_UP_URL = "https://www.redditapis.com/dashboard/buy-credits?utm_source=mcp&utm_medium=tool_error";
+
+export function paywallFor(kind) {
+  if (kind === "no_key") {
+    return {
+      needs: "account",
+      message:
+        "Missing REDDITAPIS_KEY: no API key is set. Sign up free at redditapis.com (new accounts start " +
+        "with free credit, no card), copy the key from the dashboard, set REDDITAPIS_KEY in the MCP " +
+        "client config, then retry this call.",
+      action_url: SIGNUP_URL,
+      api_keys_url: API_KEYS_URL,
+      retry: "same call, after the key is set",
+    };
+  }
+  if (kind === "bad_key") {
+    return {
+      needs: "valid_key",
+      message:
+        "The redditapis.com API key was rejected (invalid, revoked or rotated). Copy a current key from " +
+        "the dashboard, set REDDITAPIS_KEY, then retry this call.",
+      action_url: API_KEYS_URL,
+      retry: "same call, after the key is replaced",
+    };
+  }
+  if (kind === "credits") {
+    return {
+      needs: "credits",
+      message:
+        "The redditapis.com account is out of credits. Top up (pay as you go, no subscription), then " +
+        "retry this call; nothing was charged for the failed request. reddit_account_me shows the balance.",
+      action_url: TOP_UP_URL,
+      retry: "same call, after topping up",
+    };
+  }
+  return null;
+}
+
+// Which failures ARE a paywall is decided from the API's own response BODY, not
+// the status alone, because the status is shared (review 2026-09-29): the API
+// answers a rejected key with 403 {"error":"Invalid token"} (401 is only a
+// MISSING token, which this client never sends), and 402 also means a monitor
+// plan or slot limit, which buying credits does not fix. Only the two bodies
+// below are paywalls; everything else keeps its ordinary hint.
+export function classifyPaywall(status, bodyText) {
+  let body = null;
+  try {
+    body = JSON.parse(bodyText);
+  } catch {
+    body = null;
+  }
+  const err = body && typeof body.error === "string" ? body.error : "";
+  if ((status === 403 || status === 401) && err === "Invalid token") return { kind: "bad_key" };
+  if (status === 402 && (err === "Insufficient credits" || typeof body?.top_up_url === "string")) {
+    const url = typeof body?.top_up_url === "string" && /^https:\/\/www\.redditapis\.com\//.test(body.top_up_url)
+      ? body.top_up_url
+      : null;
+    return { kind: "credits", topUpUrl: url };
+  }
+  return null;
+}
+
+function paywallResult(kind, detail = "", overrides = {}) {
+  const p = { ...paywallFor(kind), ...overrides };
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${p.message}${detail ? ` (${detail})` : ""}\n\n${JSON.stringify(p)}` }],
+    structuredContent: p,
+  };
+}
+
+export function hintFor(status, path) {
+  if (status === 401) return " (invalid or missing API key, verify REDDITAPIS_KEY at https://www.redditapis.com)";
+  if (status === 402) return " (insufficient credits, top up at https://www.redditapis.com)";
+  if (status === 403) return " (access forbidden. The subreddit/user may be private, banned, or quarantined)";
+  if (status === 404) {
+    for (const [re, hint] of NOT_FOUND_HINTS) if (re.test(path || "")) return hint;
+    return DEFAULT_NOT_FOUND_HINT;
+  }
+  if (status === 429) return " (rate limited. Wait a few seconds and retry, or reduce request frequency)";
+  if (status >= 500) return " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)";
+  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 =
+  "redditapis.com MCP server. Read tools cost credits per call (most $0.002); monitor, webhook and feedback tools are free. " +
+  "If a redditapis tool call fails with an error other than 401/402/429 and the user has to work around it, if the user asks for something no redditapis 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 reddit_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.redditapis.com
+ * @param {number} [opts.timeoutMs]        per-request timeout, must be > 0
+ * @param {object} [opts.feedbackEnv]      env-shaped object for the feedback queue location
+ *                                         (REDDITAPIS_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 already authenticated the caller another way (a connected app's
+ *        OAuth token resolved to an account) and forwards calls over its own
+ *        trusted channel. When set, no API key is required or sent.
+ * @param {(ms:number)=>Promise<void>} [opts.sleepImpl] injectable for tests
+ * @param {number[]} [opts.retryDelaysMs] waits before each retry of a read that
+ *        hit a gateway failure (an API restart); default [3000, 8000]
+ */
+export function createServer({
+  apiKey,
+  baseUrl = DEFAULT_BASE_URL,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  feedbackEnv = process.env,
+  fetchImpl = fetch,
+  authHeaders = null,
+  sleepImpl = (ms) => new Promise((r) => setTimeout(r, ms)),
+  retryDelaysMs = [3000, 8000],
+} = {}) {
+  const BASE_URL = String(baseUrl).replace(/\/+$/, "");
+  const REQUEST_TIMEOUT_MS = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+
+  // 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. Resolves any {param} path placeholders from args, and for GET
+  // sends the rest as a query string; for POST it sends the rest as a JSON body
+  // (see buildBody -- `tool` is passed through only to read its
+  // `filterSpecFields`). Forwards the API key as a Bearer token (redditapis.com
+  // authenticates via `Authorization: Bearer <key>` only).
+  async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
+    // The credential check lives here, not at startup, so listing tools needs no
+    // key and calling one still cannot silently proceed without it. Without this
+    // the request would carry an Authorization header reading "Bearer
+    // undefined" and the caller would read a 401 about an INVALID key when the
+    // real answer is that no key was ever set.
+    if (!apiKey && !authHeaders) return paywallResult("no_key");
+    const { path, rest: pathRest } = buildPath(pathTemplate, args);
+    // A tool that declares `sessionHeaders` has its Reddit session args lifted
+    // out of the query and onto headers. For every other tool this is the
+    // identity, so the request is byte-for-byte what it was before.
+    const { headers: sessionHeaders, rest } = buildHeaders(tool, pathRest);
+    const isWrite = method !== "GET";
+    const q = isWrite ? "" : buildQuery(rest);
+    const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+
+    const headers = {
+      ...(authHeaders ? authHeaders : { Authorization: `Bearer ${apiKey}` }),
+      accept: "application/json",
+      "user-agent": `reddit-mcp/${VERSION}`,
+      ...sessionHeaders,
+    };
+    let requestBody;
+    if (isWrite) {
+      headers["content-type"] = "application/json";
+      requestBody = JSON.stringify(buildBody(tool || {}, rest));
+    }
+
+    // An API restart makes the gateway answer an HTML 502/503 or refuse the
+    // connection for a short window. A READ is retried through it; the API's own
+    // JSON errors, timeouts and writes never are, so a request the API may already have
+    // handled is never sent twice (a gateway 504 is not retried for that reason).
+    // Only a REFUSED connection is retried: the request never reached the API,
+    // so it cannot have been handled or billed. A reset, a broken pipe or a
+    // socket dropped mid-answer can all happen after the API did the work, and
+    // "fetch failed" alone also covers DNS and TLS errors that retrying cannot fix.
+    const RETRYABLE_NET = new Set(["ECONNREFUSED"]);
+    const gatewayFailure = (status, text) =>
+      (status === 502 || status === 503) && /^\s*<(!doctype|html)/i.test(text);
+    const transientNetwork = (err) =>
+      !gotResponse && err?.name !== "AbortError" && RETRYABLE_NET.has(err?.cause?.code ?? err?.code);
+    let attempt = 0;
+    let gotResponse = false;
+    for (;;) {
+    gotResponse = false;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const res = await fetchImpl(url, { method, headers, body: requestBody, signal: ctrl.signal });
+      gotResponse = true;
+      const body = await res.text();
+      if (!isWrite && attempt < retryDelaysMs.length && gatewayFailure(res.status, body)) {
+        clearTimeout(timer);
+        await sleepImpl(retryDelaysMs[attempt++]);
+        continue;
+      }
+      if (!res.ok) {
+        const hint = hintFor(res.status, path);
+        lastError = {
+          path,
+          method,
+          status: res.status,
+          requestId: res.headers.get("x-request-id") || undefined,
+          ts: Date.now(),
+        };
+        // Credential, credit, rate-limit and not-found failures are the caller's
+        // situation (a 404 is almost always a wrong id or a deleted thing, a 409
+        // a conflict with the caller's own state), 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 reddit_feedback_send (queued locally until the user reviews it).";
+        const pw = classifyPaywall(res.status, body);
+        if (pw) {
+          return paywallResult(pw.kind, `HTTP ${res.status}: ${body.slice(0, 1200)}`, pw.topUpUrl ? { action_url: pw.topUpUrl } : {});
+        }
+        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 remove's draft
+      // carried the previous update's 404).
+      lastError = null;
+      return { content: [{ type: "text", text: body }] };
+    } catch (err) {
+      if (!isWrite && attempt < retryDelaysMs.length && transientNetwork(err)) {
+        clearTimeout(timer);
+        await sleepImpl(retryDelaysMs[attempt++]);
+        continue;
+      }
+      const code = err?.cause?.code ?? err?.code;
+      const msg = err?.name === "AbortError"
+        ? `timed out after ${REQUEST_TIMEOUT_MS}ms`
+        : `${err?.message || String(err)}${code ? ` (${code})` : ""}`;
+      lastError = { path, 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: "redditapis", 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";
+    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(`[reddit-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, tool);
+        if (result?.isError && lastError) {
+          let resolved = null;
+          try { resolved = buildPath(tool.path, args).path; } catch { resolved = null; }
+          // Name the tool only when BOTH method and path match the recorded
+          // failure; a GET and a POST can share a path.
+          if (sameFailure(lastError, resolved, 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 };
+}