redditapis-mcp 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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.2.0
 - **10 new monitor/webhook management tools** (task #43), the first WRITES this
   catalog has ever carried. Unlike the reddit comment/vote/DM writes this MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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.",
   "repository": {
@@ -18,7 +18,8 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "smithery.yaml"
+    "smithery.yaml",
+    "server.json"
   ],
   "engines": {
     "node": ">=18"

package/server.json

@@ -0,0 +1,30 @@
+{
+  "$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.1",
+  "websiteUrl": "https://www.redditapis.com",
+  "repository": {
+    "url": "https://github.com/redditapis/redditapis-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "redditapis-mcp",
+      "version": "0.3.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "REDDITAPIS_KEY",
+          "description": "Your redditapis.com API key. Get one at https://www.redditapis.com",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}

package/src/index.js

@@ -33,11 +33,19 @@ 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.",
+    "[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.",
   );
-  process.exit(1);
 }
 
 // REST call. Resolves any {param} path placeholders from args, and for GET
@@ -46,6 +54,15 @@ if (!API_KEY) {
 // `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);

package/src/tools.js

@@ -126,6 +126,12 @@ const MONITOR_SUBREDDIT = {
   subreddit: z.array(z.string().min(1)).min(1).max(50).optional().describe(MONITOR_SUBREDDIT_DESC),
 };
 const MONITOR_FILTER_FIELDS = {
+  // SITEWIDE ONLY BY DESIGN, and the description says so in the first clause
+  // because an agent that passes it alongside `subreddit` gets a 400 and needs
+  // to know from the schema, not from the error, which of the two to drop.
+  exclude_subreddits: z.array(z.string().min(1)).max(50).optional().describe(
+    "Subreddits to SUPPRESS, without the r/ prefix (e.g. ['politics', 'AskReddit']). SITEWIDE MONITORS ONLY: pass this only when you have OMITTED `subreddit` and anchored the monitor with `q`. Passing it together with `subreddit` is rejected with a field-level 400 -- a monitor that names its subreddits should drop the unwanted name from that list instead. Up to 50, matched exactly like `subreddit` so 'r/Politics', '/r/politics' and 'politics' are one entry. This is the noise control for an all-of-Reddit keyword watch: it filters DELIVERY only, so it never changes what is polled, never frees quota, and never affects matching in any other subreddit. Independent of exclude_terms -- an item is dropped if either fires.",
+  ),
   q: z.string().max(200).optional().describe(
     "Free-text keyword or phrase to match. Matched against the fields in `search_in` (default title+body+url). Omit to match every new post in the watched subreddits.",
   ),
@@ -519,7 +525,7 @@ export const TOOLS = [
     path: "/api/reddit/monitor/add",
     method: "POST",
     write: true,
-    filterSpecFields: ["subreddit", "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", "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: {
@@ -546,7 +552,7 @@ export const TOOLS = [
     path: "/api/reddit/monitor/update",
     method: "POST",
     write: true,
-    filterSpecFields: ["subreddit", "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", "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: {