mobile-growth-mcp 2.2.4 → 2.3.4

package/dist/index.js

@@ -258,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) {
@@ -420,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,
@@ -449,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
@@ -461,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 += `
@@ -493,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({
@@ -525,6 +530,8 @@ function registerGetMetaInsights(server2) {
     },
     async ({
       ad_account_id,
+      campaign_id,
+      adset_id,
       level,
       fields,
       date_preset,
@@ -539,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) {
@@ -555,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;
         }
@@ -582,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");
@@ -944,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);
@@ -2173,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(
@@ -2455,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
@@ -2689,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();
@@ -2699,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 },
@@ -2752,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) {
@@ -2841,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}`);
@@ -2896,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(
@@ -3064,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.4",
+  "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",