mcp-reddit-ads 1.0.13 → 1.1.1

package/README.md

@@ -47,6 +47,11 @@ Set credentials via environment variables:
 | `REDDIT_CLIENT_ID` | OAuth app client ID |
 | `REDDIT_CLIENT_SECRET` | OAuth app client secret |
 | `REDDIT_REFRESH_TOKEN` | OAuth refresh token with ads scopes |
+| `REDDIT_ADS_MCP_WRITE` | Set to `true` to enable mutating tools (create/update/pause/enable). Unset = read-only (default). |
+
+### Read-only by default
+
+As of v1.1.0 the MCP starts in **read-only mode**. The 10 read/report/targeting tools are always exposed, but the 8 mutating tools (create/update campaigns, ad groups, ads, and bulk pause/enable) are hidden from the tool list and refused at call time unless `REDDIT_ADS_MCP_WRITE=true` is set in the server's environment. This guards against a casual chat message accidentally mutating live ad spend. Enable writes deliberately, for the sessions where you actually intend to ship changes.
 
 ### 3. Config File
 

package/dist/build-info.json

@@ -1 +1 @@
-{"sha":"b34ee9d","builtAt":"2026-04-09T23:11:50.924Z"}
+{"sha":"58320cf","builtAt":"2026-04-18T18:09:07.962Z"}

package/dist/errors.js

@@ -55,7 +55,8 @@ export function classifyError(error) {
         message.includes("Unauthorized") ||
         message.includes("Forbidden") ||
         bodyError?.code === 401) {
-        return new RedditAdsAuthError(`Reddit Ads auth failed: ${message}. Refresh token may be expired. Update REDDIT_REFRESH_TOKEN in Keychain.`, error);
+        return new RedditAdsAuthError(`Reddit Ads auth failed: ${message}. Refresh token may be expired. Update your REDDIT_REFRESH_TOKEN environment variable.` +
+            (process.platform === "darwin" ? ` On macOS: security add-generic-password -a reddit-ads-mcp -s REDDIT_REFRESH_TOKEN -w '<token>' -U` : ""), error);
     }
     if (status === 429 || message.includes("rate limit") || message.includes("Rate limit")) {
         const retryMs = error?.retryAfterMs || 60_000;

package/dist/index.js

@@ -7,6 +7,8 @@ import { join, dirname } from "path";
 import { RedditAdsAuthError, RedditAdsRateLimitError, RedditAdsServiceError, classifyError, validateCredentials, } from "./errors.js";
 import { tools } from "./tools.js";
 import { withResilience, safeResponse, logger } from "./resilience.js";
+import { filterTools, assertWriteAllowed, isWriteEnabled } from "./writeGate.js";
+import { checkForUpdate } from "./updateNotifier.js";
 import v8 from "v8";
 // CLI package info
 const __cliPkg = JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf-8"));
@@ -21,9 +23,17 @@ catch {
 }
 // Version safety: warn if running a deprecated or dangerously old version
 const __minimumSafeVersion = "1.0.5"; // minimum version with input sanitization
-if (__cliPkg.version < __minimumSafeVersion) {
+const __semverLt = (a, b) => { const pa = a.split(".").map(Number), pb = b.split(".").map(Number); for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0))
+        return true;
+    if ((pa[i] || 0) > (pb[i] || 0))
+        return false;
+} return false; };
+if (__semverLt(__cliPkg.version, __minimumSafeVersion)) {
     console.error(`[WARNING] Running deprecated version ${__cliPkg.version}. Minimum safe version is ${__minimumSafeVersion}. Please upgrade.`);
 }
