mcp-linkedin-ads 1.0.13 → 1.1.1

package/README.md

@@ -64,6 +64,26 @@ npm install mcp-linkedin-ads
    export LINKEDIN_ADS_ACCESS_TOKEN="your_access_token"
    ```
 
+### Environment variables
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `LINKEDIN_ADS_CLIENT_ID` | yes | -- | OAuth client ID |
+| `LINKEDIN_ADS_CLIENT_SECRET` | yes | -- | OAuth client secret |
+| `LINKEDIN_ADS_ACCESS_TOKEN` | yes | -- | OAuth access token |
+| `LINKEDIN_ADS_REFRESH_TOKEN` | optional | -- | OAuth refresh token (rotated automatically when set) |
+| `LINKEDIN_ADS_MCP_WRITE` | optional | `false` | Set to `true` to expose mutating tools. Read-only by default. |
+
+### Read-only by default
+
+The LinkedIn Ads MCP currently ships with read-only tools only. The write-mode
+gate is already in place so that any future create/update/pause/enable/remove
+tool is hidden from `ListTools` and refused at call time unless
+`LINKEDIN_ADS_MCP_WRITE=true` is set in the MCP server environment. This
+mirrors the Google Ads MCP gate and matches the pattern being rolled out to
+Bing / Reddit / Meta. Motivation: prevent a casual LLM request from mutating
+production ad accounts without the operator explicitly opting in.
+
 ## Usage
 
 ### Start the server

package/dist/build-info.json

@@ -1 +1 @@
-{"sha":"3375b28","builtAt":"2026-04-09T23:02:26.033Z"}
+{"sha":"acbfeb9","builtAt":"2026-04-18T18:10:49.640Z"}

package/dist/index.js

@@ -6,6 +6,7 @@ import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { LinkedInAdsAuthError, 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
@@ -21,7 +22,13 @@ 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.`);
 }
 // CLI flags
@@ -55,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 LINKEDIN_ACCESS_TOKEN, LINKEDIN_ADS_REFRESH_TOKEN, linkedin-client-id, and linkedin-client-secret. ` +
+            `Run 'node get-refresh-token.cjs' to obtain a refresh token.`);
     }
     return JSON.parse(readFileSync(configPath, "utf-8"));
 }
@@ -298,12 +307,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);
         const resolveAccountId = (accountId) => {
             if (accountId)
                 return accountId;
@@ -435,6 +445,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    const writeMode = isWriteEnabled()
+        ? "WRITES ENABLED (LINKEDIN_ADS_MCP_WRITE=true)"
+        : "read-only (set LINKEDIN_ADS_MCP_WRITE=true to enable mutating tools)";
+    console.error(`[startup] write mode: ${writeMode}`);
     logger.info("MCP LinkedIn Ads server running");
 }
 process.on("SIGTERM", () => {

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,22 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Tools that mutate LinkedIn Ads state. These are hidden from the tool list
+ * and refused at call time unless LINKEDIN_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.
+ *
+ * This set is currently empty: the LinkedIn Ads MCP exposes read-only tools
+ * only. The gate still ships so that any future write tool is gated by
+ * default, matching the Google Ads / Bing / Reddit / Meta pattern.
+ */
+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 LINKEDIN_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 LinkedIn Ads state. These are hidden from the tool list
+ * and refused at call time unless LINKEDIN_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.
+ *
+ * This set is currently empty: the LinkedIn Ads MCP exposes read-only tools
+ * only. The gate still ships so that any future write tool is gated by
+ * default, matching the Google Ads / Bing / Reddit / Meta pattern.
+ */
+export const WRITE_TOOLS = new Set([]);
+export function isWriteTool(name) {
+    return WRITE_TOOLS.has(name);
+}
+export function isWriteEnabled(env = process.env) {
+    const v = (env.LINKEDIN_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 LINKEDIN_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-linkedin-ads",
   "mcpName": "io.github.mharnett/linkedin-ads",
-  "version": "1.0.13",
+  "version": "1.1.1",
   "description": "MCP server for LinkedIn Campaign Manager API with full campaign, ad group, creative, and targeting support. Production-proven with 65+ campaigns under active management.",
   "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",