mcp-linkedin-ads 1.0.14 → 1.1.2

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":"9e7a890","builtAt":"2026-04-09T23:18:58.748Z"}
+{"sha":"eb446cf","builtAt":"2026-05-08T18:24:15.904Z"}

package/dist/index.js

@@ -4,16 +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";
+const __dirname = dirname(fileURLToPath(import.meta.url));
 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
-const __cliPkg = JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf-8"));
+const __cliPkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 // Log build fingerprint at startup
 try {
-    const __buildInfoDir = dirname(new URL(import.meta.url).pathname);
-    const buildInfo = JSON.parse(readFileSync(join(__buildInfoDir, "build-info.json"), "utf-8"));
+    const buildInfo = JSON.parse(readFileSync(join(__dirname, "build-info.json"), "utf-8"));
     console.error(`[build] SHA: ${buildInfo.sha} (${buildInfo.builtAt})`);
 }
 catch {
@@ -59,9 +61,11 @@ if (heapLimit < 256 * 1024 * 1024) {
 // ============================================
 const envTrimmed = (key) => (process.env[key] || "").trim().replace(/^["']|["']$/g, "");
 function loadConfig() {
-    const configPath = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
+    const configPath = join(__dirname, "..", "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"));
 }
@@ -73,6 +77,23 @@ function getClientFromWorkingDir(config, cwd) {
     }
     return null;
 }
+// Add derived `frequency` (impressions / approximateMemberReach) to each
+// analytics element when both fields are present. approximateMemberReach is
+// only populated by the LinkedIn API at certain pivots (CAMPAIGN, CREATIVE,
+// CAMPAIGN_GROUP); at pivot=ACCOUNT it returns 0, in which case frequency is
+// omitted rather than reported as Infinity.
+function enrichAnalyticsResponse(raw) {
+    if (!raw || !Array.isArray(raw.elements))
+        return raw;
+    for (const el of raw.elements) {
+        const reach = Number(el?.approximateMemberReach ?? 0);
+        const impr = Number(el?.impressions ?? 0);
+        if (reach > 0 && impr > 0) {
+            el.frequency = +(impr / reach).toFixed(4);
+        }
+    }
+    return raw;
+}
 // ============================================
 // LINKEDIN MARKETING API CLIENT
 // ============================================
@@ -222,7 +243,7 @@ class LinkedInAdsManager {
         const statuses = options?.status || ["ACTIVE", "PAUSED"];
         const statusList = `List(${statuses.join(",")})`;
         let searchParams = `(status:(values:${statusList}))`;
-        let url = `${this.config.api.base_url}/adAccounts/${accountId}/adCampaigns?q=search&search=${encodeURIComponent(searchParams)}&count=100`;
+        let url = `${this.config.api.base_url}/adAccounts/${accountId}/adCampaigns?q=search&search=${searchParams}&count=100`;
         if (options?.campaignGroupId) {
             url += `&search.campaignGroup.values=List(urn%3Ali%3AsponsoredCampaignGroup%3A${options.campaignGroupId})`;
         }
@@ -244,12 +265,18 @@ class LinkedInAdsManager {
             "oneClickLeads", "oneClickLeadFormOpens",
             "externalWebsiteConversions", "externalWebsitePostClickConversions",
             "totalEngagements", "videoViews", "videoCompletions",
+            "approximateMemberReach",
             "dateRange", "pivotValues",
         ];
+        // LinkedIn Restli quirk (verified against /rest/adAnalytics with
+        // LinkedIn-Version 202602): dateRange value must use literal
+        // parens/colons/commas — percent-encoding them returns 400 PARAM_INVALID.
+        // The URN inside accounts=List(...) MUST be percent-encoded, but the
+        // List() wrapper itself stays literal. fields uses literal commas.
         const accountUrn = encodeURIComponent(`urn:li:sponsoredAccount:${options.accountId}`);
         let url = `${this.config.api.base_url}/adAnalytics?q=analytics` +
             `&pivot=${options.pivot}` +
-            `&dateRange=${encodeURIComponent(dateRange)}` +
+            `&dateRange=${dateRange}` +
             `&timeGranularity=${granularity}` +
             `&accounts=List(${accountUrn})` +
             `&fields=${fields.join(",")}`;
@@ -265,7 +292,8 @@ class LinkedInAdsManager {
                 .join(",");
             url += `&campaignGroups=List(${urns})`;
         }
-        return await this.apiGetRaw(url);
+        const raw = await this.apiGetRaw(url);
+        return enrichAnalyticsResponse(raw);
     }
     async getCampaignPerformance(accountId, options) {
         return await this.getAnalytics({
@@ -304,12 +332,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;
@@ -441,6 +470,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/tools.js

@@ -56,7 +56,7 @@ export const tools = [
     },
     {
         name: "linkedin_ads_campaign_performance",
-        description: "Get campaign-level performance metrics (impressions, clicks, spend, conversions, leads, engagement, video views) for a date range. This is the main reporting tool for weekly slides.",
+        description: "Get campaign-level performance metrics (impressions, clicks, spend, conversions, leads, engagement, video views, reach, frequency) for a date range. Reach = approximateMemberReach (unique members exposed); frequency = impressions / reach (computed server-side). This is the main reporting tool for weekly slides.",
         inputSchema: {
             additionalProperties: false,
             type: "object",
@@ -71,7 +71,7 @@ export const tools = [
     },
     {
         name: "linkedin_ads_account_performance",
-        description: "Get account-level aggregate performance metrics for a date range. Good for high-level summaries.",
+        description: "Get account-level aggregate performance metrics for a date range. Good for high-level summaries. Note: reach (approximateMemberReach) and the derived frequency field are not populated at pivot=ACCOUNT; query at CAMPAIGN/CAMPAIGN_GROUP via linkedin_ads_campaign_performance or linkedin_ads_analytics if you need reach.",
         inputSchema: {
             additionalProperties: false,
             type: "object",
@@ -102,7 +102,7 @@ export const tools = [
                 fields: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Metrics to return. Default: impressions, clicks, costInLocalCurrency, landingPageClicks, oneClickLeads, externalWebsiteConversions, totalEngagements, videoViews, dateRange, pivotValues",
+                    description: "Metrics to return. Default: impressions, clicks, costInLocalCurrency, landingPageClicks, oneClickLeads, oneClickLeadFormOpens, externalWebsiteConversions, externalWebsitePostClickConversions, totalEngagements, videoViews, videoCompletions, approximateMemberReach, dateRange, pivotValues. The server adds a derived `frequency` field (impressions / approximateMemberReach) when both are non-zero. Reach is only populated at pivots CAMPAIGN, CREATIVE, and CAMPAIGN_GROUP — it returns 0 at pivot=ACCOUNT.",
                 },
                 campaign_ids: { type: "array", items: { type: "string" }, description: "Filter by numeric string campaign IDs" },
                 campaign_group_ids: { type: "array", items: { type: "string" }, description: "Filter by campaign group IDs" },

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.14",
+  "version": "1.1.2",
   "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": {
@@ -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"
   },
   "keywords": [
     "mcp",
@@ -58,6 +59,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",