redditapis-mcp 0.1.12 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 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
+  still excludes, these configure the caller's OWN redditapis.com account (an
+  alerting subscription), never Reddit itself:
+  - **`reddit_monitor_add`** / **`reddit_monitor_list`** / **`reddit_monitor_update`** /
+    **`reddit_monitor_remove`** — create, list, update (pause/resume/re-filter/
+    re-cadence), and permanently delete a monitor. Requires an active plan to
+    create/update (monitoring has no free tier); reading your own list never does.
+  - **`reddit_monitor_health`** — per-monitor delivered/failed/suppressed counts and
+    whether the delivery ceiling has been hit.
+  - **`reddit_monitor_deliveries`** — the actual Reddit posts a monitor's webhook
+    has received, not just counts (task #47, the feature the operator asked for
+    directly: "can they check which all posts their webhook has received").
+  - **`reddit_monitor_webhook_create`** / **`reddit_monitor_webhook_list`** /
+    **`reddit_monitor_webhook_test`** / **`reddit_monitor_webhook_delete`** —
+    register a delivery target (secret shown once), list registered webhooks
+    (secret never re-shown), send a one-off test delivery, and permanently
+    delete one.
+  - All 10 verified live end to end against production (real create/update/
+    pause/resume/remove/re-add round trips, a real signed test delivery), not
+    just unit-tested against a mock.
+  - `remove`/`webhook_delete` are marked `destructive: true`; every write is
+    `write: true`; every other tool remains a pure, `readOnlyHint: true` read.
+  - Fixed two pre-existing drifts found while touching this file: the reported
+    `VERSION` was hardcoded `"0.1.0"` while the package had shipped up to
+    0.1.12 for months (now read live from package.json, so it can't drift
+    again), and `test/tools.test.mjs` / `test/smoke.mjs` both hardcoded stale
+    tool counts (12 and 11) against an actual catalog of 22 -- neither test
+    file had been updated as the catalog grew.
+  - Brings the tool count to 32 (22 reads + 10 monitor/webhook writes).
+
 ## 0.1.12
 - reddit_search gains advanced filters applied to the returned page (the pullpush
   filter-power model): min_score/max_score, min_comments/max_comments, is_video,

package/README.md

