redditapis-mcp 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,53 +1,21 @@
 # Changelog
 
-## 0.3.2
-- **Security: 10 Dependabot alerts closed (3 high, 6 moderate, 1 low)**, all in
-  transitive dependencies pulled in by `@modelcontextprotocol/sdk` (never a
-  direct dependency of this package): `hono` (SSR output cross-user
-  disclosure, ReDoS in CORS/language middleware, header handling in the proxy
-  helper), `fast-uri` (host confusion via a backslash authority delimiter),
-  `ip-address` (three separate SSRF/trust-boundary bypasses via octal,
-  IPv4-mapped, and CIDR-suffix address confusion), and `@hono/node-server`
-  (path traversal on Windows). Fixed by a clean reinstall against the
-  existing `@modelcontextprotocol/sdk: ^1.0.0` range, which already permitted
-  the patched versions; no version constraint changed, only the resolved
-  tree (SDK 1.29.0 to 1.30.0, hono to 4.13.2, fast-uri to 3.1.5, ip-address
-  to 10.5.0, @hono/node-server to 2.1.1). This server only imports the SDK's
-  stdio transport (confirmed: `src/index.js` never imports `hono` or the
-  SDK's HTTP transport), so `hono` and `@hono/node-server` never load at
-  runtime here; `fast-uri` and `ip-address` sit deeper in the SDK's own
-  dependency tree and were not individually traced. Fixed regardless, since
-  Dependabot flags them independent of reachability and a clean scan is
-  the point.
-
-## 0.3.1
-- **Fix: the server no longer exits at startup when `REDDITAPIS_KEY` is missing.**
-  A registry connectivity scanner (Smithery, Glama, the official MCP registry,
-  Claude Connectors Directory) spins up the server with no real credential to
-  enumerate `tools/list`. Exiting before the transport connects made every
-  automated scan fail outright and read as a generic connectivity error rather
-  than a missing-key error, which is most of why this listing scored low on
-  every registry's capability-quality checks. Tools now register and
-  `tools/list` responds regardless of whether a key is present; an actual tool
-  call with no key still fails clearly, at the point of the call, with the
-  same style of message the existing 401 branch already used.
-- Adds `server.json` (official MCP server manifest: description, homepage,
-  repository, npm package identifier, and the `REDDITAPIS_KEY` config field
-  with a title and description) to the repo and to the published package, so
-  registry submissions have a durable, versioned source instead of a local,
-  never-committed file.
-
-## 0.3.0
-- 4 new READ tools for the caller's own private Reddit listings (upvoted,
-  saved, hidden, gilded), each requiring the caller's own Reddit session
-  cookie obtained via `POST /api/reddit/login`.
-- Pagination docs clarified across every listing tool: `listing_status` on the
-  final page distinguishes `complete` (nothing missing) from `truncated`/
-  `unknown` (Reddit stopped serving a busy listing early), so a client no
-  longer reads a null `after` cursor as proof of a complete result set.
-- This CHANGELOG entry is retroactive; 0.3.0 published without one, along with
-  drifting one npm publish ahead of what GitHub had committed. Both are
-  corrected as part of the 0.3.1 pass.
+## 0.4.0 (2026-09-04)
+
+### Added
+
+- **`reddit_feedback_send` and `reddit_feedback_get`, report a bug or a gap to the redditapis.com team from inside the session you are already in.** Modelled on Claude Code's own feedback tool: the model drafts a report at a high-signal moment (a call failed in a way that is not your key, credits or a rate limit and you had to work around it; you asked for something no tool covers; a documented field came back empty or wrong; you were plainly frustrated with a result) into a local queue at `~/.redditapis/feedback-queue.json` (override with `REDDITAPIS_FEEDBACK_DIR`, at most 10 drafts), and nothing is sent until you review the queue and name the drafts to send. Each draft carries the last failing call's endpoint, status and request id, your MCP client's name and this package's version, filled in automatically, so a report is actionable without a follow-up. `reddit_feedback_send` takes `action` (`draft`, `list`, `send`, `discard`); `reddit_feedback_get` reads a sent report's status and the team's response. Both are free and need only your API key. The trigger list also ships as the server's MCP `instructions`, so a client that honours them nudges its model at the right moments, and every non-credential error body (anything but 401/402/429) now ends with a one-line pointer to the tool. This takes the catalog to 38 tools (34 documented in the table above plus the 4 cookie-authenticated user-history reads).
+- **Catalog support for local handlers.** A tool may declare `local: "<handler>"` in `src/tools.js` and name its local-only args in `localArgs`; those args are consumed in this package and never sent to the API. `src/index.js` refuses to boot if a catalog entry names a handler it does not implement, and the catalog test pins that every `localArgs` entry is a real key of the tool's shape, so neither flag can turn into a silent passthrough.
+
+### Fixed
+
+- `test/smoke.mjs` asserted a tool count of 32 against a catalog of 36; it now derives the expected count from the catalog it lists.
+
+## 0.3.0 (2026-08-16)
+
+### Added
+
+- **`exclude_subreddits` and `exclude_terms` on `reddit_monitor_add` and `reddit_monitor_update`.** Per-monitor subreddit exclusion for sitewide keyword watches, and term exclusion for every monitor. Published as a minor rather than a patch because a real capability was added; anyone pinned to 0.2.x opts in rather than receiving it silently. (This entry was written retroactively on 2026-09-04: the version shipped with no changelog line.)
 
 ## 0.2.0
 - **10 new monitor/webhook management tools** (task #43), the first WRITES this

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/redditapis-mcp)](https://www.npmjs.com/package/redditapis-mcp)
 [![license](https://img.shields.io/npm/l/redditapis-mcp)](./LICENSE)
 
-Official **Model Context Protocol** server for [redditapis.com](https://www.redditapis.com), the Reddit API as native tools for Claude, Cursor, Windsurf, and any MCP client. It turns Reddit reads (search, subreddit listings, comment trees, user profiles, community metadata) into typed tools your agent can call directly, plus (since 0.2.0) managing your own redditapis.com monitors and webhooks.
+Official **Model Context Protocol** server for [redditapis.com](https://www.redditapis.com), the Reddit API as native tools for Claude, Cursor, Windsurf, and any MCP client. It turns Reddit reads (search, subreddit listings, comment trees, user profiles, community metadata) into typed tools your agent can call directly, plus (since 0.2.0) managing your own redditapis.com monitors and webhooks, and (since 0.4.0) sending the team product feedback the agent drafted and you reviewed.
 
 Ask your agent to search Reddit for a topic, read a community's top posts of the week, pull a user's comment history, surface the redditors talking about a product, or read a subreddit's rules before you engage, and it calls the API for you. It can also set up a monitor that watches a subreddit for new posts matching a filter and delivers them to a webhook, then check what it's actually delivered. Every tool maps to a REST endpoint at `https://api.redditapis.com`; the server holds no state and forwards your API key on each call.
 
@@ -94,12 +94,13 @@ claude mcp add reddit --env REDDITAPIS_KEY=YOUR_API_KEY -- npx -y redditapis-mcp
 | `REDDITAPIS_KEY` | Yes | (none) | API key from [redditapis.com](https://www.redditapis.com). `REDDIT_APIS_KEY` is accepted as an alias. |
 | `REDDITAPIS_BASE_URL` | No | `https://api.redditapis.com` | Override the API host. |
 | `REDDITAPIS_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds. |
+| `REDDITAPIS_FEEDBACK_DIR` | No | `~/.redditapis` | Where `reddit_feedback_send` keeps its local draft queue (`feedback-queue.json`). |
 
 Authentication is a Bearer token: the server sends `Authorization: Bearer <REDDITAPIS_KEY>` on every request.
 
 ## Tools
 
-32 tools: 22 reads plus 10 monitor/webhook management tools. Reddit writes (posting, commenting, voting, DMs) remain a separate authenticated surface and are intentionally out of scope here -- monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below).
+34 tools: 22 reads, 10 monitor/webhook management tools, and 2 feedback tools. Reddit writes (posting, commenting, voting, DMs) remain a separate authenticated surface and are intentionally out of scope here -- monitor/webhook tools configure your OWN redditapis.com account (an alerting subscription), never Reddit itself, and the feedback tools send a report to the redditapis.com team, never to Reddit. Every read works with just your API key; the 6 monitor/webhook writes additionally need an active monitoring plan (see Monitoring below). The feedback tools are free and need only your key.
 
 A few conventions across the catalog:
 
@@ -172,6 +173,15 @@ v1 monitors are **subreddit-scoped, posts-only** (no all-of-Reddit keyword watch
 | `reddit_monitor_webhook_test` | `POST /api/reddit/monitor/webhook/test` | Send a one-off test delivery to confirm a webhook is wired up correctly. |
 | `reddit_monitor_webhook_delete` | `POST /api/reddit/monitor/webhook/delete` | Permanently delete a webhook. Does not cascade-pause monitors still pointing at it. |
 
+### Feedback: tell the team what broke, after you review the draft
+
+Modelled on Claude Code's own feedback tool. When a call fails in a way that is not your key, credits or a rate limit, when you ask for something no tool covers, or when a result is plainly wrong, the model can **draft** a report into a local queue (`~/.redditapis/feedback-queue.json`, at most 10 drafts, override the directory with `REDDITAPIS_FEEDBACK_DIR`). Nothing is sent until you ask to review the queue and name the drafts to send. Each report carries the last failing call's endpoint, status and request id, your client name and this package's version, so the team can act on it without a follow-up. Use `reddit_feedback_get` with the returned server id to see whether it was triaged, shipped or declined. Both tools are free.
+
+| Tool | Endpoint | What it does |
+|------|----------|--------------|
+| `reddit_feedback_send` | `POST /feedback` | `action: "draft"` (default) queues a report locally and sends nothing; `"list"` shows the queue; `"send"` posts only the drafts you name; `"discard"` drops them. |
+| `reddit_feedback_get` | `GET /feedback/{id}` | Read a sent report's status (`new`, `triaged`, `shipped`, `declined`) and the team's response. |
+
 ## Usage examples
 
 ### Research a topic across Reddit

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.3.2",
+  "version": "0.4.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) as native tools for Claude, Cursor, and any MCP client.",
+  "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": {
     "type": "git",
     "url": "git+https://github.com/redditapis/redditapis-mcp.git"
@@ -18,16 +18,15 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "smithery.yaml",
-    "server.json"
+    "smithery.yaml"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "start": "node src/index.js",
-    "check": "node --check src/index.js && node --check src/tools.js",
-    "test": "node test/tools.test.mjs",
+    "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",
     "prepublishOnly": "node scripts/prepublish-tenant-check.mjs"
   },
   "dependencies": {

package/src/feedback.js

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

package/src/index.js

@@ -3,18 +3,23 @@
 //
 // Exposes the Reddit API as native MCP tools for Claude, Cursor, and any MCP
 // client: subreddit listings, post + comment search, community/user/media/comment
-// search, a post's comment tree, subreddit top posts, user profile/comments, and
+// search, a post's comment tree, subreddit top posts, user profile/comments,
 // (since 0.2.0) managing your own redditapis.com monitors and webhooks -- create/
 // list/update/remove a monitor, register/list/test/delete a webhook, and read
-// delivery history. Each tool is a thin, typed wrapper over a REST endpoint at
-// https://api.redditapis.com. The server holds no state and forwards your API
-// key on every call. The tool catalog lives in ./tools.js.
+// delivery history -- and (since 0.4.0) sending the team product feedback the
+// 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.
 //
 // Config (env):
 //   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
 //   REDDITAPIS_TIMEOUT_MS optional. Per-request timeout (default 30000)
+//   REDDITAPIS_FEEDBACK_DIR optional. Where reddit_feedback_send keeps its
+//                         local draft queue (default ~/.redditapis)
 //
 // Run:  npx -y redditapis-mcp@latest   (stdio transport)
 
@@ -22,6 +27,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 { createFeedbackHandler, sameFailure } from "./feedback.js";
 
 const API_KEY = process.env.REDDITAPIS_KEY || process.env.REDDIT_APIS_KEY;
 const BASE_URL = (
@@ -33,36 +39,24 @@ const REQUEST_TIMEOUT_MS = Number(process.env.REDDITAPIS_TIMEOUT_MS || 30000);
 // User-Agent and MCP server handshake understated its own version for months.
 const { version: VERSION } = createRequire(import.meta.url)("../package.json");
 
-// Lazy validation, not exit-on-boot: an MCP registry scanner (Smithery, Glama,
-// the official registry, Claude Connectors) connects the stdio transport with
-// no real credential to enumerate tools/list. Exiting here before the server
-// ever registers a tool makes that handshake fail outright and reads as a
-// generic connectivity error, not a missing-key error, on the scanner side --
-// confirmed live 2026-08-18 (Smithery: "Initialization failed... could not be
-// automatically scanned", HTTP 404). 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).
 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.",
+    "[reddit-mcp] Missing REDDITAPIS_KEY. Get a key at https://www.redditapis.com and set it in your MCP client config.",
   );
+  process.exit(1);
 }
 
+// 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).
 async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
-  if (!API_KEY) {
-    return {
-      isError: true,
-      content: [{
-        type: "text",
-        text: "Missing REDDITAPIS_KEY (invalid or missing API key, get one at https://www.redditapis.com and set it in your MCP client config).",
-      }],
-    };
-  }
   const { path, rest } = buildPath(pathTemplate, args);
   const isWrite = method !== "GET";
   const q = isWrite ? "" : buildQuery(rest);
@@ -99,18 +93,59 @@ async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
                   : res.status >= 500
                     ? " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)"
                     : "";
-      return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}` }] };
+      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);
   }
 }
 
