redditapis-mcp 0.7.0 → 0.8.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.7.0",
+  "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,7 +31,7 @@
   "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 && node test/per-caller-state.test.mjs && node test/paywall.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": {

package/src/server.js

@@ -157,6 +157,14 @@ export const INSTRUCTIONS =
  *                                         (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,
@@ -164,6 +172,9 @@ export function createServer({
   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;
@@ -185,7 +196,7 @@ export function createServer({
     // 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) return paywallResult("no_key");
+    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
@@ -196,7 +207,7 @@ export function createServer({
     const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
 
     const headers = {
-      Authorization: `Bearer ${apiKey}`,
+      ...(authHeaders ? authHeaders : { Authorization: `Bearer ${apiKey}` }),
       accept: "application/json",
       "user-agent": `reddit-mcp/${VERSION}`,
       ...sessionHeaders,
@@ -207,11 +218,34 @@ export function createServer({
       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 = {
@@ -242,12 +276,21 @@ export function createServer({
       lastError = null;
       return { content: [{ type: "text", text: body }] };
     } catch (err) {
-      const msg = err?.name === "AbortError" ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : err?.message || String(err);
+      if (!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 });