mcp-bing-ads 1.0.15 → 1.1.0

package/README.md

@@ -65,8 +65,24 @@ npm install mcp-bing-ads
    export BING_ADS_REFRESH_TOKEN="your_refresh_token"
    # Optional:
    export BING_ADS_CLIENT_SECRET="your_client_secret"
+   # Optional: opt into mutating tools (read-only by default)
+   export BING_ADS_MCP_WRITE="true"
    ```
 
+### Environment Variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `BING_ADS_DEVELOPER_TOKEN` | yes | -- | Microsoft Advertising developer token |
+| `BING_ADS_CLIENT_ID` | yes | -- | Azure AD app client ID |
+| `BING_ADS_REFRESH_TOKEN` | yes | -- | OAuth refresh token |
+| `BING_ADS_CLIENT_SECRET` | no | -- | Azure AD app client secret (if confidential client) |
+| `BING_ADS_MCP_WRITE` | no | `false` | Set to `true`, `1`, or `yes` to expose mutating tools (pause/update/add). Any other value -- or unset -- keeps the server read-only. |
+
+### Read-only by default
+
+Mutating tools (`bing_ads_pause_keywords`, `bing_ads_update_campaign_budget`, `bing_ads_add_shared_negatives`) are **hidden from the tool list and refused at call time** unless `BING_ADS_MCP_WRITE=true` is set in the server environment. This is a safety gate against casual write actions -- for example, pausing a keyword or editing a budget based on a throwaway chat message. To make write changes, set the env var explicitly in your `.mcp.json` or shell profile for the session that needs it, then unset it afterwards. Read tools (list/report/performance) are always available.
+
 ## Usage
 
 ### Start the server

package/dist/build-info.json

@@ -1 +1 @@
-{"sha":"da8d128","builtAt":"2026-04-09T23:18:53.060Z"}
+{"sha":"202808b","builtAt":"2026-04-18T18:10:54.717Z"}

package/dist/errors.js

@@ -55,7 +55,8 @@ export function classifyError(error) {
         message.includes("AuthenticationTokenExpired") ||
         message.includes("InvalidCredentials") ||
         bodyError?.code === "AuthenticationTokenExpired") {
-        return new BingAdsAuthError(`Bing Ads auth failed: ${message}. Refresh token may be expired. Re-authenticate and update Keychain.`, error);
+        return new BingAdsAuthError(`Bing Ads auth failed: ${message}. Refresh token may be expired. Run 'node get-refresh-token.cjs' and update your BING_ADS_REFRESH_TOKEN environment variable.` +
+            (process.platform === "darwin" ? ` On macOS: security add-generic-password -a bing-ads-mcp -s BING_ADS_REFRESH_TOKEN -w '<token>' -U` : ""), error);
     }
     if (status === 429 || message.includes("RateLimit") || message.includes("CallRateExceeded")) {
         const retryMs = 60_000;

package/dist/index.js

@@ -6,6 +6,7 @@ import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { BingAdsAuthError, BingAdsRateLimitError, BingAdsServiceError, classifyError, validateCredentials, } from "./errors.js";
 import { tools } from "./tools.js";
+import { filterTools, assertWriteAllowed, isWriteEnabled } from "./writeGate.js";
 import { withResilience, safeResponse, logger } from "./resilience.js";
 import v8 from "v8";
 // CLI package info
@@ -61,7 +62,9 @@ const envTrimmed = (key) => (process.env[key] || "").trim().replace(/^["']|["']$
 function loadConfig() {
     const configPath = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
     if (!existsSync(configPath)) {
-        throw new Error(`Config file not found at ${configPath}. Create config.json from config.example.json with your client entries.`);
+        throw new Error(`Config file not found at ${configPath}. Create config.json from config.example.json with your client entries, ` +
+            `or set env vars BING_ADS_DEVELOPER_TOKEN, BING_ADS_CLIENT_ID, BING_ADS_CLIENT_SECRET, and BING_ADS_REFRESH_TOKEN. ` +
+            `Run 'node get-refresh-token.cjs' to obtain a refresh token.`);
     }
     return JSON.parse(readFileSync(configPath, "utf-8"));
 }
@@ -89,7 +92,9 @@ class BingAdsManager {
         // Validate credentials at startup — fail fast
         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 BingAdsAuthError(msg);
         }
@@ -599,12 +604,13 @@ const server = new Server({
 });
 // Handle list tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools };
+    return { tools: filterTools(tools) };
 });
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
+        assertWriteAllowed(name);
         // Resolve client from account_id or working directory context
         const resolveClient = (accountId) => {
             if (accountId) {
@@ -818,6 +824,8 @@ async function main() {
         console.error(`[STARTUP WARNING] Auth check FAILED: ${err.message}`);
         console.error(`[STARTUP WARNING] MCP will start but ALL API calls will fail until auth is fixed.`);
     }
+    const writeMode = isWriteEnabled();
+    console.error(`[startup] Write mode: ${writeMode ? "ENABLED (mutating tools exposed)" : "DISABLED (read-only; set BING_ADS_MCP_WRITE=true to enable writes)"}`);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[startup] MCP Bing 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 Bing Ads state. These are hidden from the tool list
+ * and refused at call time unless BING_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 BING_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable/remove/apply).";
+/**
+ * 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,36 @@
+/**
+ * Tools that mutate Bing Ads state. These are hidden from the tool list
+ * and refused at call time unless BING_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([
+    "bing_ads_add_shared_negatives",
+    "bing_ads_pause_keywords",
+    "bing_ads_update_campaign_budget",
+]);
+export function isWriteTool(name) {
+    return WRITE_TOOLS.has(name);
+}
+export function isWriteEnabled(env = process.env) {
+    const v = (env.BING_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 BING_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable/remove/apply).";
+/**
+ * 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-bing-ads",
   "mcpName": "io.github.mharnett/bing-ads",
-  "version": "1.0.15",
+  "version": "1.1.0",
   "description": "MCP server for Microsoft Advertising (Bing Ads) API with campaign, ad group, keyword, and performance reporting. First comprehensive open-source Bing Ads MCP.",
   "main": "dist/index.js",
   "bin": {
@@ -58,6 +58,7 @@
     "zod": "^3.22.4"
   },
   "devDependencies": {
+    "@drak-marketing/mcp-test-harness": "^0.1.2",
     "@types/node": "^20.10.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",