redditapis-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.5.0 (2026-09-06)
+
+### Added
+
+- **`reddit_home_feed`, the caller's own front page.** A shared account pool can never answer "what is on MY home feed", so this reads it with your own Reddit session, sent as headers rather than in the URL. Part of the same change that gave nine existing read tools an authenticated mode: send `x-reddit-session` and `x-reddit-loid` and a private, restricted or member-only subreddit is readable as the account that belongs there, instead of coming back empty. Send neither and the read is served anonymously from the pool exactly as before, so existing integrations are untouched.
+- **`reddit_verify_comments`, verify up to a hundred comments in one call.**
+- **`reddit_feedback_list`, find a report whose id you lost.** `GET /feedback` with cursor paging and a type filter, so a report you sent and did not record is still reachable.
+
+### Fixed
+
+- **A foreign-tenant token that `git push` shipped and `npm pack` did not.** The published tarball was clean, so this never reached a customer through npm, but the string was in the repo.
+- The stuck-lock test used the wrong queue-directory env var and wrote to the real home directory instead of its fixture.
+- `send` now releases the queue lock across the network, a 409 carries no hint, and a posted draft fails soft rather than stranding the queue.
+
+### Why a minor rather than a patch
+
+The catalog moved from 38 tools to 41. A client enumerating tools sees three it did not have, which is a capability change, so anyone pinned to 0.4.x opts in rather than receiving it silently.
+
+### Note on the gap this closes
+
+0.4.0 was published on 2026-09-04 and the registry served it unchanged for two days while HEAD moved 50 commits ahead. Because both the registry and the repo said `0.4.0`, every version-based freshness check read clean while the BYTES differed: `src/index.js`, `src/tools.js` and `README.md` all diverged, and customers running `npx redditapis-mcp` were enumerating 38 tools against a repo that shipped 41. Found by `ship-chain.sh`, which compares the published tarball to HEAD file by file rather than comparing version strings.
+
 ## 0.4.0 (2026-09-04)
 
 ### Added

package/README.md

@@ -125,6 +125,9 @@ A few conventions across the catalog:
 | Tool | Endpoint | What it does |
 |---|---|---|
 | `reddit_subreddit_posts` | `GET /api/reddit/posts` | List a subreddit's posts by `sort` (`new`, `hot`, `top`, `rising`, `controversial`, `best`). |
+| `reddit_feedback_list` | `GET /feedback` | List the reports this account has sent, newest first, with their status. The way back to a report whose id was not kept. Free. |
+| `reddit_verify_comments` | `POST /api/reddit/comments/verify` | Check whether up to 100 specific comments still exist and are publicly visible. A read despite the POST; tells 'deleted by author' from 'removed by a mod' from 'still there'. |
+| `reddit_home_feed` | `GET /api/reddit/feed` | Read YOUR OWN Reddit home feed. Needs your `reddit_session` and `loid` from `POST /api/reddit/login` (a REST call, not an MCP tool); they travel as headers, never in the URL. |
 | `reddit_subreddit_top` | `GET /api/reddit/sub/{name}/top` | Top posts of a subreddit for a time window (`t`). |
 | `reddit_subreddit_comments` | `GET /api/reddit/sub/{name}/comments` | Stream the newest comments across an entire subreddit (not one post's thread). |
 | `reddit_subreddit_about` | `GET /api/reddit/sub/{name}/about` | A subreddit's public metadata: title, description, subscriber and active-user counts, type, NSFW flag. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "mcpName": "io.github.redditapis/redditapis-mcp",
   "description": "Official MCP server for redditapis.com, the Reddit API (subreddit listings, post + comment + community + user + media search, comment trees, top posts, user profiles) plus monitor/webhook management (create/list/update/remove a monitor, register/test/delete a webhook, read delivery history) and user-reviewed product feedback to the team as native tools for Claude, Cursor, and any MCP client.",
   "repository": {

package/src/index.js

@@ -26,7 +26,7 @@
 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 } from "./tools.js";
+import { TOOLS, buildQuery, buildPath, buildBody, buildHeaders } from "./tools.js";
 import { createFeedbackHandler, sameFailure } from "./feedback.js";
 
 const API_KEY = process.env.REDDITAPIS_KEY || process.env.REDDIT_APIS_KEY;
@@ -56,8 +56,45 @@ let lastError = null;
 // (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) {
-  const { path, rest } = buildPath(pathTemplate, args);
+  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}` : ""}`;
@@ -66,6 +103,7 @@ async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
     Authorization: `Bearer ${API_KEY}`,
     accept: "application/json",
     "user-agent": `reddit-mcp/${VERSION}`,