+// Fire-and-forget npm outdated check. Non-blocking; any error is swallowed.
+void checkForUpdate(__cliPkg.name, __cliPkg.version).catch(() => { });
 // CLI flags
 if (process.argv.includes("--help") || process.argv.includes("-h")) {
     console.error(`${__cliPkg.name} v${__cliPkg.version}\n`);
@@ -113,7 +123,9 @@ class RedditAdsManager {
         this.config = config;
         const creds = validateCredentials();
         if (!creds.valid) {
-            const msg = `[STARTUP ERROR] Missing required credentials: ${creds.missing.join(", ")}. MCP will not function. Check run-mcp.sh and Keychain entries.`;
+            const msg = `[STARTUP ERROR] Missing required credentials: ${creds.missing.join(", ")}. ` +
+                `Set these environment variables before starting the server.` +
+                (process.platform === "darwin" ? ` On macOS, tokens can be stored in Keychain and loaded via run-mcp.sh.` : "");
             console.error(msg);
             throw new RedditAdsAuthError(msg);
         }
@@ -146,6 +158,27 @@ class RedditAdsManager {
         const data = await resp.json();
         this.accessToken = data.access_token;
         this.tokenExpiry = Date.now() + ((data.expires_in || 3600) - 60) * 1000;
+        // Persist rotated refresh token so restarts use the latest
+        if (data.refresh_token && data.refresh_token !== auth.refresh_token) {
+            auth.refresh_token = data.refresh_token;
+            if (process.platform === "darwin") {
+                try {
+                    const { execFileSync } = await import("child_process");
+                    try {
+                        execFileSync("security", ["delete-generic-password", "-a", "reddit-ads-mcp", "-s", "REDDIT_REFRESH_TOKEN"], { stdio: "ignore" });
+                    }
+                    catch { /* may not exist yet */ }
+                    execFileSync("security", ["add-generic-password", "-a", "reddit-ads-mcp", "-s", "REDDIT_REFRESH_TOKEN", "-w", data.refresh_token]);
+                    console.error("[token] Rotated refresh token persisted to Keychain");
+                }
+                catch (err) {
+                    console.error("[token] WARNING: Failed to persist rotated refresh token to Keychain:", err);
+                }
+            }
+            else {
+                console.error("[token] Refresh token rotated. Update your REDDIT_REFRESH_TOKEN environment variable to persist across restarts.");
+            }
+        }
         return this.accessToken;
     }
     async apiCall(method, path, options) {
@@ -320,13 +353,14 @@ class RedditAdsManager {
 const config = loadConfig();
 const adsManager = new RedditAdsManager(config);
 const server = new Server({ name: __cliPkg.name, version: __cliPkg.version }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: filterTools(tools) }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const ok = (data) => ({
         content: [{ type: "text", text: JSON.stringify(safeResponse(data, name), null, 2) }],
     });
     try {
+        assertWriteAllowed(name);
         const accountId = () => {
             const id = args?.account_id;
             if (id)
@@ -579,7 +613,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             server: __cliPkg.name,
         };
         if (error instanceof RedditAdsAuthError) {
-            response.action_required = "Re-authenticate: refresh token may be expired. Run oauth_flow.py and update Keychain.";
+            response.action_required = "Re-authenticate: refresh token may be expired. Update your REDDIT_REFRESH_TOKEN environment variable." +
+                (process.platform === "darwin" ? " On macOS: security add-generic-password -a reddit-ads-mcp -s REDDIT_REFRESH_TOKEN -w '<token>' -U" : "");
         }
         else if (error instanceof RedditAdsRateLimitError) {
             response.retry_after_ms = error.retryAfterMs;
@@ -609,6 +644,10 @@ async function main() {
         console.error(`[STARTUP WARNING] Auth check FAILED: ${err.message}`);
         console.error(`[STARTUP WARNING] MCP will start but API calls may fail until auth is fixed.`);
     }
+    const writeMode = isWriteEnabled()
+        ? "WRITE ENABLED (REDDIT_ADS_MCP_WRITE=true) -- mutating tools are exposed"
+        : "READ-ONLY (default) -- set REDDIT_ADS_MCP_WRITE=true to enable mutating tools";
+    console.error(`[startup] Write mode: ${writeMode}`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[startup] MCP Reddit Ads server running");

package/dist/updateNotifier.d.ts

@@ -0,0 +1,7 @@
+export type FetchLatestVersion = () => Promise<string>;
+export interface UpdateNotifierDeps {
+    fetchLatestVersion?: FetchLatestVersion;
+    log?: (msg: string) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function checkForUpdate(pkgName: string, currentVersion: string, deps?: UpdateNotifierDeps): Promise<void>;

package/dist/updateNotifier.js

@@ -0,0 +1,59 @@
+// Fire-and-forget npm registry check at startup. Logs to stderr when a
+// newer version is available. stdout is reserved for MCP JSON-RPC, so the
+// message never goes there. Silent on network error, timeout, or when the
+// installed version is equal to or ahead of the registry latest.
+//
+// Opt out by setting MCP_DISABLE_UPDATE_CHECK=1 (CI, offline, air-gapped).
+// Also skipped when NODE_ENV=test to keep vitest runs silent.
+export async function checkForUpdate(pkgName, currentVersion, deps = {}) {
+    const env = deps.env ?? process.env;
+    if (env.MCP_DISABLE_UPDATE_CHECK === "1" || env.NODE_ENV === "test") {
+        return;
+    }
+    const log = deps.log ?? ((msg) => process.stderr.write(msg + "\n"));
+    const fetcher = deps.fetchLatestVersion ?? (() => defaultFetch(pkgName));
+    let latest;
+    try {
+        latest = await fetcher();
+    }
+    catch {
+        return;
+    }
+    if (!latest || !semverLt(currentVersion, latest)) {
+        return;
+    }
+    log(`[update] ${pkgName}@${latest} is available (running ${currentVersion}). ` +
+        `Upgrade: npx -y ${pkgName}@latest (and relaunch Claude Desktop).`);
+}
+async function defaultFetch(pkgName) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 2_000);
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, {
+            signal: controller.signal,
+            headers: { Accept: "application/json" },
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (typeof body.version !== "string") {
+            throw new Error("registry response missing version field");
+        }
+        return body.version;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function semverLt(a, b) {
+    const pa = a.split(".").map((x) => parseInt(x, 10) || 0);
+    const pb = b.split(".").map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}

package/dist/writeGate.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Tools that mutate Reddit Ads state. These are hidden from the tool list
+ * and refused at call time unless REDDIT_ADS_MCP_WRITE=true.
+ *
+ * Adding a new tool? Put it in this set if it creates, modifies, pauses,
+ * enables, removes, links, unlinks, or applies anything.
+ */
+export declare const WRITE_TOOLS: ReadonlySet<string>;
+export declare function isWriteTool(name: string): boolean;
+export declare function isWriteEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function filterTools(allTools: readonly Tool[], env?: NodeJS.ProcessEnv): Tool[];
+export declare const WRITE_DISABLED_MESSAGE = "Write operations are disabled. Set REDDIT_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable).";
+/**
+ * Assert that a tool call is allowed under the current write-mode setting.
+ * Throws a clear Error if the tool mutates state and writes are disabled.
+ */
+export declare function assertWriteAllowed(toolName: string, env?: NodeJS.ProcessEnv): void;

package/dist/writeGate.js

@@ -0,0 +1,41 @@
+/**
+ * Tools that mutate Reddit Ads state. These are hidden from the tool list
+ * and refused at call time unless REDDIT_ADS_MCP_WRITE=true.
+ *
+ * Adding a new tool? Put it in this set if it creates, modifies, pauses,
+ * enables, removes, links, unlinks, or applies anything.
+ */
+export const WRITE_TOOLS = new Set([
+    "reddit_ads_create_campaign",
+    "reddit_ads_update_campaign",
+    "reddit_ads_create_ad_group",
+    "reddit_ads_update_ad_group",
+    "reddit_ads_create_ad",
+    "reddit_ads_update_ad",
+    "reddit_ads_pause_items",
+    "reddit_ads_enable_items",
+]);
+export function isWriteTool(name) {
+    return WRITE_TOOLS.has(name);
+}
+export function isWriteEnabled(env = process.env) {
+    const v = (env.REDDIT_ADS_MCP_WRITE || "").trim().toLowerCase();
+    return v === "true" || v === "1" || v === "yes";
+}
+export function filterTools(allTools, env = process.env) {
+    if (isWriteEnabled(env))
+        return [...allTools];
+    return allTools.filter((t) => !WRITE_TOOLS.has(t.name));
+}
+export const WRITE_DISABLED_MESSAGE = "Write operations are disabled. Set REDDIT_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable).";
+/**
+ * Assert that a tool call is allowed under the current write-mode setting.
+ * Throws a clear Error if the tool mutates state and writes are disabled.
+ */
+export function assertWriteAllowed(toolName, env = process.env) {
+    if (!isWriteTool(toolName))
+        return;
+    if (isWriteEnabled(env))
+        return;
+    throw new Error(`Tool "${toolName}" is a write operation. ${WRITE_DISABLED_MESSAGE}`);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-reddit-ads",
   "mcpName": "io.github.mharnett/reddit-ads",
-  "version": "1.0.13",
+  "version": "1.1.1",
   "description": "MCP server for Reddit Ads API v3 with campaign, ad group, ad management, and performance reporting.",
   "main": "dist/index.js",
   "bin": {
@@ -39,6 +39,7 @@
     "pino-pretty": "^13.1.3"
   },
   "devDependencies": {
+    "@drak-marketing/mcp-test-harness": "^0.1.2",
     "@types/node": "^20.10.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",