mobile-growth-mcp 2.2.1 → 2.3.4

package/dist/index.js

@@ -23,7 +23,7 @@ async function jsonRpcRequest(apiKey2, method, params) {
       Accept: "application/json, text/event-stream"
     },
     body: JSON.stringify(body),
-    signal: AbortSignal.timeout(15e3)
+    signal: AbortSignal.timeout(3e4)
   });
   if (!res.ok) {
     const text = await res.text();
@@ -39,19 +39,34 @@ async function fetchRemoteTools(apiKey2) {
   return resp.result?.tools ?? [];
 }
 async function callRemoteTool(apiKey2, name, args) {
-  const resp = await jsonRpcRequest(apiKey2, "tools/call", {
-    name,
-    arguments: args
-  });
-  if (resp.error) {
-    return {
-      content: [{ type: "text", text: `Remote error: ${resp.error.message}` }],
-      isError: true
-    };
+  const maxAttempts = 2;
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const resp = await jsonRpcRequest(apiKey2, "tools/call", {
+        name,
+        arguments: args
+      });
+      if (resp.error) {
+        return {
+          content: [{ type: "text", text: `Remote error: ${resp.error.message}` }],
+          isError: true
+        };
+      }
+      return {
+        content: resp.result?.content ?? [{ type: "text", text: "No content returned" }],
+        isError: resp.result?.isError
+      };
+    } catch (err) {
+      lastError = err;
+      const isRetryable = lastError.name === "AbortError" || lastError.name === "TimeoutError" || lastError.message?.includes("fetch failed");
+      if (!isRetryable || attempt === maxAttempts) break;
+      await new Promise((r) => setTimeout(r, 2e3));
+    }
   }
   return {
-    content: resp.result?.content ?? [{ type: "text", text: "No content returned" }],
-    isError: resp.result?.isError
+    content: [{ type: "text", text: `Remote call failed after retry: ${lastError?.message ?? "unknown error"}` }],
+    isError: true
   };
 }
 function jsonSchemaToZodShape(inputSchema) {
@@ -222,7 +237,7 @@ async function metaApiGet(options) {
 function activeFilter() {
   return JSON.stringify([
     {
-      field: "effective_status",
+      field: "ad.effective_status",
       operator: "IN",
       value: ["ACTIVE"]
     }
@@ -243,6 +258,8 @@ var CAMPAIGN_DEFAULT_FIELDS = "id,name,status,effective_status,objective,bid_str
 var ADSET_DEFAULT_FIELDS = "id,name,status,effective_status,campaign_id,optimization_goal,billing_event,bid_strategy,bid_amount,daily_budget,lifetime_budget,targeting,promoted_object";
 var AD_DEFAULT_FIELDS = "id,name,status,effective_status,adset_id,campaign_id,creative{id,title,body,image_url,video_id,call_to_action_type}";
 var INSIGHT_DEFAULT_FIELDS = "campaign_id,campaign_name,spend,impressions,clicks,ctr,cpm,cpc,actions,cost_per_action_type";
+var INSIGHT_ADSET_FIELDS = "adset_id,adset_name";
+var INSIGHT_AD_FIELDS = "adset_id,adset_name,ad_id,ad_name";
 
 // src/tools/meta-campaigns.ts
 function registerGetMetaCampaigns(server2) {
@@ -405,16 +422,17 @@ import { z as z4 } from "zod";
 function registerGetMetaAds(server2) {
   server2.tool(
     "get_meta_ads",
-    "List ads from a Meta ad account, optionally scoped to an ad set. Defaults to active ads with lean field set.",
+    "List ads from a Meta ad account, optionally scoped to a campaign or ad set. Defaults to active ads with lean field set.",
     {
       ad_account_id: z4.string().describe("Meta ad account ID (e.g. act_123456789)"),
-      adset_id: z4.string().optional().describe("Scope to a specific ad set ID."),
+      campaign_id: z4.string().optional().describe("Scope to a specific campaign ID (e.g. 23851234567890)"),
+      adset_id: z4.string().optional().describe("Scope to a specific ad set ID. Takes priority over campaign_id."),
       fields: z4.string().optional().describe(`Comma-separated fields. Default: ${AD_DEFAULT_FIELDS}`),
       effective_status: z4.array(z4.string()).optional().describe('Filter by status. Default: ["ACTIVE"]'),
       limit: z4.number().min(1).max(100).optional().describe("Results per page (default 50, max 100)"),
       after: z4.string().optional().describe("Pagination cursor from previous response")
     },
-    async ({ ad_account_id, adset_id, fields, effective_status, limit, after }) => {
+    async ({ ad_account_id, campaign_id, adset_id, fields, effective_status, limit, after }) => {
       try {
         const params = {
           fields: fields ?? AD_DEFAULT_FIELDS,
@@ -434,7 +452,7 @@ function registerGetMetaAds(server2) {
         if (after) {
           params.after = after;
         }
-        const parentPath = adset_id ? `/${adset_id}/ads` : `/${ad_account_id}/ads`;
+        const parentPath = adset_id ? `/${adset_id}/ads` : campaign_id ? `/${campaign_id}/ads` : `/${ad_account_id}/ads`;
         const result = await metaApiGet({
           path: parentPath,
           params
@@ -446,7 +464,7 @@ function registerGetMetaAds(server2) {
 `;
         for (const ad of ads) {
           text += `- **${ad.name}** (${ad.id})
-  Ad Set: ${ad.adset_id} | Status: ${ad.effective_status}` + (ad.creative?.call_to_action_type ? ` | CTA: ${ad.creative.call_to_action_type}` : "") + (ad.creative?.video_id ? " | Format: Video" : "") + (ad.creative?.image_url ? " | Format: Image" : "") + "\n";
+  Campaign: ${ad.campaign_id} | Ad Set: ${ad.adset_id} | Status: ${ad.effective_status}` + (ad.creative?.call_to_action_type ? ` | CTA: ${ad.creative.call_to_action_type}` : "") + (ad.creative?.video_id ? " | Format: Video" : "") + (ad.creative?.image_url ? " | Format: Image" : "") + "\n";
         }
         if (nextCursor) {
           text += `
@@ -478,12 +496,14 @@ import { z as z5 } from "zod";
 function registerGetMetaInsights(server2) {
   server2.tool(
     "get_meta_insights",
-    "Pull performance insights from a Meta ad account with configurable level, breakdowns, and date range. Default: campaign-level, last 7 days, active only. Conversion event is configurable (default: mobile_app_install).",
+    "Pull performance insights from a Meta ad account with configurable level, breakdowns, and date range. Default: campaign-level, last 7 days, active only. Conversion event is configurable (default: mobile_app_install). Use campaign_id or adset_id to scope results.",
     {
       ad_account_id: z5.string().describe("Meta ad account ID (e.g. act_123456789)"),
+      campaign_id: z5.string().optional().describe("Scope to a specific campaign ID (e.g. 23851234567890)"),
+      adset_id: z5.string().optional().describe("Scope to a specific ad set ID (e.g. 23851234567891)"),
       level: z5.enum(["account", "campaign", "adset", "ad"]).optional().describe("Aggregation level (default: campaign)"),
       fields: z5.string().optional().describe(
-        `Comma-separated fields. Default: ${INSIGHT_DEFAULT_FIELDS}`
+        `Comma-separated fields. Default includes level-appropriate name fields + ${INSIGHT_DEFAULT_FIELDS}`
       ),
       date_preset: z5.string().optional().describe(`Date preset (default: ${DEFAULT_DATE_PRESET})`),
       time_range: z5.object({
@@ -510,6 +530,8 @@ function registerGetMetaInsights(server2) {
     },
     async ({
       ad_account_id,
+      campaign_id,
+      adset_id,
       level,
       fields,
       date_preset,
@@ -524,9 +546,20 @@ function registerGetMetaInsights(server2) {
     }) => {
       try {
         const convEvent = conversion_event ?? "mobile_app_install";
+        const effectiveLevel = level ?? "campaign";
+        let effectiveFields = fields;
+        if (!effectiveFields) {
+          if (effectiveLevel === "ad") {
+            effectiveFields = `${INSIGHT_AD_FIELDS},${INSIGHT_DEFAULT_FIELDS}`;
+          } else if (effectiveLevel === "adset") {
+            effectiveFields = `${INSIGHT_ADSET_FIELDS},${INSIGHT_DEFAULT_FIELDS}`;
+          } else {
+            effectiveFields = INSIGHT_DEFAULT_FIELDS;
+          }
+        }
         const params = {
-          fields: fields ?? INSIGHT_DEFAULT_FIELDS,
-          level: level ?? "campaign",
+          fields: effectiveFields,
+          level: effectiveLevel,
           limit: String(limit ?? 50)
         };
         if (time_range) {
@@ -540,11 +573,22 @@ function registerGetMetaInsights(server2) {
         if (breakdowns) {
           params.breakdowns = breakdowns;
         }
-        if (filtering !== void 0) {
-          params.filtering = filtering === "[]" ? "[]" : filtering;
-        } else {
-          params.filtering = activeFilter();
+        const baseFilters = filtering !== void 0 ? filtering === "[]" ? [] : JSON.parse(filtering) : JSON.parse(activeFilter());
+        if (campaign_id) {
+          baseFilters.push({
+            field: "campaign.id",
+            operator: "IN",
+            value: [campaign_id]
+          });
         }
+        if (adset_id) {
+          baseFilters.push({
+            field: "adset.id",
+            operator: "IN",
+            value: [adset_id]
+          });
+        }
+        params.filtering = JSON.stringify(baseFilters);
         if (sort) {
           params.sort = sort;
         }
@@ -567,9 +611,10 @@ function registerGetMetaInsights(server2) {
             ]
           };
         }
-        let text = `**${rows.length} rows** | Level: ${level ?? "campaign"} | Event: ${convEvent}
-
-`;
+        let text = `**${rows.length} rows** | Level: ${effectiveLevel} | Event: ${convEvent}`;
+        if (campaign_id) text += ` | Campaign: ${campaign_id}`;
+        if (adset_id) text += ` | Ad Set: ${adset_id}`;
+        text += "\n\n";
         for (const row of rows) {
           const spend = parseFloat(row.spend || "0");
           const impressions = parseInt(row.impressions || "0");
@@ -929,6 +974,30 @@ function formatGoogleAdsError(err) {
   }
   return `Google Ads API error (${code}): ${err.message}`;
 }
+async function googleAdsMutate(customerId, operations) {
+  const auth = getGoogleAdsAuth();
+  const normalizedId = normalizeCustomerId(customerId);
+  const headers = await auth.getHeaders(normalizedId);
+  const url = `${BASE_URL}/customers/${normalizedId}/googleAds:mutate`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      ...headers,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ mutateOperations: operations })
+  });
+  const body = await response.json();
+  if (!response.ok) {
+    if (isGoogleAdsError(body)) {
+      throw new Error(formatGoogleAdsError(body.error));
+    }
+    throw new Error(
+      `Google Ads API mutate returned ${response.status}: ${JSON.stringify(body)}`
+    );
+  }
+  return body;
+}
 async function googleAdsQuery(customerId, query) {
   const auth = getGoogleAdsAuth();
   const normalizedId = normalizeCustomerId(customerId);
@@ -958,6 +1027,23 @@ async function googleAdsQuery(customerId, query) {
 }
 
 // src/google/format.ts
+async function resolveCampaignId(customerId, value) {
+  if (/^\d+$/.test(value)) return value;
+  const query = `SELECT campaign.id, campaign.name FROM campaign WHERE campaign.name = '${value.replace(/'/g, "\\'")}' LIMIT 1`;
+  const chunks = await googleAdsQuery(customerId, query);
+  const rows = chunks.flatMap((c) => c.results ?? []);
+  if (rows.length === 0) throw new Error(`Campaign not found by name: "${value}"`);
+  return rows[0].campaign.id;
+}
+async function resolveAdGroupId(customerId, value, campaignId) {
+  if (/^\d+$/.test(value)) return value;
+  let query = `SELECT ad_group.id, ad_group.name FROM ad_group WHERE ad_group.name = '${value.replace(/'/g, "\\'")}' LIMIT 1`;
+  if (campaignId) query = query.replace("LIMIT 1", `AND campaign.id = ${campaignId} LIMIT 1`);
+  const chunks = await googleAdsQuery(customerId, query);
+  const rows = chunks.flatMap((c) => c.results ?? []);
+  if (rows.length === 0) throw new Error(`Ad group not found by name: "${value}"`);
+  return rows[0].adGroup.id;
+}
 function formatMicros(micros) {
   if (!micros) return "\u2014";
   const val = parseInt(micros, 10);
@@ -1091,7 +1177,7 @@ function registerGetGoogleAdsCampaigns(server2) {
         const header = `## Google Campaigns (${rows.length} found)
 
 `;
-        const tableHeader = "| Campaign | Status | Type | Bid Strategy | Target | Daily Budget | App |\n|---|---|---|---|---|---|---|\n";
+        const tableHeader = "| ID | Campaign | Status | Type | Bid Strategy | Target | Daily Budget | App |\n|---|---|---|---|---|---|---|---|\n";
         let tableRows = "";
         for (const row of rows) {
           const c = row.campaign;
@@ -1102,7 +1188,7 @@ function registerGetGoogleAdsCampaigns(server2) {
           const appId = c.appCampaignSetting?.appId ?? "";
           const store = appStoreLabel(c.appCampaignSetting?.appStore);
           const appDisplay = appId ? `${appId} (${store})` : "\u2014";
-          tableRows += `| ${c.name} | ${c.status} | ${channelSubTypeLabel(c.advertisingChannelSubType)} | ${c.biddingStrategyType ?? "\u2014"} | ${formatTarget(row)} | ${budgetDisplay} | ${appDisplay} |
+          tableRows += `| ${c.id} | ${c.name} | ${c.status} | ${channelSubTypeLabel(c.advertisingChannelSubType)} | ${c.biddingStrategyType ?? "\u2014"} | ${formatTarget(row)} | ${budgetDisplay} | ${appDisplay} |
 `;
         }
         return {
@@ -1143,8 +1229,9 @@ function registerGetGoogleAdsAdGroups(server2) {
         let whereClause = `WHERE campaign.advertising_channel_sub_type IN ('APP_CAMPAIGN', 'APP_CAMPAIGN_FOR_ENGAGEMENT')
   AND ad_group.status IN (${statusList})`;
         if (campaign_id) {
+          const resolvedCampaignId = await resolveCampaignId(customer_id, campaign_id);
           whereClause += `
-  AND campaign.id = ${campaign_id}`;
+  AND campaign.id = ${resolvedCampaignId}`;
         }
         const query = `
           SELECT
@@ -1175,13 +1262,13 @@ function registerGetGoogleAdsAdGroups(server2) {
         const header = `## Ad Groups${campaignName} (${rows.length} found)
 
 `;
-        const tableHeader = "| Ad Group | Status | Type | Campaign |\n|---|---|---|---|\n";
+        const tableHeader = "| Ad Group ID | Ad Group | Status | Type | Campaign ID | Campaign |\n|---|---|---|---|---|---|\n";
         let tableRows = "";
         for (const row of rows) {
           const ag = row.adGroup;
           const c = row.campaign;
           if (!ag) continue;
-          tableRows += `| ${ag.name} | ${ag.status ?? "\u2014"} | ${ag.type ?? "\u2014"} | ${c?.name ?? "\u2014"} |
+          tableRows += `| ${ag.id} | ${ag.name} | ${ag.status ?? "\u2014"} | ${ag.type ?? "\u2014"} | ${c?.id ?? "\u2014"} | ${c?.name ?? "\u2014"} |
 `;
         }
         return {
@@ -1236,8 +1323,14 @@ function registerGetGoogleAdsAssets(server2) {
         const conditions = [
           "campaign.status = 'ENABLED'"
         ];
-        if (campaign_id) conditions.push(`campaign.id = ${campaign_id}`);
-        if (ad_group_id) conditions.push(`ad_group.id = ${ad_group_id}`);
+        if (campaign_id) {
+          const resolvedCampaignId = await resolveCampaignId(customer_id, campaign_id);
+          conditions.push(`campaign.id = ${resolvedCampaignId}`);
+        }
+        if (ad_group_id) {
+          const resolvedAdGroupId = await resolveAdGroupId(customer_id, ad_group_id, campaign_id);
+          conditions.push(`ad_group.id = ${resolvedAdGroupId}`);
+        }
         if (asset_type?.length) {
           const typeList = asset_type.map((t) => `'${t}'`).join(", ");
           conditions.push(`asset.type IN (${typeList})`);
@@ -1531,8 +1624,14 @@ function registerGetGoogleAdsInsights(server2) {
           "campaign.status = 'ENABLED'",
           `segments.date BETWEEN '${startDate}' AND '${endDate}'`
         ];
-        if (campaign_id) conditions.push(`campaign.id = ${campaign_id}`);
-        if (ad_group_id) conditions.push(`ad_group.id = ${ad_group_id}`);
+        if (campaign_id) {
+          const resolvedCampaignId = await resolveCampaignId(customer_id, campaign_id);
+          conditions.push(`campaign.id = ${resolvedCampaignId}`);
+        }
+        if (ad_group_id) {
+          const resolvedAdGroupId = await resolveAdGroupId(customer_id, ad_group_id, campaign_id);
+          conditions.push(`ad_group.id = ${resolvedAdGroupId}`);
+        }
         const orderBy = `ORDER BY ${sortKeyForEnum(sortField)} DESC`;
         const query = `
           SELECT ${selectFields.join(", ")}
@@ -1677,7 +1776,10 @@ function registerGetGoogleAdsNetworkMix(server2) {
           "campaign.status = 'ENABLED'",
           `segments.date BETWEEN '${startDate}' AND '${endDate}'`
         ];
-        if (campaign_id) conditions.push(`campaign.id = ${campaign_id}`);
+        if (campaign_id) {
+          const resolvedCampaignId = await resolveCampaignId(customer_id, campaign_id);
+          conditions.push(`campaign.id = ${resolvedCampaignId}`);
+        }
         const query = `
           SELECT
             campaign.id,
@@ -1887,11 +1989,15 @@ function registerGetGoogleAdsAssetFatigue(server2) {
         startDate.setDate(startDate.getDate() - lookback + 1);
         const ageStartDate = new Date(endDate);
         ageStartDate.setDate(ageStartDate.getDate() - 89);
+        const resolvedCampaignId = await resolveCampaignId(customer_id, campaign_id);
         const conditions = [
-          `campaign.id = ${campaign_id}`,
+          `campaign.id = ${resolvedCampaignId}`,
           `segments.date BETWEEN '${dateFmt(startDate)}' AND '${dateFmt(endDate)}'`
         ];
-        if (ad_group_id) conditions.push(`ad_group.id = ${ad_group_id}`);
+        if (ad_group_id) {
+          const resolvedAdGroupId = await resolveAdGroupId(customer_id, ad_group_id, resolvedCampaignId);
+          conditions.push(`ad_group.id = ${resolvedAdGroupId}`);
+        }
         if (asset_type?.length) {
           const typeList = asset_type.map((t) => `'${t}'`).join(", ");
           conditions.push(`asset.type IN (${typeList})`);
@@ -2121,6 +2227,168 @@ Sources: goog-pdf-018, ab-pt-008, goog-pdf-019, ab-pt-007
   );
 }
 
+// src/tools/google-upload-assets.ts
+import { z as z13 } from "zod";
+import { readFile } from "fs/promises";
+import { basename, resolve } from "path";
+async function fetchAsBase64(url) {
+  if (url.startsWith("data:")) {
+    const commaIdx = url.indexOf(",");
+    if (commaIdx === -1) throw new Error("Invalid data URI");
+    return url.slice(commaIdx + 1);
+  }
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  return buf.toString("base64");
+}
+async function readFileAsBase64(filePath) {
+  const buf = await readFile(resolve(filePath));
+  return buf.toString("base64");
+}
+function registerUploadGoogleImageAssets(server2) {
+  server2.tool(
+    "upload_google_image_assets",
+    "Upload image assets to a Google Ads account. Accepts URLs or local file paths. Each image becomes an Asset resource in the account. Optionally link assets to a campaign or ad group after upload. Supports batch upload (up to 50 images per call).",
+    {
+      customer_id: z13.string().describe("Google Ads customer ID"),
+      images: z13.array(
+        z13.object({
+          source: z13.string().describe(
+            "Image URL (https://...) or local file path (/path/to/image.png)"
+          ),
+          name: z13.string().optional().describe(
+            "Asset name in Google Ads (default: filename from source)"
+          )
+        })
+      ).min(1).max(50).describe("Array of images to upload (max 50 per call)"),
+      campaign_id: z13.string().optional().describe(
+        "Link uploaded assets to this campaign (creates CampaignAsset links)"
+      ),
+      ad_group_id: z13.string().optional().describe(
+        "Link uploaded assets to this ad group (creates AdGroupAsset links). Takes priority over campaign_id."
+      ),
+      field_type: z13.enum(["IMAGE", "LANDSCAPE_LOGO", "LOGO", "MARKETING_IMAGE", "SQUARE_MARKETING_IMAGE", "PORTRAIT_MARKETING_IMAGE"]).optional().describe("Asset field type when linking to campaign/ad group (default: IMAGE)"),
+      dry_run: z13.boolean().optional().describe("Preview what would be uploaded without making changes")
+    },
+    async ({
+      customer_id,
+      images,
+      campaign_id,
+      ad_group_id,
+      field_type,
+      dry_run
+    }) => {
+      try {
+        const normalizedId = normalizeCustomerId(customer_id);
+        const effectiveFieldType = field_type ?? "IMAGE";
+        if (dry_run) {
+          let text2 = `**Dry run** \u2014 would upload ${images.length} image(s) to customer ${customer_id}
+
+`;
+          for (const img of images) {
+            const name = img.name ?? basename(img.source).replace(/\?.*$/, "") ?? "unnamed";
+            text2 += `- ${name} \u2190 ${img.source}
+`;
+          }
+          if (ad_group_id) {
+            text2 += `
+Would link to ad group ${ad_group_id} as ${effectiveFieldType}`;
+          } else if (campaign_id) {
+            text2 += `
+Would link to campaign ${campaign_id} as ${effectiveFieldType}`;
+          }
+          return { content: [{ type: "text", text: text2 }] };
+        }
+        const assetOps = [];
+        const assetNames = [];
+        for (const img of images) {
+          const name = img.name ?? basename(img.source).replace(/\?.*$/, "") ?? "unnamed";
+          assetNames.push(name);
+          const isUrl = img.source.startsWith("http://") || img.source.startsWith("https://") || img.source.startsWith("data:");
+          const data = isUrl ? await fetchAsBase64(img.source) : await readFileAsBase64(img.source);
+          assetOps.push({
+            assetOperation: {
+              create: {
+                name,
+                type: "IMAGE",
+                imageAsset: { data }
+              }
+            }
+          });
+        }
+        const assetResult = await googleAdsMutate(normalizedId, assetOps);
+        const createdResourceNames = assetResult.mutateOperationResponses.map(
+          (r) => r.assetResult?.resourceName ?? ""
+        );
+        const successCount = createdResourceNames.filter(Boolean).length;
+        let text = `**Uploaded ${successCount}/${images.length} image assets**
+
+`;
+        for (let i = 0; i < images.length; i++) {
+          const rn = createdResourceNames[i];
+          if (rn) {
+            text += `\u2713 ${assetNames[i]} \u2192 ${rn}
+`;
+          } else {
+            text += `\u2717 ${assetNames[i]} \u2014 failed
+`;
+          }
+        }
+        if (successCount > 0 && (ad_group_id || campaign_id)) {
+          const linkOps = [];
+          for (const resourceName of createdResourceNames) {
+            if (!resourceName) continue;
+            if (ad_group_id) {
+              linkOps.push({
+                adGroupAssetOperation: {
+                  create: {
+                    adGroup: `customers/${normalizedId}/adGroups/${ad_group_id}`,
+                    asset: resourceName,
+                    fieldType: effectiveFieldType
+                  }
+                }
+              });
+            } else if (campaign_id) {
+              linkOps.push({
+                campaignAssetOperation: {
+                  create: {
+                    campaign: `customers/${normalizedId}/campaigns/${campaign_id}`,
+                    asset: resourceName,
+                    fieldType: effectiveFieldType
+                  }
+                }
+              });
+            }
+          }
+          try {
+            await googleAdsMutate(normalizedId, linkOps);
+            const linkTarget = ad_group_id ? `ad group ${ad_group_id}` : `campaign ${campaign_id}`;
+            text += `
+\u2713 Linked ${successCount} assets to ${linkTarget} as ${effectiveFieldType}`;
+          } catch (linkErr) {
+            text += `
+\u26A0\uFE0F Assets uploaded but linking failed: ${linkErr instanceof Error ? linkErr.message : String(linkErr)}`;
+            text += `
+Assets exist in the account and can be linked manually.`;
+          }
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/tools/connection-status.ts
 function registerConnectionStatus(server2, status2) {
   server2.tool(
@@ -2156,10 +2424,11 @@ function registerConnectionStatus(server2, status2) {
         );
       } else {
         lines.push(
-          "## Meta Marketing API: Not Configured",
-          "- Meta tools will return an error when called",
+          "## Meta Marketing API: Not Connected (Optional)",
+          "- KB, suggestions, and private insights work without it",
+          "- Connect Meta to unlock live campaign data and reports",
           "",
-          "### How to fix",
+          "### How to connect",
           "Provide your Meta access token using one of these methods:",
           '1. MCP config: add `"META_ACCESS_TOKEN": "..."` to the `"env"` block in `.mcp.json` (Claude Code/Cursor) or `claude_desktop_config.json` (Claude Desktop)',
           "2. CLI argument: add `--meta-token=...` to the args array",
@@ -2176,11 +2445,11 @@ function registerConnectionStatus(server2, status2) {
         );
       } else {
         lines.push(
-          "## Google Ads API: Not Configured",
-          "- Google Ads tools will return an error when called",
-          `- Missing: ${status2.google.missing.join(", ")}`,
+          "## Google Ads API: Not Connected (Optional)",
+          "- KB, suggestions, and private insights work without it",
+          "- Connect Google Ads to unlock campaign data and network analysis",
           "",
-          "### How to fix",
+          "### How to connect",
           "Option 1 \u2014 Interactive setup (recommended):",
           "```",
           "npx mobile-growth-mcp auth google",
@@ -2314,35 +2583,40 @@ function registerVocabularyResource(server2) {
 }
 
 // src/resources/instructions.ts
-var INSTRUCTIONS = `# Mobile Growth MCP \u2014 Knowledge Base + Meta Ad Tools
+var INSTRUCTIONS = `# Mobile Growth MCP \u2014 Knowledge Base + Ad Platform Tools
 
 ## Welcome
 
-You're connected to the Mobile Growth knowledge base \u2014 curated expert insights on mobile advertising, campaign optimization, and subscription app growth.
+You're connected to the Mobile Growth knowledge base \u2014 curated expert insights on mobile advertising, campaign optimization, and subscription app growth \u2014 plus direct Meta and Google Ads API integration.
 
 **The knowledge base is always on.** Use \`search_insights\` freely \u2014 before making recommendations, when diagnosing issues, or exploring strategies. The more specific your query, the better the results.
 
+> **Note:** Connecting Meta or Google Ads is optional. The knowledge base, community suggestions, and private insights all work with just your API key. Add Meta or Google Ads credentials later if you want live campaign data and reports.
+
 Quick examples:
 - "subscription app creative fatigue signals"
 - "Meta CBO vs ABO tradeoffs for subscription apps"
+- "Google UAC network shift detection"
 - "iOS attribution strategies post-ATT"
 
 If you can't find what you need, call \`submit_feedback\` to report the gap \u2014 it helps us improve the knowledge base.
 
 ## What This Is
-A curated knowledge base of mobile advertising insights + direct Meta Marketing API integration. Query expert knowledge, pull live campaign data, and run pre-built reports \u2014 all from your LLM.
+A curated knowledge base of mobile advertising insights + direct Meta Marketing API and Google Ads API integration. Query expert knowledge, pull live campaign data, and run pre-built reports \u2014 all from your LLM.
+
+---
 
 ## Knowledge Base Tools
 
 ### search_insights
-Semantic + keyword hybrid search across the knowledge base.
+Semantic + keyword hybrid search across the knowledge base. **Use this first** for any question about mobile advertising before searching the web.
 - **query** (required): Natural language search query
 - **topics** (optional): Filter by topic tags, e.g. ["creative_strategy", "scaling"]
 - **applies_to** (optional): Filter by applicability, e.g. ["subscription_apps", "ios"]
 - **limit** (optional): Max results, 1-30, default 10
 
 ### list_insights
-Browse all insights with optional filtering. Returns titles and metadata.
+Browse all insights with optional filtering. Returns titles and metadata. Private insights are marked with a lock icon.
 - **topic** (optional): Filter by a single topic tag
 - **applies_to** (optional): Filter by a single applies_to value
 
@@ -2350,12 +2624,29 @@ Browse all insights with optional filtering. Returns titles and metadata.
 Fetch the full content of a specific insight by ID or slug.
 - **id** (required): Numeric ID or string slug (e.g. "mb-li-001")
 
+### get_vocabulary_counts
+Returns counts of how many insights use each topic and applies_to tag. Lightweight way to explore what's in the KB.
+
 ### submit_feedback
-Report a gap in the knowledge base or a missing capability. Helps improve the product.
-- **category** (required): missing_knowledge, missing_feature, search_quality, or other
-- **summary** (required): What was needed but not available (anonymized \u2014 no account IDs or tokens)
+Report a gap in the knowledge base, a bug in any tool, or a missing capability.
+- **category** (required): missing_knowledge, missing_feature, search_quality, bug_report, or other
+- **summary** (required): What was needed or what went wrong (anonymized \u2014 no account IDs or tokens)
 - **search_queries_tried** (optional): Search queries that returned poor/no results
 
+## Community Knowledge
+
+### suggest_insight \u2B50 DEFAULT for saving knowledge
+Submit knowledge for admin review. **This is the default tool when a user wants to save an insight** \u2014 it contributes to the shared knowledge base that benefits all users. Extract as much structured data as possible from the source material \u2014 full insight schema (title, insight text, source metadata, topics, actionable steps). Once approved, it's added to the shared knowledge base.
+- Use this when the user shares an article, post, or discussion with valuable mobile growth knowledge
+- Keep raw_excerpt concise (under 500 chars) for reliability
+
+### save_private_insight
+Save knowledge that is private to your API key. Immediately searchable but only visible to you. **Only use this instead of suggest_insight when** the content contains client-specific data, internal benchmarks, account metrics, or the user explicitly asks for private storage.
+- Same full schema as suggest_insight
+- No admin approval needed \u2014 saved instantly
+
+---
+
 ## Meta Marketing API Tools
 
 **Requires META_ACCESS_TOKEN env var** \u2014 without it, these tools return a clear error. Knowledge base tools work with just API_KEY.
@@ -2380,8 +2671,10 @@ List ads, optionally scoped to an ad set.
 - **fields, effective_status, limit, after** (optional)
 
 ### get_meta_insights
-Pull performance insights with configurable level, breakdowns, date range.
+Pull performance insights with configurable level, breakdowns, date range. Ad-level queries auto-include ad_id, ad_name, adset_id, adset_name.
 - **ad_account_id** (required)
+- **campaign_id** (optional): Scope to a specific campaign
+- **adset_id** (optional): Scope to a specific ad set
 - **level** (optional): account, campaign, adset, ad (default: campaign)
 - **date_preset** (optional): default last_7d
 - **time_range** (optional): {since, until} for custom dates
@@ -2399,33 +2692,87 @@ Built-in report: detect creative fatigue via frequency, CTR decline, CPA trends.
 - **frequency_critical** (optional): default 5
 - **ctr_decline_threshold** (optional): default 30%
 
+---
+
 ## Google Ads Tools
 
-**Requires Google Ads credentials** \u2014 run \`npx mobile-growth-mcp auth google\` to set up interactively. This walks you through developer token, OAuth app, and authorization. Credentials are saved to \`.env\` and never leave the user's machine.
+**Requires Google Ads credentials** \u2014 run \`npx mobile-growth-mcp auth google\` to set up interactively. Credentials are saved to \`.env\` and never leave the user's machine.
+
+All tools accept campaign and ad group IDs as either **numeric IDs** or **campaign/ad group names** \u2014 names are auto-resolved to numeric IDs internally.
 
 ### get_google_ads_campaigns
-List campaigns from a Google Ads account with key metrics (last 7 days).
+List Google App Campaigns with status, bid strategy, budgets, and app info. Returns **numeric campaign IDs** needed by other tools.
 - **customer_id** (required): Google Ads customer ID (e.g. "123-456-7890")
-- **status** (optional): Filter by status \u2014 ENABLED, PAUSED, or REMOVED (default: ENABLED)
+- **status** (optional): Filter by status \u2014 ENABLED, PAUSED, REMOVED (default: ["ENABLED"])
+- **channel_sub_type** (optional): Filter by campaign type \u2014 APP_CAMPAIGN (ACi), APP_CAMPAIGN_FOR_ENGAGEMENT (ACe)
 - **limit** (optional): Max campaigns to return (default 50)
 
+### get_google_ad_groups
+List ad groups within Google App Campaigns. Returns **numeric ad group IDs** and campaign IDs. In UAC, ad groups represent creative themes \u2014 observe spend distribution to identify winning messaging angles.
+- **customer_id** (required): Google Ads customer ID
+- **campaign_id** (optional): Scope to a specific campaign (name or numeric ID)
+- **status** (optional): Filter by status (default: ["ENABLED"])
+- **limit** (optional): Max results (default 50)
+
+### get_google_insights
+Pull performance metrics with configurable level, breakdowns, date ranges, and time granularity. Use **network breakdown** to detect traffic shifts between Search, Display/AdMob, and YouTube \u2014 the #1 diagnostic lever for Google campaigns.
+- **customer_id** (required): Google Ads customer ID
+- **level** (optional): account, campaign, ad_group, asset (default: campaign)
+- **campaign_id** (optional): Scope to specific campaign (name or numeric ID)
+- **ad_group_id** (optional): Scope to specific ad group
+- **breakdown** (optional): network or device (one at a time \u2014 GAQL restriction)
+- **date_range** (optional): {start_date, end_date} in YYYY-MM-DD
+- **date_preset** (optional): LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH
+- **time_increment** (optional): daily, weekly, monthly, summary (default: summary)
+- **sort** (optional): cost_desc, conversions_desc, impressions_desc, ctr_desc
+- **limit** (optional): Max results (default 50, max 500)
+
+### get_google_assets
+List creative assets with metadata, performance labels, and slot utilization audit. Checks headlines, descriptions, images, videos against Google's per-slot maximums.
+- **customer_id** (required): Google Ads customer ID
+- **campaign_id** (optional): Scope to a specific campaign (name or numeric ID)
+- **ad_group_id** (optional): Scope to a specific ad group
+- **asset_type** (optional): IMAGE, YOUTUBE_VIDEO, TEXT, MEDIA_BUNDLE
+- **include_slot_audit** (optional): default true
+- **limit** (optional): Max results (default 50)
+
+### get_google_network_mix
+Analyze traffic distribution across Google's ad networks (Search, Display/AdMob, YouTube) over time. Flags significant shifts in spend share \u2014 a sudden shift to Display/MGDN typically tanks CPA.
+- **customer_id** (required): Google Ads customer ID
+- **campaign_id** (optional): Scope to one campaign (name or numeric ID)
+- **date_range** (optional): {start_date, end_date} \u2014 default last 14 days
+- **shift_threshold_pct** (optional): Flag networks with spend share change > this % (default 10)
+
+### get_google_asset_fatigue
+Detect creative asset fatigue by analyzing per-asset impression trends, CTR decline, and CPA deterioration. Checks asset age against Google's 2-week learning minimum and 2-3 month refresh cadence.
+- **customer_id** (required): Google Ads customer ID
+- **campaign_id** (required): Campaign to analyze (name or numeric ID)
+- **ad_group_id** (optional): Scope to specific ad group
+- **lookback_days** (optional): Days of data to analyze, 7-90 (default 14)
+- **ctr_decline_threshold_pct** (optional): CTR decline % to flag (default 30)
+- **impression_decay_threshold_pct** (optional): Impression drop % to flag (default 50)
+- **asset_type** (optional): IMAGE, YOUTUBE_VIDEO, TEXT
+
+---
+
 ## Reports (MCP Prompts)
 
-Pre-built analysis workflows. Select a prompt and provide your ad_account_id to run:
+Pre-built analysis workflows for Meta accounts. Select a prompt and provide your ad_account_id to run:
 
 | Prompt | What it does | API calls |
 |--------|-------------|-----------|
 | ad-fatigue-report | Detect creative fatigue with daily granularity | 1 |
 | weekly-performance | Week-over-week health comparison with diagnosis | 2 |
 | creative-performance | Categorize ads by health status | 1 |
-| placement-efficiency | Identify placement waste and savings | 1 per campaign |
-| audience-composition | Age \xD7 gender heatmap with CPA analysis | 1-2 |
+| audience-composition | Age x gender heatmap with CPA analysis | 1-2 |
 | architecture-review | Campaign structure evaluation | 3 (no insights) |
 | audit-meta-account | Comprehensive account audit | 6+ |
 | campaign-comparison | Side-by-side campaign comparison | 3+ |
 | placement-audit | Detailed placement audit with examples | 1 per campaign |
 | attribution-analysis | Conversion quality validation | 2+ |
 
+---
+
 ## Resources
 
 ### vocabulary://tags
@@ -2435,17 +2782,31 @@ Lists all topic tags, applies_to tags, and platforms with counts.
 
 When your response draws on knowledge base results, **always attribute visibly** so the user knows the value came from the curated KB, not your general training data:
 
-- **Tell the user** the information comes from the Mobile Growth knowledge base (e.g. "According to the Mobile Growth KB\u2026" or "The knowledge base recommends\u2026")
-- **Cite source author + slug** for key claims (e.g. "\u2026(source: Eric Seufert, \`mb-li-001\`)")
-- **When multiple insights support a recommendation**, mention the count (e.g. "3 insights in the KB agree that\u2026")
-- **Distinguish KB-sourced advice from your own reasoning** \u2014 if you're adding your own analysis on top of KB results, make that clear (e.g. "The KB covers X; based on that, my suggestion is Y")
-
-## Tips
-- Start with \`list_insights\` to see what's in the knowledge base
-- Use \`search_insights\` to find specific advice grounded in expert knowledge
-- Meta tools default to safe parameters (last_7d, active-only) to avoid rate limits
-- Reports reference specific knowledge base insight IDs \u2014 use \`get_insight\` to read the full context
-- For custom date ranges, use time_range instead of date_preset
+- **Tell the user** the information comes from the Mobile Growth knowledge base (e.g. "According to the Mobile Growth KB..." or "The knowledge base recommends...")
+- **Cite source author + slug** for key claims (e.g. "...(source: Eric Seufert, \`mb-li-001\`)")
+- **When multiple insights support a recommendation**, mention the count (e.g. "3 insights in the KB agree that...")
+- **Distinguish KB-sourced advice from your own reasoning** \u2014 if you're adding your own analysis on top of KB results, make that clear
+
+## Workflow Tips
+
+### For Google Ads analysis:
+1. Start with \`get_google_ads_campaigns\` to see campaigns and get numeric IDs
+2. Use \`get_google_insights\` with network breakdown to check traffic distribution
+3. Use \`get_google_network_mix\` if you suspect network shifts
+4. Use \`get_google_assets\` to audit creative slot utilization
+5. Use \`get_google_asset_fatigue\` on specific campaigns to detect creative decay
+
+### For Meta analysis:
+1. Start with \`get_meta_campaigns\` to see account structure
+2. Use reports (MCP prompts) for comprehensive analysis
+3. For custom analysis, use \`get_meta_insights\` with breakdowns
+
+### General:
+- Always \`search_insights\` before making recommendations \u2014 ground advice in expert knowledge
+- Use \`get_insight\` to read full context when reports reference insight IDs
+- Use \`suggest_insight\` (default) when a user shares valuable knowledge from articles or discussions
+- Use \`save_private_insight\` only for client-specific data the user explicitly wants private
+- If a tool errors unexpectedly, call \`submit_feedback\` with category \`bug_report\`
 `;
 function buildStatusSection(status2) {
   if (!status2) return "";
@@ -2466,20 +2827,20 @@ function buildStatusSection(status2) {
     lines.push("- **Meta Marketing API**: Token configured");
   } else {
     lines.push(
-      "- **Meta Marketing API**: Token not configured \u2014 Meta tools will return errors"
+      "- **Meta Marketing API**: Not connected (optional \u2014 KB works without it)"
     );
     lines.push(
-      "  - Fix: provide your token via `--meta-token=...` CLI arg, `META_ACCESS_TOKEN` env var, or `.env` file"
+      "  - To connect: provide your token via `--meta-token=...` CLI arg, `META_ACCESS_TOKEN` env var, or `.env` file"
     );
   }
   if (status2.google.configured) {
     lines.push("- **Google Ads API**: Configured");
   } else {
     lines.push(
-      "- **Google Ads API**: Not configured \u2014 Google Ads tools will return errors"
+      "- **Google Ads API**: Not connected (optional \u2014 KB works without it)"
     );
     lines.push(
-      "  - Fix: run `npx mobile-growth-mcp auth google` to set up credentials"
+      "  - To connect: run `npx mobile-growth-mcp auth google` to set up credentials"
     );
   }
   return lines.join("\n");
@@ -2546,7 +2907,7 @@ function getDotEnv() {
   }
   return dotEnvCache;
 }
-function resolve(envName, cliName) {
+function resolve2(envName, cliName) {
   const cli = getCliArg(cliName);
   if (cli) return { value: cli, source: `--${cliName} argument` };
   const env = process.env[envName]?.trim();
@@ -2556,17 +2917,17 @@ function resolve(envName, cliName) {
   return { value: void 0, source: "not configured" };
 }
 function resolveApiKey() {
-  return resolve("API_KEY", "api-key");
+  return resolve2("API_KEY", "api-key");
 }
 function resolveMetaToken() {
-  return resolve("META_ACCESS_TOKEN", "meta-token");
+  return resolve2("META_ACCESS_TOKEN", "meta-token");
 }
 function resolveGoogleAdsConfig() {
-  const devToken = resolve("GOOGLE_ADS_DEVELOPER_TOKEN", "google-dev-token");
-  const clientId = resolve("GOOGLE_ADS_CLIENT_ID", "google-client-id");
-  const clientSecret = resolve("GOOGLE_ADS_CLIENT_SECRET", "google-client-secret");
-  const refreshToken = resolve("GOOGLE_ADS_REFRESH_TOKEN", "google-refresh-token");
-  const loginCustomerId = resolve("GOOGLE_ADS_LOGIN_CUSTOMER_ID", "google-login-customer-id");
+  const devToken = resolve2("GOOGLE_ADS_DEVELOPER_TOKEN", "google-dev-token");
+  const clientId = resolve2("GOOGLE_ADS_CLIENT_ID", "google-client-id");
+  const clientSecret = resolve2("GOOGLE_ADS_CLIENT_SECRET", "google-client-secret");
+  const refreshToken = resolve2("GOOGLE_ADS_REFRESH_TOKEN", "google-refresh-token");
+  const loginCustomerId = resolve2("GOOGLE_ADS_LOGIN_CUSTOMER_ID", "google-login-customer-id");
   const required = [
     { name: "GOOGLE_ADS_DEVELOPER_TOKEN", result: devToken },
     { name: "GOOGLE_ADS_CLIENT_ID", result: clientId },
@@ -2609,8 +2970,8 @@ async function maybeRunAuthCommand() {
   process.exit(0);
 }
 function prompt(rl, question) {
-  return new Promise((resolve2) => {
-    rl.question(question, (answer) => resolve2(answer.trim()));
+  return new Promise((resolve3) => {
+    rl.question(question, (answer) => resolve3(answer.trim()));
   });
 }
 function openBrowser(url) {
@@ -2698,7 +3059,7 @@ function saveToEnv(vars) {
   }
 }
 async function waitForOAuthCallback(clientId, clientSecret) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const server2 = createServer(
       async (req, res) => {
         const url = new URL(req.url ?? "/", `http://localhost:${OAUTH_PORT}`);
@@ -2753,7 +3114,7 @@ async function waitForOAuthCallback(clientId, clientSecret) {
             "<html><body><h2>Success!</h2><p>You can close this tab and return to the terminal.</p></body></html>"
           );
           server2.close();
-          resolve2({ refreshToken: tokenData.refresh_token });
+          resolve3({ refreshToken: tokenData.refresh_token });
         } catch (err) {
           res.writeHead(500, { "Content-Type": "text/html" });
           res.end(
@@ -2788,7 +3149,7 @@ async function runGoogleAuthFlow() {
   });
   try {
     console.log("Step 1: Developer token");
-    console.log("  (Found in Google Ads \u2192 Tools \u2192 API Center)\n");
+    console.log("  (Found in Google Ads \u2192 Admin \u2192 API Center, or https://ads.google.com/aw/apicenter)\n");
     const developerToken = await prompt(rl, "  Developer token: ");
     if (!developerToken) {
       console.error("\n  Developer token is required.");
@@ -2876,10 +3237,10 @@ console.error(
   apiKey ? `API key: ${apiKeyResult.source}` : "API key: not configured \u2014 KB tools will not be available"
 );
 console.error(
-  metaTokenResult.value ? `Meta token: ${metaTokenResult.source}` : "Meta token: not configured \u2014 Meta tools will return errors when called"
+  metaTokenResult.value ? `Meta token: ${metaTokenResult.source}` : "Meta token: not configured (optional \u2014 KB works without it)"
 );
 console.error(
-  googleAdsResult.configured ? `Google Ads: configured` : `Google Ads: not configured (missing: ${googleAdsResult.missing.join(", ")}) \u2014 run \`npx mobile-growth-mcp auth google\` to set up`
+  googleAdsResult.configured ? `Google Ads: configured` : `Google Ads: not configured (optional \u2014 KB works without it). Run \`npx mobile-growth-mcp auth google\` to set up`
 );
 var server = new McpServer({
   name: "mobile-growth-mcp",
@@ -2921,6 +3282,7 @@ registerGetGoogleAdsAssets(server);
 registerGetGoogleAdsInsights(server);
 registerGetGoogleAdsNetworkMix(server);
 registerGetGoogleAdsAssetFatigue(server);
+registerUploadGoogleImageAssets(server);
 registerConnectionStatus(server, status);
 registerVocabularyResource(server);
 registerInstructionsResource(server, status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-growth-mcp",
-  "version": "2.2.1",
+  "version": "2.3.4",
   "description": "MCP server for mobile growth & UA knowledge base — campaign optimization, creative strategy, and subscription app insights",
   "type": "module",
   "main": "dist/index.js",