mcp-reddit-ads 1.0.14 → 1.1.2

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":"1d8c954","builtAt":"2026-04-09T23:19:14.252Z"}
+{"sha":"19917ed","builtAt":"2026-07-09T14:42:15.009Z"}

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

@@ -4,15 +4,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
+import { fileURLToPath } from "url";
 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 "mcp-updatenotifier";
 import v8 from "v8";
 // CLI package info
-const __cliPkg = JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf-8"));
+const __cliPkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8"));
 // Log build fingerprint at startup
 try {
-    const __buildInfoDir = dirname(new URL(import.meta.url).pathname);
+    const __buildInfoDir = dirname(fileURLToPath(import.meta.url));
     const buildInfo = JSON.parse(readFileSync(join(__buildInfoDir, "build-info.json"), "utf-8"));
     console.error(`[build] SHA: ${buildInfo.sha} (${buildInfo.builtAt})`);
 }
@@ -30,6 +33,8 @@ const __semverLt = (a, b) => { const pa = a.split(".").map(Number), pb = b.split
 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`);
@@ -60,7 +65,7 @@ if (heapLimit < 256 * 1024 * 1024) {
 const envTrimmed = (key) => (process.env[key] || "").trim().replace(/^["']|["']$/g, "");
 function loadConfig() {
     // Try config.json first
-    const configPath = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
+    const configPath = join(dirname(fileURLToPath(import.meta.url)), "..", "config.json");
     let config;
     if (existsSync(configPath)) {
         config = JSON.parse(readFileSync(configPath, "utf-8"));
@@ -119,7 +124,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);
         }
@@ -152,6 +159,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) {
@@ -326,13 +354,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)
@@ -585,7 +614,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;
@@ -615,6 +645,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/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,44 @@
+import { createWriteGate } from "mcp-write-gate";
+/**
+ * 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",
+]);
+const gate = createWriteGate({
+    writeTools: WRITE_TOOLS,
+    envPrefix: "REDDIT_ADS",
+});
+export function isWriteTool(name) {
+    return gate.isWriteTool(name);
+}
+export function isWriteEnabled(env = process.env) {
+    return gate.isWriteEnabled(env);
+}
+export function filterTools(allTools, env = process.env) {
+    return gate.filterTools(allTools, env);
+}
+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) {
+    try {
+        gate.assertWriteAllowed(toolName, env);
+    }
+    catch (e) {
+        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.14",
+  "version": "1.1.2",
   "description": "MCP server for Reddit Ads API v3 with campaign, ad group, ad management, and performance reporting.",
   "main": "dist/index.js",
   "bin": {
@@ -25,7 +25,8 @@
     "build": "tsc && node -e \"fs=require('fs');cp=require('child_process');sha=cp.execSync('git rev-parse --short HEAD 2>/dev/null||echo unknown').toString().trim();fs.writeFileSync('dist/build-info.json',JSON.stringify({sha,builtAt:new Date().toISOString()}))\"",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "test": "vitest run"
+    "test": "vitest run",
+    "smoke": "scripts/healthcheck.sh"
   },
   "author": "drak-marketing",
   "license": "MIT",
@@ -35,13 +36,20 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.5.0",
     "cockatiel": "^3.2.1",
+    "mcp-updatenotifier": "^1.0.0",
+    "mcp-write-gate": "^1.0.0",
     "pino": "^8.21.0",
     "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",
     "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mharnett/mcp-reddit-ads.git"
   }
 }