+    ...sessionHeaders,
   };
   let requestBody;
   if (isWrite) {
@@ -79,20 +117,7 @@ async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
     const res = await fetch(url, { method, headers, body: requestBody, signal: ctrl.signal });
     const body = await res.text();
     if (!res.ok) {
-      const hint =
-        res.status === 401
-          ? " (invalid or missing API key, verify REDDITAPIS_KEY at https://www.redditapis.com)"
-          : res.status === 402
-            ? " (insufficient credits, top up at https://www.redditapis.com)"
-            : res.status === 403
-              ? " (access forbidden. The subreddit/user may be private, banned, or quarantined)"
-              : res.status === 404
-                ? " (not found. The subreddit, post id, user, or permalink may be wrong or deleted)"
-                : res.status === 429
-                  ? " (rate limited. Wait a few seconds and retry, or reduce request frequency)"
-                  : res.status >= 500
-                    ? " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)"
-                    : "";
+      const hint = hintFor(res.status, path);
       lastError = {
         path,
         method,

package/src/tools.js

@@ -112,6 +112,28 @@ const LISTING_COOKIES = {
   ),
 };
 
+// The SESSION-HEADER form of the same thing, for tools that declare
+// `sessionHeaders: true`. Identical fields, different transport: buildHeaders
+// lifts these onto x-reddit-* headers instead of the query string, because a
+// session cookie in a URL ends up in every log along the path. LISTING_COOKIES
+// above stays as it is; the four tools using it ship with the query form and
+// changing what they put on the wire would be a behaviour change nobody asked
+// for. The REST API accepts both.
+const SESSION_HEADERS_REQUIRED = {
+  reddit_session: z.string().min(1).describe(
+    "Your Reddit `reddit_session` cookie, from POST /api/reddit/login on the REST API (not an MCP tool). Sent as a header, never in the URL. Required.",
+  ),
+  loid: z.string().min(1).describe(
+    "Your Reddit `loid` cookie, from the same login response. Required, and must be sent together with reddit_session.",
+  ),
+  token_v2: z.string().optional().describe(
+    "Your Reddit `token_v2` cookie, from the same login response. Optional.",
+  ),
+  proxy: z.string().optional().describe(
+    "Optional proxy this read egresses through, so the request reaches Reddit from the IP this account normally acts from. http://user:pass@host:port or host:port. Pinned across retries.",
+  ),
+};
+
 // ── monitoring filter_spec fragments, shared by monitor_add and monitor_update ──
 // v1 is SUBREDDIT-SCOPED ONLY (all-Reddit keyword monitoring is not available),
 // matching apps/api/src/lib/monitor-filter.js's own validation exactly, so a
@@ -211,6 +233,34 @@ export const TOOLS = [
       ...LIMIT,
     },
   },
+  {
+    name: "reddit_verify_comments",
+    path: "/api/reddit/comments/verify",
+    method: "POST",
+    description:
+      "Check whether specific Reddit comments still EXIST and are publicly visible, in one batch of up to 100 ids. A READ despite being a POST (ids travel in the body because a hundred of them do not fit in a URL); it costs the same as any other read and changes nothing on Reddit. Use it to tell 'deleted by the author' from 'removed by a moderator' from 'still there', which a normal comment fetch cannot distinguish, and to re-check a list of comments you posted or collected earlier. Accepts bare ids and t1_-prefixed fullnames interchangeably. Returns one row per id, in the order you sent them, each with a status. Example: ids=['n5abcde','t1_n5fghij'].",
+    shape: {
+      ids: z.array(z.string().min(1)).min(1).max(100).describe(
+        "Comment ids to check, 1 to 100 per call. Bare id ('n5abcde') or fullname ('t1_n5abcde'), mixed freely. Reddit's own batch lookup caps at 100; split larger lists across calls. Required.",
+      ),
+    },
+  },
+  {
+    name: "reddit_home_feed",
+    path: "/api/reddit/feed",
+    sessionHeaders: true,
+    description:
+      "Read YOUR OWN Reddit home feed, the front page your subscriptions produce. Every other read tool here is served from a shared pool of accounts, so it cannot answer 'what is on my feed' -- this one sends your session instead. REQUIRES your own Reddit session: call POST /api/reddit/login on the REST API first (not an MCP tool) and pass the `reddit_session` and `loid` cookies it returns. Without them this returns 400, deliberately, because Reddit's logged-out front page is a different feed belonging to nobody rather than a thinner version of yours. Same post shape and `after` cursor as reddit_subreddit_posts. For a PUBLIC community feed use reddit_subreddit_posts instead. Example: sort='best' limit=25.",
+    shape: {
+      ...SESSION_HEADERS_REQUIRED,
+      sort: z.enum(["best", "hot", "new", "top", "rising", "controversial"]).optional().describe(
+        "Feed sort. 'best' (default) is Reddit's own logged-in home sort. 'top'/'controversial' also take `t`.",
+      ),
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
   {
     name: "reddit_search",
     path: "/api/reddit/search",
@@ -692,6 +742,26 @@ export const TOOLS = [
       ),
     },
   },
+  {
+    name: "reddit_feedback_list",
+    path: "/feedback",
+    description:
+      "List the feedback reports this account has sent, newest first, with each one's current status. Use it to RECOVER A LOST ID: the server id is returned only once, when a report is sent, so this is the way back to a report whose id was not kept. Also the way to answer \"did that report actually land\" and \"has the team looked at it yet\". Optionally filter by status or type, and page with the cursor from a previous response. Free per call, never metered. Returns {feedback: [...], count, limit, next_cursor}; page by passing next_cursor back as cursor until it is null; an account that has filed nothing gets an empty list and a 200, not an error. Note this lists SENT reports on the server, which is different from reddit_feedback_send action=\"list\", which shows unsent local drafts on this machine.",
+    shape: {
+      status: z.enum(["new", "triaged", "shipped", "declined"]).optional().describe(
+        "Optional. Show only reports in this state. Omit for all of them.",
+      ),
+      type: z.enum(["bug", "idea", "missing_capability"]).optional().describe(
+        "Optional. Show only reports of this kind. Omit for all of them.",
+      ),
+      cursor: z.string().optional().describe(
+        "Optional. The next_cursor from a previous response, to fetch the page after it. Keyset paging on (created_at, id), so a report filed while you page cannot make a row repeat or be skipped. A cursor this endpoint did not issue is a 400, never an empty page.",
+      ),
+      limit: z.number().int().min(1).max(100).optional().describe(
+        "Optional. How many to return, 1 to 100 (default 25). Newest first.",
+      ),
+    },
+  },
   {
     name: "reddit_feedback_get",
     path: "/feedback/{id}",
@@ -706,6 +776,55 @@ export const TOOLS = [
 ];
 
 // Turn tool args into a URL query string. Skips undefined/null/empty values.
+// ── the session HEADER transport ────────────────────────────────────────────
+//
+// A GET tool's args normally become the query string. A Reddit session cookie
+// must not: it grants full control of that account and a query string is
+// written into every access log, proxy log and browser history along the path.
+// So a tool that declares `sessionHeaders: true` has these arg names lifted OUT
+// of the query and sent as headers instead.
+//
+// The four legacy private listings (upvoted/saved/hidden/gilded) deliberately
+// do NOT declare it: they have always sent cookies as query fields, the REST
+// API still honours that form, and changing what a shipped tool puts on the
+// wire is a behaviour change nobody asked for. New tools use headers.
+export const SESSION_ARG_TO_HEADER = {
+  reddit_session: "x-reddit-session",
+  loid: "x-reddit-loid",
+  token_v2: "x-reddit-token-v2",
+  csrf_token: "x-reddit-csrf-token",
+  edgebucket: "x-reddit-edgebucket",
+  csv: "x-reddit-csv",
+  session_tracker: "x-reddit-session-tracker",
+  pc: "x-reddit-pc",
+  proxy: "x-reddit-proxy",
+};
+
+/**
+ * Split a tool's args into headers and everything else.
+ *
+ * Returns { headers, rest }. When the tool does not declare `sessionHeaders`
+ * this is the identity: `headers` is empty and `rest` is the args unchanged, so
+ * every existing tool builds exactly the request it built before.
+ */
+export function buildHeaders(tool, args) {
+  const headers = {};
+  const rest = {};
+  const lift = tool && tool.sessionHeaders;
+  for (const [k, v] of Object.entries(args || {})) {
+    const header = lift ? SESSION_ARG_TO_HEADER[k] : null;
+    if (header && v !== undefined && v !== null && String(v).length > 0) {
+      headers[header] = String(v);
+    } else if (!header) {
+      rest[k] = v;
+    }
+    // A declared session field that is empty is dropped rather than sent as an
+    // empty header: an empty x-reddit-session would read as "authenticate me"
+    // and earn a 400 instead of the anonymous read the caller meant.
+  }
+  return { headers, rest };
+}
+
 export function buildQuery(args) {
   const qs = new URLSearchParams();
   for (const [k, v] of Object.entries(args || {})) {