-const server = new McpServer({ name: "redditapis", version: VERSION });
+// Standing instructions the client hands its model alongside the tool list.
+// This is the trigger list for feedback, in the place a model actually reads.
+const INSTRUCTIONS =
+  "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\".";
+
+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";
@@ -120,10 +155,27 @@ for (const tool of TOOLS) {
     destructiveHint: Boolean(tool.destructive),
     openWorldHint: true,
   };
+  let handler;
+  if (tool.local) {
+    handler = LOCAL_HANDLERS[tool.local];
+    if (!handler) throw new Error(`[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 },
-    async (args) => callEndpoint(tool.path, args, method, tool),
+    handler,
   );
 }
 

package/src/tools.js

@@ -21,6 +21,20 @@
 // a query string (see buildBody below). `filterSpecFields` on a tool declares
 // which of its args nest under `filter_spec` in that body; everything else in
 // `shape` stays top-level (id, cadence_s, active, url, kind, ...).
+//
+// LOCAL TOOLS (2026-09-04): a tool carrying `local: "<handler>"` is dispatched
+// by index.js to a handler in this package instead of straight to the API.
+// Args flagged in `localArgs` are consumed locally and never sent. Today the
+// only such tool is reddit_feedback_send, whose draft queue lives on disk in
+// src/feedback.js and whose POST to /feedback happens only on the user's say.
+// index.js refuses to boot if a catalog entry names a handler it lacks, so a
+// `local` tag can never turn into a silent passthrough with the local args
+// attached.
+//
+// PUBLIC MOUNTS: every tool path is under /api/reddit/ EXCEPT the feedback
+// pair, which the API serves un-prefixed (api.redditapis.com/feedback) because
+// it is mounted outside the metered /api surface, like /account. The catalog
+// test pins the allowed prefixes so a typo cannot invent a third one.
 import { z } from "zod";
 
 // Shared Zod input-schema fragments.
@@ -158,6 +172,9 @@ const MONITOR_FILTER_FIELDS = {
     "What to watch in the named subreddits: 'post' (default when omitted), 'comment', or 'both'. Comment monitoring requires a Growth, Pro or Scale plan -- on a lower tier this returns `comment_monitoring_requires_higher_tier` (402). Comments run roughly 7x the volume of posts, so expect proportionally more deliveries and check reddit_monitor_health's delivery ceiling before enabling it on a busy subreddit.",
   ),
   min_score: z.number().int().optional().describe("Only match posts with at least this many upvotes."),
+  min_relevance: z.number().int().min(0).max(100).optional().describe(
+    "AI relevance floor, 0-100. 0 (the default) is off. Above 0, every match is scored by a language model against this monitor's own keywords and anything below the floor is NOT delivered -- it is recorded in your delivery history with status 'suppressed' and reason 'low_relevance', carrying its score and a one-line explanation, so you can always read what was filtered and why. Nothing is silently discarded. Rough calibration: 80-100 squarely on topic, 50-79 related but peripheral, 20-49 tangential, 0-19 the keyword is used in an unrelated sense. The comparison is inclusive, so a score equal to the floor is delivered. If scoring is unavailable the match is delivered UNSCORED rather than withheld. Requires a Growth, Pro or Scale plan -- on a lower tier this returns `ai_relevance_requires_higher_tier` (402). REJECTED with a field-level 400 on a monitor that has no q, include_any or include_all, because there would be no topic to score an item against and the floor could only ever admit everything.",
+  ),
   nsfw: z.boolean().optional().describe("Set false to EXCLUDE NSFW/over-18 posts. Omitted or true both mean NSFW is allowed through -- there is no exclude-by-default; you must explicitly pass false to filter it out. POSTS ONLY: nsfw=false is REJECTED with a field-level 400 when kind is 'comment' or 'both', because Reddit flags NSFW on a post and never on an individual comment, so there is no field to filter a comment on. Run a kind='post' monitor to keep NSFW filtering, and cut unwanted comment text with exclude_terms."),
 };
 // Per-monitor webhook targeting (task #66, migration 009). NOT a filter_spec
@@ -525,7 +542,7 @@ export const TOOLS = [
     path: "/api/reddit/monitor/add",
     method: "POST",
     write: true,
-    filterSpecFields: ["subreddit", "exclude_subreddits", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "nsfw"],
+    filterSpecFields: ["subreddit", "exclude_subreddits", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "min_relevance", "nsfw"],
     description:
       "Create a new Reddit monitor: watch one or more subreddits, or ALL of Reddit, for new posts (or comments, via `kind`) matching a filter, and get every match delivered to a webhook you've registered with reddit_monitor_webhook_create. Omit `subreddit` and set `q` for a sitewide keyword monitor covering every subreddit at once (posts only). By default matches go to EVERY active webhook on your account; pass `webhook_ids` to route this monitor's matches to only specific webhook(s). Every redditapis.com account holds a free entitlement of ONE all-of-Reddit post watch at a 60s cadence (up to 10,000 deliveries a day), so no subscription is needed to create that monitor. Naming a `subreddit`, matching comments, a faster cadence and any additional watch require a paid plan. Needs at least one monitor slot free (see reddit_monitor_list's `slots`). Forward-looking only from the moment of creation, or from `baseline_item_id` if given -- it never backfills posts that already existed. Returns the created monitor (with its `id`) on success, or `subscription_required` (402) if the account holds no recognised entitlement at all, `subreddit_scope_requires_paid_plan` (402) if a free account named a `subreddit`, `monitor_slots_exhausted` (402) if the plan's slot limit is reached, `sitewide_slots_exhausted` (402) if the plan's separate sitewide cap is reached, `distinct_subreddit_limit_reached` (402) if the account already watches as many DIFFERENT subreddits as the plan covers (the limit counts distinct subreddits across all your monitors, not monitors, and the same subreddit in two monitors counts once; see reddit_monitor_list's `slots.distinct_subreddits_total`), `sitewide_comment_monitoring_not_available` (501) if a sitewide monitor asks for comments, `subreddit_reserved` (400) if `subreddit` names 'all', `subreddit_not_found` (400) if a named subreddit does not exist, or `webhook_not_found` (400) if a `webhook_ids` entry is not yours.",
     shape: {
@@ -552,7 +569,7 @@ export const TOOLS = [
     path: "/api/reddit/monitor/update",
     method: "POST",
     write: true,
-    filterSpecFields: ["subreddit", "exclude_subreddits", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "nsfw"],
+    filterSpecFields: ["subreddit", "exclude_subreddits", "kind", "q", "author", "exclude_terms", "domain", "include_any", "include_all", "search_in", "group", "min_score", "min_relevance", "nsfw"],
     description:
       "Update an existing monitor: pause/resume it (`active`), change its poll interval (`cadence_s`), switch between posts and comments (`kind`), replace its filter entirely, or re-target which webhook(s) it delivers to (`webhook_ids`). IMPORTANT: if you pass ANY filter field (subreddit, q, kind, domain, etc.), it REPLACES the whole filter, it does not merge with the existing one -- resupply every field you want kept, including `subreddit` AND `kind` (omitting `kind` reverts that monitor to posts-only). Same rule for `webhook_ids`: passing it REPLACES the monitor's targeting outright (an empty array clears back to 'every active webhook'); omitting it entirely leaves the monitor's existing targeting untouched. Omit all filter/webhook_ids fields to change only `active`/`cadence_s`. Returns 404 `monitor_not_found` if the id does not exist or is not yours, or 400 `webhook_not_found` if a `webhook_ids` entry is not yours.",
     shape: {
@@ -590,7 +607,7 @@ export const TOOLS = [
     name: "reddit_monitor_deliveries",
     path: "/api/reddit/monitor/deliveries",
     description:
-      "Delivery history: the actual Reddit posts a monitor's webhook has received (or attempted), newest first, including the real post content (title, subreddit, permalink, author). Answers 'what did I actually get sent', not just 'how many' (see reddit_monitor_health for counts). Omit `id` to aggregate history across every monitor you own.",
+      "Delivery history: the actual Reddit posts a monitor's webhook has received (or attempted), newest first, including the real post content (title, subreddit, permalink, author). Answers 'what did I actually get sent', not just 'how many' (see reddit_monitor_health for counts). Every delivered item also carries `payload.items[].enrichment`: a `relevance.score` (0-1, how much of THIS monitor's own keyword criteria the item matched -- not a model's confidence), a `sentiment` (`polarity` -1 to 1 plus a positive/negative/mixed/neutral `label`), and an `intent.tag` (question, recommendation_request, complaint, promotion, praise, or discussion). All three are deterministic keyword/lexicon/rule heuristics computed at no extra cost -- each carries its own `method` field and NONE of them is a machine-learning or LLM call, so do not describe a score here as ML-derived. Omit `id` to aggregate history across every monitor you own.",
     shape: {
       id: z.string().optional().describe("Narrow to one monitor's history. Omit to aggregate across every monitor you own."),
       status: z.enum(["pending", "delivered", "failed", "dead", "suppressed"]).optional().describe(
@@ -639,6 +656,53 @@ export const TOOLS = [
       "Permanently delete a webhook. Any monitor still pointing at it will fail to deliver until repointed at a different webhook -- this does NOT cascade-delete or pause the monitors using it. Cannot be undone. Returns 404 `webhook_not_found` if the id does not exist or is not yours.",
     shape: { ...WEBHOOK_ID },
   },
+
+  // ── feedback: report a defect or a gap to the redditapis.com team, with the
+  //    user's review between the draft and the send ─────────────────────────
+  {
+    name: "reddit_feedback_send",
+    path: "/feedback",
+    method: "POST",
+    write: true,
+    local: "feedback",
+    localArgs: ["action", "ids"],
+    description:
+      "Report a product problem or gap in redditapis.com to its team from inside this session, the way Claude Code's own feedback tool works: a report is DRAFTED to a local queue first (action \"draft\", the default) and SENT only after the user reviews it. Drafting sends nothing, needs no confirmation, and should not be announced mid-task. WHEN TO DRAFT, only at high-signal moments: a redditapis tool call failed with an error that was not a missing key (401), credits (402) or a rate limit (429), and the user had to work around it; the user asked for something no redditapis tool covers; a documented field came back empty or wrong; the user was clearly frustrated with a result. One draft per distinct issue, never twice for the same one. FORMAT for details, four labelled bullets in this order: 'What happened:' observed vs expected, exact error text if short. 'What the user said:' quoted verbatim, or 'user did not comment'. 'Repro:' the minimal call that reproduces it. 'Evidence:' tool name, endpoint, HTTP status, request id (the last failing call is attached automatically where you leave a gap). Facts only: no guessing, no API keys or secrets, no personal names. REVIEW: when the user asks to see or send feedback, call action \"list\", then action \"send\" with ONLY the draft ids the user named in their own message, or action \"discard\". Sending posts each draft to POST /feedback (free, not metered) and returns a server id that reddit_feedback_get can check later.",
+    shape: {
+      action: z.enum(["draft", "list", "send", "discard"]).optional().describe(
+        "What to do. \"draft\" (default) queues a new report locally and sends nothing. \"list\" shows the pending drafts with their ids. \"send\" posts the drafts named in ids to redditapis.com; use it only for ids the user named. \"discard\" drops the drafts named in ids.",
+      ),
+      type: z.enum(["bug", "idea", "missing_capability"]).optional().describe(
+        "Required for a draft. \"bug\": a tool or endpoint misbehaved. \"idea\": a change that would have made the task easier. \"missing_capability\": the user needed something no tool provides.",
+      ),
+      title: z.string().max(120).optional().describe(
+        "Required for a draft. One specific line, at most 120 characters, naming the tool or endpoint and the defect, e.g. \"reddit_post_comments returns 502 when the post is deleted\".",
+      ),
+      details: z.string().max(8000).optional().describe(
+        "Required for a draft. At most 8000 characters, four labelled bullets in order: What happened, What the user said (verbatim), Repro, Evidence.",
+      ),
+      area: z.string().max(80).optional().describe(
+        "Optional. The endpoint or feature the report is about, e.g. \"posts/comments\" or \"monitoring\". At most 80 characters.",
+      ),
+      evidence: z.record(z.string(), z.unknown()).optional().describe(
+        "Optional identifiers only, never payloads: {tool, endpoint, status, request_id}. Whatever you leave out is filled from the last failing call in this session; mcp_version and client are always attached.",
+      ),
+      ids: z.array(z.string()).optional().describe(
+        "For action \"send\" or \"discard\": the draft ids to act on, exactly as shown by action \"list\" and named by the user.",
+      ),
+    },
+  },
+  {
+    name: "reddit_feedback_get",
+    path: "/feedback/{id}",
+    description:
+      "Check the status of a feedback report this account sent earlier (the server id returned by reddit_feedback_send action \"send\"): status new, triaged, shipped or declined, the team's response text if any, and updated_at, which moves only when the team acts on it. Free per call. 404 if the id is not on this account.",
+    shape: {
+      id: z.string().min(1).describe(
+        "The server id of a sent report, as returned by reddit_feedback_send action \"send\" (a UUID). Not a local draft id.",
+      ),
+    },
+  },
 ];
 
 // Turn tool args into a URL query string. Skips undefined/null/empty values.

package/server.json

@@ -1,30 +0,0 @@
-{
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.redditapis/redditapis-mcp",
-  "description": "Reddit API as MCP tools: search, subreddits, posts, comments, users, monitors, and webhooks.",
-  "title": "RedditAPIs",
-  "version": "0.3.2",
-  "websiteUrl": "https://www.redditapis.com",
-  "repository": {
-    "url": "https://github.com/redditapis/redditapis-mcp",
-    "source": "github"
-  },
-  "packages": [
-    {
-      "registryType": "npm",
-      "identifier": "redditapis-mcp",
-      "version": "0.3.2",
-      "transport": {
-        "type": "stdio"
-      },
-      "environmentVariables": [
-        {
-          "name": "REDDITAPIS_KEY",
-          "description": "Your redditapis.com API key. Get one at https://www.redditapis.com",
-          "isRequired": true,
-          "isSecret": true
-        }
-      ]
-    }
-  ]
-}