@@ -4,13 +4,13 @@
 [![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.
+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.
 
-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. 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.
+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.
 
 ## Quick start
 
-No install needed. Run with `npx`. You need one thing: an API key from **[redditapis.com](https://www.redditapis.com)**. Reads work with just that key, so there is no account login or session step to set up.
+No install needed. Run with `npx`. You need one thing: an API key from **[redditapis.com](https://www.redditapis.com)**. Reads work with just that key, so there is no account login or session step to set up. Monitor/webhook management additionally requires an active monitoring plan (monitoring has no free tier).
 
 ## Setup
 
@@ -99,7 +99,7 @@ Authentication is a Bearer token: the server sends `Authorization: Bearer <REDDI
 
 ## Tools
 
-22 tools, all reads. This server is **read-only** by design. Reddit writes (posting, commenting, voting, DMs) are a separate authenticated surface and are intentionally out of scope here, so every tool below works with just your API key, with no account login or session step.
+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).
 
 A few conventions across the catalog:
 
@@ -154,6 +154,23 @@ A few conventions across the catalog:
 | `reddit_subreddits_new` | `GET /api/reddit/subreddits/new` | Browse the newest subreddits, most recently created first. |
 | `reddit_subreddits_default` | `GET /api/reddit/subreddits/default` | Browse Reddit's default front-page set of subreddits. |
 
+### Monitoring: manage your own monitors and webhooks
+
+v1 monitors are **subreddit-scoped, posts-only** (no all-of-Reddit keyword watch, no comment monitoring yet). Creating or updating a monitor or webhook needs an active plan; reading your own list/health/deliveries never does.
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `reddit_monitor_add` | `POST /api/reddit/monitor/add` | Create a monitor: subreddits to watch plus an optional filter (keyword, author, domain, include/exclude terms, min score, NSFW). Forward-looking only from creation (or from `baseline_item_id`). |
+| `reddit_monitor_list` | `GET /api/reddit/monitor/list` | List every monitor on your account, plus `slots` ({used, total, tier}). |
+| `reddit_monitor_update` | `POST /api/reddit/monitor/update` | Pause/resume (`active`), re-cadence, or replace a monitor's filter. Passing any filter field REPLACES the whole filter -- resupply everything you want kept. |
+| `reddit_monitor_remove` | `POST /api/reddit/monitor/remove` | Permanently delete a monitor. Cannot be undone. |
+| `reddit_monitor_health` | `GET /api/reddit/monitor/health` | Per-monitor delivered/failed/suppressed counts (last 24h) and whether the delivery ceiling has been hit. |
+| `reddit_monitor_deliveries` | `GET /api/reddit/monitor/deliveries` | The actual posts delivered (or attempted), newest first, with real content -- not just counts. Omit `id` to aggregate across every monitor you own. |
+| `reddit_monitor_webhook_create` | `POST /api/reddit/monitor/webhook/create` | Register a delivery target (`webhook`/`slack`/`discord`). Returns a signing secret shown ONCE. |
+| `reddit_monitor_webhook_list` | `GET /api/reddit/monitor/webhook/list` | List your webhooks. Never returns the secret. |
+| `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. |
+
 ## Usage examples
 
 ### Research a topic across Reddit
@@ -210,15 +227,35 @@ t: "year"
 
 Then `reddit_subreddit_rules` with `{ name: "webdev" }`, and finally `reddit_post_comments` with the `permalink` from a search result, for example `{ permalink: "/r/webdev/comments/abc123/some_title/" }`, to pull the post and its comment tree.
 
-## Reads only, no session needed
+### Set up brand monitoring and check what came in
+
+> "Watch r/SaaS and r/startups for mentions of my product, send matches to my Slack, and show me what's come in so far."
+
+The agent calls `reddit_monitor_webhook_create` with:
+
+```
+url: "https://hooks.slack.com/services/..."
+kind: "slack"
+```
+
+Then `reddit_monitor_add` with:
+
+```
+subreddit: ["SaaS", "startups"]
+q: "my product name"
+```
+
+Later, `reddit_monitor_deliveries` with `{ id: "<monitor id from the add response>" }` returns the actual matching posts sent so far, or `reddit_monitor_health` for just the counts.
+
+## No session needed for reads; monitor/webhook writes need an active plan
 
-Because this server exposes reads and nothing that writes, there is no account linking, login, or cookie step: your API key alone authorizes every call. Reddit write actions (posting, commenting, voting, sending DMs) are handled by a separate authenticated surface outside this package and are deliberately not exposed here, so an agent using this server cannot take an action on any account.
+Reads need nothing but your API key -- no account linking, login, or cookie step. Reddit write actions (posting, commenting, voting, sending DMs) are handled by a separate authenticated surface outside this package and remain deliberately not exposed here, so an agent using this server can never post, vote, or DM as you on Reddit. Monitor/webhook management tools are a different kind of write: they configure your OWN redditapis.com account (an alerting subscription) and require an active monitoring plan for anything that creates or changes state (`reddit_monitor_add`/`update`/`remove`, `reddit_monitor_webhook_create`/`test`/`delete`); reading your own list, health, or delivery history never does.
 
 ## Troubleshooting
 
 **`HTTP 401 (invalid or missing API key)`** Check that `REDDITAPIS_KEY` is set correctly in your MCP client config and matches the key from [redditapis.com](https://www.redditapis.com).
 
-**`HTTP 402 (insufficient credits)`** Top up your account at [redditapis.com](https://www.redditapis.com).
+**`HTTP 402 (insufficient credits)`** Top up your account at [redditapis.com](https://www.redditapis.com). For a monitor/webhook write specifically, a 402 body of `subscription_required` means there is no active monitoring plan (monitoring has no free tier); `monitor_slots_exhausted` means the plan's monitor slot limit is already in use -- `reddit_monitor_list`'s `slots` field shows used vs total.
 
 **`HTTP 403 (access forbidden)`** The subreddit or user may be private, banned, or quarantined, or your plan may not include this endpoint.
 
@@ -248,7 +285,7 @@ npm start       # run the stdio server (needs REDDITAPIS_KEY)
 
 **Do I need a Reddit developer account?** No. Get an API key at [redditapis.com](https://www.redditapis.com); there is no application or approval step.
 
-**Can it post, comment, or vote?** No. This server is read-only. All 22 tools read Reddit; writes are a separate authenticated surface and are not exposed here.
+**Can it post, comment, or vote?** No. All 22 Reddit-facing tools read Reddit; posting, commenting, voting, and DMs are a separate authenticated surface and are not exposed here. The other 10 tools manage your OWN redditapis.com monitors/webhooks, which is a write, but never a write to Reddit itself.
 
 **Which clients are supported?** Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code (Copilot agent mode), or any Model Context Protocol client.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "redditapis-mcp",
-  "version": "0.1.12",
-  "description": "Official MCP server for redditapis.com, the Reddit API (subreddit listings, post + comment + community + user + media search, comment trees, top posts, user profiles) as native tools for Claude, Cursor, and any MCP client.",
+  "version": "0.2.0",
+  "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": {
     "type": "git",
     "url": "git+https://github.com/redditapis/redditapis-mcp.git"
@@ -25,7 +25,8 @@
   "scripts": {
     "start": "node src/index.js",
     "check": "node --check src/index.js && node --check src/tools.js",
-    "test": "node test/tools.test.mjs"
+    "test": "node test/tools.test.mjs",
+    "prepublishOnly": "node scripts/prepublish-tenant-check.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/src/index.js

@@ -3,8 +3,10 @@
 //
 // 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, and user profile/comments.
-// Each tool is a thin, typed wrapper over a REST endpoint at
+// search, a post's comment tree, subreddit top posts, user profile/comments, and
+// (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.
 //
@@ -16,16 +18,20 @@
 //
 // 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 } from "./tools.js";
+import { TOOLS, buildQuery, buildPath, buildBody } from "./tools.js";
 
 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);
-const VERSION = "0.1.0";
+// 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");
 
 if (!API_KEY) {
   console.error(
@@ -34,12 +40,15 @@ if (!API_KEY) {
   process.exit(1);
 }
 
-// REST call. Resolves any {param} path placeholders from args, sends the rest as
-// the query string, and forwards the API key as a Bearer token (redditapis.com
+// 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") {
+async function callEndpoint(pathTemplate, args, method = "GET", tool = null) {
   const { path, rest } = buildPath(pathTemplate, args);
-  const q = buildQuery(rest);
+  const isWrite = method !== "GET";
+  const q = isWrite ? "" : buildQuery(rest);
   const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
 
   const headers = {
@@ -47,11 +56,16 @@ async function callEndpoint(pathTemplate, args, method = "GET") {
     accept: "application/json",
     "user-agent": `reddit-mcp/${VERSION}`,
   };
+  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, signal: ctrl.signal });
+    const res = await fetch(url, { method, headers, body: requestBody, signal: ctrl.signal });
     const body = await res.text();
     if (!res.ok) {
       const hint =
@@ -85,14 +99,14 @@ for (const tool of TOOLS) {
   const method = tool.method || "GET";
   const annotations = {
     title: tool.name,
-    readOnlyHint: !tool.write, // every tool here is a read
+    readOnlyHint: !tool.write,
     destructiveHint: Boolean(tool.destructive),
     openWorldHint: true,
   };
   server.registerTool(
     tool.name,
     { description: tool.description, inputSchema: tool.shape, annotations },
-    async (args) => callEndpoint(tool.path, args, method),
+    async (args) => callEndpoint(tool.path, args, method, tool),
   );
 }
 

package/src/tools.js

@@ -5,9 +5,22 @@
 // Each tool maps 1:1 to a REST endpoint at https://api.redditapis.com/api/reddit.
 // Tool arg names map 1:1 to endpoint query params, EXCEPT path params written as
 // {name}/{id} in a tool's `path` (e.g. /api/reddit/sub/{name}/top), which are
-// interpolated into the URL and removed from the query string. Every tool here
-// is a READ (GET); reddit writes (comment/vote/DM) are a separate authenticated
-// surface and are intentionally out of scope for this reads MCP.
+// interpolated into the URL and removed from the query string.
+//
+// WRITES: reddit writes (comment/vote/DM -- posting AS the customer to Reddit
+// itself) are a separate authenticated surface and remain intentionally out of
+// scope here, that boundary is unchanged. Monitor/webhook management (2026-08-11,
+// task #43) is a DIFFERENT kind of write: it configures the customer's OWN
+// redditapis.com account (an alerting subscription), the same risk class as
+// reading their own usage -- it never posts, votes, or DMs anywhere. Those tools
+// are marked `write: true` (and `destructive: true` for remove/delete), which
+// index.js turns into MCP's `readOnlyHint`/`destructiveHint` annotations so a
+// client can surface a confirmation before calling them.
+//
+// BODY-BEARING TOOLS: a POST tool's args become a JSON request body instead of
+// 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, ...).
 import { z } from "zod";
 
 // Shared Zod input-schema fragments.
@@ -63,7 +76,52 @@ const QUERY = {
   ),
 };
 
-// The tool catalog. All reads (GET). Path params are {name}/{id} placeholders.
+// ── monitoring filter_spec fragments, shared by monitor_add and monitor_update ──
+// v1 is SUBREDDIT-SCOPED ONLY (all-Reddit keyword monitoring is not available)
+// and POSTS ONLY (comment monitoring is validated but rejected server-side) --
+// both match apps/api/src/lib/monitor-filter.js's own validation exactly, so a
+// tool call fails fast in the client rather than round-tripping a 400.
+const MONITOR_SUBREDDIT = {
+  subreddit: z.array(z.string().min(1)).min(1).max(50).describe(
+    "Subreddits to watch, without the r/ prefix (e.g. ['SaaS', 'startups']). REQUIRED, 1 to 50. All-of-Reddit monitoring is not available in v1 -- every monitor must scope to specific subreddits.",
+  ),
+};
+const MONITOR_FILTER_FIELDS = {
+  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.",
+  ),
+  author: z.string().max(200).optional().describe("Only match posts by this Reddit username (without u/)."),
+  exclude_terms: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "Posts containing any of these terms are suppressed even if they otherwise match. Use to cut noise (e.g. exclude 'giveaway' from a brand-mention monitor).",
+  ),
+  domain: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "Outbound link domains to watch for (e.g. ['example.com']). Matches the post's link URL, any URL inside a self-post/comment body, and (validated but not yet populated by the live poller) a crosspost's original link. Exact-or-subdomain match only: 'example.com' matches 'blog.example.com' but never 'notexample.com'. Does NOT resolve shortened links (bit.ly, t.co).",
+  ),
+  include_any: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "At least ONE of these terms must appear (OR match) for the post to qualify, on top of any `q`."
+  ),
+  include_all: z.array(z.string().min(1).max(200)).max(50).optional().describe(
+    "EVERY one of these terms must appear (AND match) for the post to qualify, on top of any `q`."
+  ),
+  search_in: z.array(z.enum(["title", "body", "url", "permalink"])).min(1).optional().describe(
+    "Which fields keyword/term matching is scoped to. Default ['title', 'body', 'url']. Narrow to avoid false positives, e.g. a term that only appears in a URL slug matching a post that never mentions it in prose.",
+  ),
+  group: z.string().max(64).optional().describe(
+    "Optional label to bundle multiple matches into one delivery instead of one webhook call per match. Omit for one delivery per matching item.",
+  ),
+  min_score: z.number().int().optional().describe("Only match posts with at least this many upvotes."),
+  nsfw: z.boolean().optional().describe("Include NSFW/over-18 posts. Default false (excluded)."),
+};
+const MONITOR_ID = {
+  id: z.string().min(1).describe("The monitor's id, from reddit_monitor_add's response or reddit_monitor_list."),
+};
+const WEBHOOK_ID = {
+  id: z.string().min(1).describe("The webhook's id, from reddit_monitor_webhook_create's response or reddit_monitor_webhook_list."),
+};
+
+// The tool catalog. Path params are {name}/{id} placeholders. Monitor/webhook
+// tools additionally carry `write`/`destructive` and, for POST tools whose
+// body nests a filter_spec, `filterSpecFields` (see buildBody below).
 export const TOOLS = [
   {
     name: "reddit_subreddit_posts",
@@ -340,6 +398,120 @@ export const TOOLS = [
       "Browse Reddit's default front-page set of subreddits, no keyword needed. Returns a `subreddits` list (each with name, title, subscriber count, description, type, and NSFW flag) plus an `after` cursor for paging. This BROWSES the default communities; use reddit_search_communities instead to SEARCH communities by keyword.",
     shape: { ...AFTER, ...LIMIT },
   },
+
+  // ── monitoring: manage the caller's own account, never posts/votes/DMs Reddit itself ──
+  {
+    name: "reddit_monitor_add",
+    path: "/api/reddit/monitor/add",
+    method: "POST",
+    write: true,
+    filterSpecFields: ["subreddit", "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 for new posts matching a filter, and get every match delivered to a webhook you've registered with reddit_monitor_webhook_create. Requires an active redditapis.com monitoring plan (monitoring has no free tier) and 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 there is no active plan, `monitor_slots_exhausted` (402) if the plan's slot limit is reached, or `subreddit_not_found` (400) if a named subreddit does not exist.",
+    shape: {
+      ...MONITOR_SUBREDDIT,
+      ...MONITOR_FILTER_FIELDS,
+      cadence_s: z.number().int().positive().optional().describe(
+        "Requested poll interval in seconds. May only be SLOWER than the plan tier's floor, never faster -- a too-low value is silently clamped up to the tier's minimum. Omit to use the tier's default.",
+      ),
+      baseline_item_id: z.string().optional().describe(
+        "A Reddit post fullname (e.g. 't3_abc123') to use as the starting point instead of 'now' -- matching starts strictly after this item. Omit to start from the moment of creation.",
+      ),
+    },
+  },
+  {
+    name: "reddit_monitor_list",
+    path: "/api/reddit/monitor/list",
+    description:
+      "List every monitor on the caller's account, with each one's filter, active state, and cadence, plus a `slots` object ({used, total, tier}) showing how many monitor slots are purchased vs in use. Reading your own list never requires an active plan (a lapsed subscription shows an empty or paused list, not an error).",
+    shape: {},
+  },
+  {
+    name: "reddit_monitor_update",
+    path: "/api/reddit/monitor/update",
+    method: "POST",
+    write: true,
+    filterSpecFields: ["subreddit", "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`), or replace its filter entirely. IMPORTANT: if you pass ANY filter field (subreddit, q, domain, etc.), it REPLACES the whole filter, it does not merge with the existing one -- resupply every field you want kept, including `subreddit`. Omit all filter fields to change only `active`/`cadence_s` and leave the filter untouched. Returns 404 `monitor_not_found` if the id does not exist or is not yours.",
+    shape: {
+      ...MONITOR_ID,
+      ...{ subreddit: MONITOR_SUBREDDIT.subreddit.optional().describe(MONITOR_SUBREDDIT.subreddit.description + " Required if you are replacing the filter at all.") },
+      ...MONITOR_FILTER_FIELDS,
+      active: z.boolean().optional().describe("Set false to pause the monitor (stops matching/delivering), true to resume it."),
+      cadence_s: z.number().int().positive().optional().describe("New poll interval in seconds, same tier-floor clamping as reddit_monitor_add."),
+    },
+  },
+  {
+    name: "reddit_monitor_remove",
+    path: "/api/reddit/monitor/remove",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "Permanently delete a monitor. This cannot be undone -- its filter and delivery history stop growing (past deliveries remain queryable via reddit_monitor_deliveries) and its slot is freed for a new monitor. Returns 404 `monitor_not_found` if the id does not exist or is not yours.",
+    shape: { ...MONITOR_ID },
+  },
+  {
+    name: "reddit_monitor_health",
+    path: "/api/reddit/monitor/health",
+    description:
+      "Per-monitor health: whether it's active, its poll cadence, when it last matched something, and delivery counts for the last 24h (`delivered_24h`, `failed_24h`, `suppressed_24h`) plus whether its delivery ceiling has been hit (`ceiling_reached`). Use this to check whether a monitor is silently starved before assuming it just has nothing to report.",
+    shape: { ...MONITOR_ID },
+  },
+  {
+    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.",
+    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(
+        "Filter to one delivery status. 'dead' = retries exhausted, gave up. 'suppressed' = matched but deliberately not sent (e.g. delivery ceiling). Omit for all statuses.",
+      ),
+      limit: z.number().int().min(1).max(200).optional().describe("Max rows to return, 1 to 200. Default 50."),
+      before: z.string().optional().describe("ISO 8601 timestamp cursor for pagination -- pass the `created_at` of the oldest row from the previous page to fetch older deliveries."),
+    },
+  },
+  {
+    name: "reddit_monitor_webhook_create",
+    path: "/api/reddit/monitor/webhook/create",
+    method: "POST",
+    write: true,
+    description:
+      "Register a delivery target for monitors to send matches to. Requires an active monitoring plan (a webhook with no plan could never receive anything). Returns the webhook with its signing `secret` SHOWN ONCE -- store it immediately, it is never returned again by reddit_monitor_webhook_list. HTTPS only; the URL is re-validated (including a fresh DNS check) at every delivery, not just at creation.",
+    shape: {
+      url: z.string().url().describe("HTTPS URL to deliver matches to. Must be publicly reachable HTTPS, no embedded credentials, no loopback/private/link-local address."),
+      kind: z.enum(["webhook", "slack", "discord", "email"]).optional().describe(
+        "Payload shape to send. 'slack'/'discord' format as native incoming-webhook messages; 'webhook' (default) sends redditapis' generic signed JSON envelope; 'email' is not yet a real delivery transport.",
+      ),
+    },
+  },
+  {
+    name: "reddit_monitor_webhook_list",
+    path: "/api/reddit/monitor/webhook/list",
+    description: "List every webhook registered on the caller's account. Never returns the signing secret (shown once, at creation, by reddit_monitor_webhook_create).",
+    shape: {},
+  },
+  {
+    name: "reddit_monitor_webhook_test",
+    path: "/api/reddit/monitor/webhook/test",
+    method: "POST",
+    write: true,
+    description:
+      "Send a one-off test delivery to a registered webhook (rate-limited to 10/min) so you can confirm it's wired up correctly before waiting for a real match. Uses the webhook's `kind` to format the test payload the same way a real delivery would. Returns 404 `webhook_not_found` if the id does not exist or is not yours, or `webhook_url_rejected` if the URL fails re-validation (e.g. now resolves to a private address).",
+    shape: { ...WEBHOOK_ID },
+  },
+  {
+    name: "reddit_monitor_webhook_delete",
+    path: "/api/reddit/monitor/webhook/delete",
+    method: "POST",
+    write: true,
+    destructive: true,
+    description:
+      "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 },
+  },
 ];
 
 // Turn tool args into a URL query string. Skips undefined/null/empty values.
@@ -366,3 +538,27 @@ export function buildPath(template, args) {
   for (const [k, v] of Object.entries(args || {})) if (!used.has(k)) rest[k] = v;
   return { path, rest };
 }
+
+// Turn a POST tool's args into the JSON body the REST endpoint expects. A field
+// named in `tool.filterSpecFields` nests under `filter_spec`; everything else
+// stays top-level (id, cadence_s, active, url, kind, ...). Skips undefined so
+// an omitted optional arg is genuinely absent from the body, never sent as
+// `null` -- monitor-handlers.js tells "field not provided" apart from "field
+// explicitly cleared" (e.g. updateMonitor only replaces filter_spec when at
+// least one filter field is present at all).
+export function buildBody(tool, args) {
+  const filterFields = new Set(tool.filterSpecFields || []);
+  const body = {};
+  let filterSpec = null;
+  for (const [k, v] of Object.entries(args || {})) {
+    if (v === undefined) continue;
+    if (filterFields.has(k)) {
+      filterSpec = filterSpec || {};
+      filterSpec[k] = v;
+    } else {
+      body[k] = v;
+    }
+  }
+  if (filterSpec) body.filter_spec = filterSpec;
+  return body;
+}