mobile-growth-mcp 2.0.0

package/dist/index.js

@@ -0,0 +1,1088 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/remote-proxy.ts
+import { z } from "zod";
+var EDGE_FUNCTION_URL = "https://iattgvzqiqrpzoqnrwfr.supabase.co/functions/v1/mcp";
+var nextRequestId = 1;
+async function jsonRpcRequest(apiKey2, method, params) {
+  const body = {
+    jsonrpc: "2.0",
+    method,
+    id: nextRequestId++
+  };
+  if (params) body.params = params;
+  const res = await fetch(EDGE_FUNCTION_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey2,
+      Accept: "application/json"
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Edge Function error (${res.status}): ${text}`);
+  }
+  return await res.json();
+}
+async function fetchRemoteTools(apiKey2) {
+  const resp = await jsonRpcRequest(apiKey2, "tools/list");
+  if (resp.error) {
+    throw new Error(`tools/list error: ${resp.error.message}`);
+  }
+  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
+    };
+  }
+  return {
+    content: resp.result?.content ?? [{ type: "text", text: "No content returned" }],
+    isError: resp.result?.isError
+  };
+}
+function jsonSchemaToZodShape(inputSchema) {
+  const properties = inputSchema.properties ?? {};
+  const required = new Set(inputSchema.required ?? []);
+  const shape = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    let field;
+    if (prop.oneOf) {
+      field = z.union([z.number(), z.string()]);
+    } else if (prop.type === "string") {
+      field = z.string();
+    } else if (prop.type === "number") {
+      field = z.number();
+    } else if (prop.type === "boolean") {
+      field = z.boolean();
+    } else if (prop.type === "array") {
+      field = z.array(z.string());
+    } else {
+      field = z.any();
+    }
+    if (prop.description) {
+      field = field.describe(prop.description);
+    }
+    if (!required.has(key)) {
+      field = field.optional();
+    }
+    shape[key] = field;
+  }
+  return shape;
+}
+async function registerRemoteTools(server2, apiKey2) {
+  let tools;
+  try {
+    tools = await fetchRemoteTools(apiKey2);
+  } catch (err) {
+    console.error(
+      `Failed to fetch remote tools: ${err.message}. KB tools will not be available.`
+    );
+    return;
+  }
+  for (const tool of tools) {
+    const zodShape = jsonSchemaToZodShape(tool.inputSchema);
+    server2.tool(tool.name, tool.description, zodShape, async (args) => {
+      const result = await callRemoteTool(apiKey2, tool.name, args);
+      return {
+        content: result.content.map((c) => ({
+          type: "text",
+          text: c.text
+        })),
+        isError: result.isError
+      };
+    });
+  }
+}
+async function fetchRemotePrompts(apiKey2) {
+  const resp = await jsonRpcRequest(apiKey2, "prompts/list");
+  if (resp.error) {
+    throw new Error(`prompts/list error: ${resp.error.message}`);
+  }
+  return resp.result?.prompts ?? [];
+}
+async function getRemotePrompt(apiKey2, name, args) {
+  const resp = await jsonRpcRequest(apiKey2, "prompts/get", {
+    name,
+    arguments: args
+  });
+  if (resp.error) {
+    throw new Error(`prompts/get error: ${resp.error.message}`);
+  }
+  return resp.result?.messages ?? [];
+}
+async function registerRemotePrompts(server2, apiKey2) {
+  let remotePrompts;
+  try {
+    remotePrompts = await fetchRemotePrompts(apiKey2);
+  } catch (err) {
+    console.error(
+      `Failed to fetch remote prompts: ${err.message}. Prompts will not be available.`
+    );
+    return;
+  }
+  for (const prompt of remotePrompts) {
+    const zodShape = {};
+    for (const arg of prompt.arguments) {
+      let field = z.string().describe(arg.description);
+      if (!arg.required) {
+        field = field.optional();
+      }
+      zodShape[arg.name] = field;
+    }
+    server2.prompt(
+      prompt.name,
+      prompt.description,
+      zodShape,
+      async (args) => {
+        const messages = await getRemotePrompt(
+          apiKey2,
+          prompt.name,
+          args
+        );
+        return {
+          messages: messages.map((m) => ({
+            role: m.role,
+            content: {
+              type: "text",
+              text: m.content.text
+            }
+          }))
+        };
+      }
+    );
+  }
+}
+
+// src/tools/meta-campaigns.ts
+import { z as z2 } from "zod";
+
+// src/meta/client.ts
+var META_API_VERSION = "v21.0";
+var META_BASE_URL = `https://graph.facebook.com/${META_API_VERSION}`;
+var THROTTLE_WARN_THRESHOLD = 75;
+function getMetaAccessToken() {
+  const token = process.env.META_ACCESS_TOKEN;
+  if (!token) {
+    throw new Error(
+      "Missing META_ACCESS_TOKEN environment variable. Provide a Meta Marketing API access token to use Meta tools."
+    );
+  }
+  return token;
+}
+function isMetaApiError(body) {
+  return typeof body === "object" && body !== null && "error" in body && typeof body.error?.message === "string";
+}
+function formatMetaError(err) {
+  const code = err.code;
+  const sub = err.error_subcode;
+  if (code === 190) {
+    return `Authentication error: Access token is invalid or expired. Generate a new token in Meta Business Suite. (code ${code})`;
+  }
+  if (code === 4 || code === 17 || code >= 8e4 && code <= 80099) {
+    return `Rate limit hit: ${err.message}. Wait a few minutes before retrying. (code ${code}${sub ? `/${sub}` : ""})`;
+  }
+  if (code === 100) {
+    return `Invalid parameter: ${err.message} (code ${code}${sub ? `/${sub}` : ""})`;
+  }
+  return `Meta API error: ${err.message} (code ${code}${sub ? `/${sub}` : ""})`;
+}
+function parseThrottleHeader(headers) {
+  const raw = headers.get("x-fb-ads-insights-throttle");
+  if (!raw) return void 0;
+  try {
+    const info = JSON.parse(raw);
+    const maxUtil = Math.max(info.app_id_util_pct, info.acc_id_util_pct);
+    const warning = maxUtil > THROTTLE_WARN_THRESHOLD ? `\u26A0 Meta API utilization at ${maxUtil}% \u2014 approaching rate limit. Slow down requests.` : void 0;
+    return { throttle: info, warning };
+  } catch {
+    return void 0;
+  }
+}
+async function metaApiGet(options) {
+  const token = getMetaAccessToken();
+  const url = new URL(`${META_BASE_URL}${options.path}`);
+  if (options.params) {
+    for (const [key, value] of Object.entries(options.params)) {
+      url.searchParams.set(key, value);
+    }
+  }
+  const response = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  const body = await response.json();
+  if (!response.ok || isMetaApiError(body)) {
+    if (isMetaApiError(body)) {
+      throw new Error(formatMetaError(body.error));
+    }
+    throw new Error(`Meta API returned ${response.status}: ${JSON.stringify(body)}`);
+  }
+  const throttleInfo = parseThrottleHeader(response.headers);
+  return {
+    data: body,
+    throttle: throttleInfo?.throttle,
+    warning: throttleInfo?.warning
+  };
+}
+function activeFilter() {
+  return JSON.stringify([
+    {
+      field: "effective_status",
+      operator: "IN",
+      value: ["ACTIVE"]
+    }
+  ]);
+}
+function getActionValue(actions, actionType) {
+  if (!actions) return 0;
+  const action = actions.find((a) => a.action_type === actionType);
+  return action ? parseFloat(action.value) : 0;
+}
+function getCostPerAction(costPerAction, actionType) {
+  if (!costPerAction) return null;
+  const action = costPerAction.find((a) => a.action_type === actionType);
+  return action ? parseFloat(action.value) : null;
+}
+var DEFAULT_DATE_PRESET = "last_7d";
+var CAMPAIGN_DEFAULT_FIELDS = "id,name,status,effective_status,objective,bid_strategy,daily_budget,lifetime_budget,buying_type,special_ad_categories";
+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";
+
+// src/tools/meta-campaigns.ts
+function registerGetMetaCampaigns(server2) {
+  server2.tool(
+    "get_meta_campaigns",
+    "List campaigns from a Meta ad account. Defaults to active campaigns with lean field set. Returns first page only \u2014 use 'after' cursor for next page.",
+    {
+      ad_account_id: z2.string().describe("Meta ad account ID (e.g. act_123456789)"),
+      fields: z2.string().optional().describe(
+        `Comma-separated fields. Default: ${CAMPAIGN_DEFAULT_FIELDS}`
+      ),
+      effective_status: z2.array(z2.string()).optional().describe(
+        'Filter by status. Default: ["ACTIVE"]. Use ["ACTIVE","PAUSED"] for all non-deleted.'
+      ),
+      limit: z2.number().min(1).max(100).optional().describe("Results per page (default 50, max 100)"),
+      after: z2.string().optional().describe("Pagination cursor from previous response")
+    },
+    async ({ ad_account_id, fields, effective_status, limit, after }) => {
+      try {
+        const params = {
+          fields: fields ?? CAMPAIGN_DEFAULT_FIELDS,
+          limit: String(limit ?? 50)
+        };
+        if (effective_status) {
+          params.filtering = JSON.stringify([
+            {
+              field: "effective_status",
+              operator: "IN",
+              value: effective_status
+            }
+          ]);
+        } else {
+          params.filtering = activeFilter();
+        }
+        if (after) {
+          params.after = after;
+        }
+        const result = await metaApiGet({
+          path: `/${ad_account_id}/campaigns`,
+          params
+        });
+        const campaigns = result.data.data;
+        const nextCursor = result.data.paging?.cursors?.after;
+        let text = `Found ${campaigns.length} campaigns:
+
+`;
+        for (const c of campaigns) {
+          text += `- **${c.name}** (${c.id})
+  Status: ${c.effective_status} | Objective: ${c.objective}` + (c.bid_strategy ? ` | Bid: ${c.bid_strategy}` : "") + (c.daily_budget ? ` | Daily: $${(parseInt(c.daily_budget) / 100).toFixed(2)}` : "") + (c.lifetime_budget ? ` | Lifetime: $${(parseInt(c.lifetime_budget) / 100).toFixed(2)}` : "") + "\n";
+        }
+        if (nextCursor) {
+          text += `
+_More results available. Pass \`after: "${nextCursor}"\` for next page._`;
+        }
+        if (result.warning) {
+          text = `${result.warning}
+
+${text}`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/meta-adsets.ts
+import { z as z3 } from "zod";
+function registerGetMetaAdSets(server2) {
+  server2.tool(
+    "get_meta_adsets",
+    "List ad sets from a Meta ad account, optionally scoped to a campaign. Defaults to active ad sets with lean field set.",
+    {
+      ad_account_id: z3.string().describe("Meta ad account ID (e.g. act_123456789)"),
+      campaign_id: z3.string().optional().describe(
+        "Scope to a specific campaign ID. If provided, fetches ad sets under that campaign."
+      ),
+      fields: z3.string().optional().describe(`Comma-separated fields. Default: ${ADSET_DEFAULT_FIELDS}`),
+      effective_status: z3.array(z3.string()).optional().describe('Filter by status. Default: ["ACTIVE"]'),
+      limit: z3.number().min(1).max(100).optional().describe("Results per page (default 50, max 100)"),
+      after: z3.string().optional().describe("Pagination cursor from previous response")
+    },
+    async ({
+      ad_account_id,
+      campaign_id,
+      fields,
+      effective_status,
+      limit,
+      after
+    }) => {
+      try {
+        const params = {
+          fields: fields ?? ADSET_DEFAULT_FIELDS,
+          limit: String(limit ?? 50)
+        };
+        if (effective_status) {
+          params.filtering = JSON.stringify([
+            {
+              field: "effective_status",
+              operator: "IN",
+              value: effective_status
+            }
+          ]);
+        } else {
+          params.filtering = activeFilter();
+        }
+        if (after) {
+          params.after = after;
+        }
+        const parentPath = campaign_id ? `/${campaign_id}/adsets` : `/${ad_account_id}/adsets`;
+        const result = await metaApiGet({
+          path: parentPath,
+          params
+        });
+        const adsets = result.data.data;
+        const nextCursor = result.data.paging?.cursors?.after;
+        let text = `Found ${adsets.length} ad sets:
+
+`;
+        for (const a of adsets) {
+          text += `- **${a.name}** (${a.id})
+  Campaign: ${a.campaign_id} | Status: ${a.effective_status}` + (a.optimization_goal ? ` | Goal: ${a.optimization_goal}` : "") + (a.bid_strategy ? ` | Bid: ${a.bid_strategy}` : "") + (a.daily_budget ? ` | Daily: $${(parseInt(a.daily_budget) / 100).toFixed(2)}` : "") + "\n";
+        }
+        if (nextCursor) {
+          text += `
+_More results available. Pass \`after: "${nextCursor}"\` for next page._`;
+        }
+        if (result.warning) {
+          text = `${result.warning}
+
+${text}`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/meta-ads.ts
+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.",
+    {
+      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."),
+      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 }) => {
+      try {
+        const params = {
+          fields: fields ?? AD_DEFAULT_FIELDS,
+          limit: String(limit ?? 50)
+        };
+        if (effective_status) {
+          params.filtering = JSON.stringify([
+            {
+              field: "effective_status",
+              operator: "IN",
+              value: effective_status
+            }
+          ]);
+        } else {
+          params.filtering = activeFilter();
+        }
+        if (after) {
+          params.after = after;
+        }
+        const parentPath = adset_id ? `/${adset_id}/ads` : `/${ad_account_id}/ads`;
+        const result = await metaApiGet({
+          path: parentPath,
+          params
+        });
+        const ads = result.data.data;
+        const nextCursor = result.data.paging?.cursors?.after;
+        let text = `Found ${ads.length} ads:
+
+`;
+        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";
+        }
+        if (nextCursor) {
+          text += `
+_More results available. Pass \`after: "${nextCursor}"\` for next page._`;
+        }
+        if (result.warning) {
+          text = `${result.warning}
+
+${text}`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/meta-insights.ts
+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).",
+    {
+      ad_account_id: z5.string().describe("Meta ad account ID (e.g. act_123456789)"),
+      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}`
+      ),
+      date_preset: z5.string().optional().describe(`Date preset (default: ${DEFAULT_DATE_PRESET})`),
+      time_range: z5.object({
+        since: z5.string().describe("Start date YYYY-MM-DD"),
+        until: z5.string().describe("End date YYYY-MM-DD")
+      }).optional().describe("Custom date range. Overrides date_preset if provided."),
+      time_increment: z5.string().optional().describe(
+        'Time granularity: "1" for daily, "7" for weekly, "monthly", or "all_days" (default: aggregated)'
+      ),
+      breakdowns: z5.string().optional().describe(
+        "Comma-separated breakdowns (e.g. age,gender or publisher_platform,platform_position)"
+      ),
+      filtering: z5.string().optional().describe(
+        'JSON filtering array. Default: active only. Pass "[]" to include all statuses.'
+      ),
+      conversion_event: z5.string().optional().describe(
+        "Action type for CPA calculation (default: mobile_app_install)"
+      ),
+      sort: z5.string().optional().describe(
+        'Sort field (e.g. "spend_descending", "impressions_descending")'
+      ),
+      limit: z5.number().min(1).max(500).optional().describe("Results per page (default 50, max 500)"),
+      after: z5.string().optional().describe("Pagination cursor from previous response")
+    },
+    async ({
+      ad_account_id,
+      level,
+      fields,
+      date_preset,
+      time_range,
+      time_increment,
+      breakdowns,
+      filtering,
+      conversion_event,
+      sort,
+      limit,
+      after
+    }) => {
+      try {
+        const convEvent = conversion_event ?? "mobile_app_install";
+        const params = {
+          fields: fields ?? INSIGHT_DEFAULT_FIELDS,
+          level: level ?? "campaign",
+          limit: String(limit ?? 50)
+        };
+        if (time_range) {
+          params.time_range = JSON.stringify(time_range);
+        } else {
+          params.date_preset = date_preset ?? DEFAULT_DATE_PRESET;
+        }
+        if (time_increment) {
+          params.time_increment = time_increment;
+        }
+        if (breakdowns) {
+          params.breakdowns = breakdowns;
+        }
+        if (filtering !== void 0) {
+          params.filtering = filtering === "[]" ? "[]" : filtering;
+        } else {
+          params.filtering = activeFilter();
+        }
+        if (sort) {
+          params.sort = sort;
+        }
+        if (after) {
+          params.after = after;
+        }
+        const result = await metaApiGet({
+          path: `/${ad_account_id}/insights`,
+          params
+        });
+        const rows = result.data.data;
+        const nextCursor = result.data.paging?.cursors?.after;
+        if (!rows || rows.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No insight data returned for the given parameters. Try a broader date range or check that active campaigns exist."
+              }
+            ]
+          };
+        }
+        let text = `**${rows.length} rows** | Level: ${level ?? "campaign"} | Event: ${convEvent}
+
+`;
+        for (const row of rows) {
+          const spend = parseFloat(row.spend || "0");
+          const impressions = parseInt(row.impressions || "0");
+          const conversions = getActionValue(row.actions, convEvent);
+          const cpa = getCostPerAction(row.cost_per_action_type, convEvent);
+          const label = row.ad_name ?? row.adset_name ?? row.campaign_name ?? row.campaign_id ?? "Account";
+          const breakdownParts = [];
+          if (row.age) breakdownParts.push(`Age: ${row.age}`);
+          if (row.gender) breakdownParts.push(`Gender: ${row.gender}`);
+          if (row.publisher_platform)
+            breakdownParts.push(`Platform: ${row.publisher_platform}`);
+          if (row.platform_position)
+            breakdownParts.push(`Position: ${row.platform_position}`);
+          if (row.country) breakdownParts.push(`Country: ${row.country}`);
+          const breakdownStr = breakdownParts.length > 0 ? ` (${breakdownParts.join(", ")})` : "";
+          const dateStr = time_increment && row.date_start !== row.date_stop ? ` [${row.date_start} \u2192 ${row.date_stop}]` : time_increment ? ` [${row.date_start}]` : "";
+          text += `**${label}**${breakdownStr}${dateStr}
+  Spend: $${spend.toFixed(2)} | Impressions: ${impressions.toLocaleString()}` + (row.clicks ? ` | Clicks: ${row.clicks}` : "") + (row.ctr ? ` | CTR: ${row.ctr}%` : "") + (row.cpm ? ` | CPM: $${row.cpm}` : "") + (row.frequency ? ` | Freq: ${row.frequency}` : "") + (conversions > 0 ? ` | ${convEvent}: ${conversions}` : "") + (cpa !== null ? ` | CPA: $${cpa.toFixed(2)}` : "") + "\n\n";
+        }
+        if (nextCursor) {
+          text += `_More results available. Pass \`after: "${nextCursor}"\` for next page._
+`;
+        }
+        if (result.warning) {
+          text = `${result.warning}
+
+${text}`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/meta-ad-fatigue.ts
+import { z as z6 } from "zod";
+function registerGetMetaAdFatigue(server2) {
+  server2.tool(
+    "get_meta_ad_fatigue",
+    "Detect creative fatigue in active ads. Analyzes frequency, CTR decline, and CPA trends over the last 7 days at daily granularity. Grounded in knowledge base insights: wk-tw-001 (diagnostic patterns), ds-pt-003 (frequency thresholds), vs-nt-002 (degraded creative rules).",
+    {
+      ad_account_id: z6.string().describe("Meta ad account ID (e.g. act_123456789)"),
+      campaign_id: z6.string().optional().describe("Scope to a specific campaign"),
+      conversion_event: z6.string().optional().describe("Action type for CPA (default: mobile_app_install)"),
+      frequency_warning: z6.number().optional().describe("Frequency threshold for warning (default: 3)"),
+      frequency_critical: z6.number().optional().describe("Frequency threshold for critical (default: 5)"),
+      ctr_decline_threshold: z6.number().optional().describe(
+        "CTR decline % from peak to flag fatigue (default: 30)"
+      )
+    },
+    async ({
+      ad_account_id,
+      campaign_id,
+      conversion_event,
+      frequency_warning,
+      frequency_critical,
+      ctr_decline_threshold
+    }) => {
+      try {
+        const convEvent = conversion_event ?? "mobile_app_install";
+        const freqWarn = frequency_warning ?? 3;
+        const freqCrit = frequency_critical ?? 5;
+        const ctrThreshold = ctr_decline_threshold ?? 30;
+        const parentPath = campaign_id ? `/${campaign_id}/insights` : `/${ad_account_id}/insights`;
+        const result = await metaApiGet({
+          path: parentPath,
+          params: {
+            level: "ad",
+            time_increment: "1",
+            fields: "ad_id,ad_name,spend,impressions,clicks,ctr,cpm,frequency,actions,cost_per_action_type",
+            date_preset: "last_7d",
+            filtering: activeFilter(),
+            limit: "500"
+          }
+        });
+        const rows = result.data.data;
+        if (!rows || rows.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "No active ad data found for the last 7 days."
+              }
+            ]
+          };
+        }
+        const adMap = /* @__PURE__ */ new Map();
+        for (const row of rows) {
+          const adId = row.ad_id;
+          if (!adMap.has(adId)) {
+            adMap.set(adId, {
+              ad_id: adId,
+              ad_name: row.ad_name ?? adId,
+              days: []
+            });
+          }
+          adMap.get(adId).days.push({
+            date: row.date_start,
+            spend: parseFloat(row.spend || "0"),
+            impressions: parseInt(row.impressions || "0"),
+            clicks: parseInt(row.clicks || "0"),
+            ctr: parseFloat(row.ctr || "0"),
+            cpm: parseFloat(row.cpm || "0"),
+            frequency: parseFloat(row.frequency || "0"),
+            conversions: getActionValue(row.actions, convEvent),
+            cpa: getCostPerAction(row.cost_per_action_type, convEvent)
+          });
+        }
+        const results = [];
+        let totalSpend = 0;
+        for (const ad of adMap.values()) {
+          ad.days.sort(
+            (a, b) => new Date(a.date).getTime() - new Date(b.date).getTime()
+          );
+          const adSpend = ad.days.reduce((s, d) => s + d.spend, 0);
+          totalSpend += adSpend;
+          const avgFreq = ad.days.reduce((s, d) => s + d.frequency, 0) / ad.days.length;
+          const peakCtr = Math.max(...ad.days.map((d) => d.ctr));
+          const last3 = ad.days.slice(-3);
+          const recentCtr = last3.reduce((s, d) => s + d.ctr, 0) / last3.length;
+          const ctrDecline = peakCtr > 0 ? (peakCtr - recentCtr) / peakCtr * 100 : 0;
+          const mid = Math.floor(ad.days.length / 2);
+          const earlyDays = ad.days.slice(0, Math.max(mid, 1));
+          const lateDays = ad.days.slice(mid);
+          const earlyConv = earlyDays.reduce((s, d) => s + d.conversions, 0);
+          const earlySpend = earlyDays.reduce((s, d) => s + d.spend, 0);
+          const earlyCpa = earlyConv > 0 ? earlySpend / earlyConv : null;
+          const lateConv = lateDays.reduce((s, d) => s + d.conversions, 0);
+          const lateSpend = lateDays.reduce((s, d) => s + d.spend, 0);
+          const recentCpa = lateConv > 0 ? lateSpend / lateConv : null;
+          const cpaChange = earlyCpa !== null && recentCpa !== null && earlyCpa > 0 ? (recentCpa - earlyCpa) / earlyCpa * 100 : null;
+          let status = "HEALTHY";
+          let diagnosis = "Metrics stable \u2014 no fatigue detected.";
+          const highFreq = avgFreq >= freqCrit;
+          const medFreq = avgFreq >= freqWarn;
+          const ctrDeclining = ctrDecline >= ctrThreshold;
+          const cpaRising = cpaChange !== null && cpaChange > 20;
+          if (highFreq && cpaRising) {
+            status = "FATIGUED";
+            diagnosis = `Audience saturation: frequency ${avgFreq.toFixed(1)} + CPA rising ${cpaChange.toFixed(0)}% [wk-tw-001 #1, ds-pt-003]`;
+          } else if (ctrDeclining && cpaRising) {
+            status = "FATIGUED";
+            diagnosis = `Creative fatigue: CTR declined ${ctrDecline.toFixed(0)}% from peak + CPA rising ${cpaChange.toFixed(0)}% [wk-tw-001 #4]`;
+          } else if (highFreq) {
+            status = "WARNING";
+            diagnosis = `High frequency (${avgFreq.toFixed(1)}) \u2014 approaching saturation [ds-pt-003]. CPA ${cpaRising ? "rising" : "stable"}.`;
+          } else if (ctrDeclining) {
+            status = "WARNING";
+            diagnosis = `CTR declining ${ctrDecline.toFixed(0)}% from peak \u2014 early fatigue signal [wk-tw-001 #4].`;
+          } else if (medFreq && cpaRising) {
+            status = "WARNING";
+            diagnosis = `Frequency ${avgFreq.toFixed(1)} + CPA trending up ${cpaChange.toFixed(0)}% \u2014 monitor closely [wk-tw-001 #1].`;
+          }
+          results.push({
+            ad_id: ad.ad_id,
+            ad_name: ad.ad_name,
+            total_spend: adSpend,
+            avg_frequency: avgFreq,
+            peak_ctr: peakCtr,
+            recent_ctr: recentCtr,
+            ctr_decline_pct: ctrDecline,
+            early_cpa: earlyCpa,
+            recent_cpa: recentCpa,
+            cpa_change_pct: cpaChange,
+            status,
+            diagnosis
+          });
+        }
+        const statusOrder = { FATIGUED: 0, WARNING: 1, HEALTHY: 2 };
+        results.sort(
+          (a, b) => statusOrder[a.status] - statusOrder[b.status] || b.total_spend - a.total_spend
+        );
+        const fatigued = results.filter((r) => r.status === "FATIGUED");
+        const warning = results.filter((r) => r.status === "WARNING");
+        const healthy = results.filter((r) => r.status === "HEALTHY");
+        const fatiguedSpend = fatigued.reduce((s, r) => s + r.total_spend, 0);
+        const spendConcentration = totalSpend > 0 ? fatiguedSpend / totalSpend * 100 : 0;
+        let text = `# Ad Fatigue Report
+
+`;
+        text += `**${results.length} ads analyzed** | ${fatigued.length} fatigued | ${warning.length} warning | ${healthy.length} healthy
+`;
+        text += `**Total spend:** $${totalSpend.toFixed(2)} | **Fatigued ad spend:** $${fatiguedSpend.toFixed(2)} (${spendConcentration.toFixed(0)}%)
+
+`;
+        if (spendConcentration > 50) {
+          text += `\u26A0 **Over 50% of spend is going to fatigued ads.** Urgent creative rotation needed.
+
+`;
+        }
+        text += `| Status | Ad | Spend | Freq | CTR (peak\u2192recent) | CPA Trend | Diagnosis |
+`;
+        text += `|--------|-----|-------|------|-------------------|-----------|------------|
+`;
+        for (const r of results) {
+          const icon = r.status === "FATIGUED" ? "\u{1F534}" : r.status === "WARNING" ? "\u{1F7E1}" : "\u{1F7E2}";
+          text += `| ${icon} ${r.status} | ${r.ad_name.slice(0, 30)} | $${r.total_spend.toFixed(0)} | ${r.avg_frequency.toFixed(1)} | ${r.peak_ctr.toFixed(2)}%\u2192${r.recent_ctr.toFixed(2)}% (${r.ctr_decline_pct > 0 ? "-" : ""}${r.ctr_decline_pct.toFixed(0)}%) | ${r.cpa_change_pct !== null ? `${r.cpa_change_pct > 0 ? "+" : ""}${r.cpa_change_pct.toFixed(0)}%` : "N/A"} | ${r.diagnosis} |
+`;
+        }
+        text += `
+## Recommendations
+
+`;
+        if (fatigued.length > 0) {
+          text += `### Fatigued Ads (${fatigued.length})
+- **Rotate with genuinely new creative concepts**, not variations. Meta's Andromeda requires at least 25% visual difference to treat it as a new ad [lp-pt-001, oh-li-001].
+- **Change the hook** (first 3 seconds) to access new audience segments [oh-li-005].
+- **Do NOT re-test degraded creatives** \u2014 exhaust all other angles first. Wait 3-6 months before revisiting [vs-nt-002].
+- Meta will auto-shift spend away from degrading creatives [vs-nt-001] \u2014 don't panic-pause, but do prepare replacements.
+
+`;
+        }
+        if (healthy.length > 0) {
+          text += `### Healthy Ads (${healthy.length})
+- Let Meta manage allocation. Don't force spend to low-spend winners \u2014 Meta has determined scaling them would degrade performance [ds-pt-004].
+
+`;
+        }
+        if (result.warning) {
+          text = `${result.warning}
+
+${text}`;
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// ../shared/dist/types.js
+var VALID_PLATFORMS = [
+  "meta",
+  "google",
+  "tiktok",
+  "cross_platform"
+];
+var TOPICS = [
+  "scaling",
+  "creative_strategy",
+  "creative_testing",
+  "creative_iteration",
+  "creative_fatigue",
+  "campaign_architecture",
+  "campaign_structure",
+  "funnel_strategy",
+  "funnel_optimization",
+  "audience_targeting",
+  "bid_strategy",
+  "bidding",
+  "budgeting",
+  "value_rules",
+  "cpi_optimization",
+  "campaign_optimization",
+  "aso",
+  "measurement",
+  "attribution",
+  "signal_engineering",
+  "conversion_events",
+  "pricing",
+  "subscription",
+  "monetization",
+  "paywall_optimization",
+  "ltv_modeling",
+  "onboarding",
+  "advantage_plus",
+  "eac",
+  "web_to_app",
+  "ad_ranking",
+  "meta_ads",
+  "google_ads",
+  "retention",
+  "first_party_data",
+  "surveys",
+  "ai_tools",
+  "automation",
+  "testing_framework",
+  "competitive_analysis",
+  "ad_copy",
+  "conversion_rate",
+  "strategy"
+];
+var APPLIES_TO = [
+  "subscription_apps",
+  "mobile_gaming",
+  "ios",
+  "android",
+  "mobile",
+  "web2app",
+  "web_funnels",
+  "ecommerce",
+  "all"
+];
+
+// src/resources/vocabulary.ts
+function registerVocabularyResource(server2) {
+  server2.resource(
+    "vocabulary",
+    "vocabulary://tags",
+    {
+      description: "Available topic tags, applies_to tags, and platforms for filtering insights. Includes counts from the database.",
+      mimeType: "application/json"
+    },
+    async () => {
+      let topicCounts = {};
+      let appliesToCounts = {};
+      try {
+        const apiKey2 = process.env.API_KEY;
+        if (apiKey2) {
+          const result = await callRemoteTool(apiKey2, "get_vocabulary_counts", {});
+          if (!result.isError && result.content.length > 0) {
+            const counts = JSON.parse(result.content[0].text);
+            topicCounts = counts.topics ?? {};
+            appliesToCounts = counts.applies_to ?? {};
+          }
+        }
+      } catch {
+      }
+      const payload = {
+        topics: TOPICS.map((t) => ({ tag: t, count: topicCounts[t] ?? 0 })),
+        applies_to: APPLIES_TO.map((a) => ({
+          tag: a,
+          count: appliesToCounts[a] ?? 0
+        })),
+        platforms: [...VALID_PLATFORMS]
+      };
+      return {
+        contents: [
+          {
+            uri: "vocabulary://tags",
+            mimeType: "application/json",
+            text: JSON.stringify(payload, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources/instructions.ts
+var INSTRUCTIONS = `# Mobile Growth MCP \u2014 Knowledge Base + Meta Ad Tools
+
+## 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.
+
+## Knowledge Base Tools
+
+### search_insights
+Semantic + keyword hybrid search across the knowledge base.
+- **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.
+- **topic** (optional): Filter by a single topic tag
+- **applies_to** (optional): Filter by a single applies_to value
+
+### get_insight
+Fetch the full content of a specific insight by ID or slug.
+- **id** (required): Numeric ID or string slug (e.g. "mb-li-001")
+
+## 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.
+
+**Rate limit safety**: All tools default to last_7d, active-only, minimal fields. No auto-pagination. Throttle header monitored \u2014 warns at >75% utilization.
+
+### get_meta_campaigns
+List campaigns from a Meta ad account. Defaults to active campaigns.
+- **ad_account_id** (required): e.g. "act_123456789"
+- **fields, effective_status, limit, after** (optional)
+
+### get_meta_adsets
+List ad sets, optionally scoped to a campaign.
+- **ad_account_id** (required)
+- **campaign_id** (optional): Scope to specific campaign
+- **fields, effective_status, limit, after** (optional)
+
+### get_meta_ads
+List ads, optionally scoped to an ad set.
+- **ad_account_id** (required)
+- **adset_id** (optional): Scope to specific ad set
+- **fields, effective_status, limit, after** (optional)
+
+### get_meta_insights
+Pull performance insights with configurable level, breakdowns, date range.
+- **ad_account_id** (required)
+- **level** (optional): account, campaign, adset, ad (default: campaign)
+- **date_preset** (optional): default last_7d
+- **time_range** (optional): {since, until} for custom dates
+- **time_increment** (optional): "1" for daily, "7" for weekly
+- **breakdowns** (optional): e.g. "age,gender" or "publisher_platform,platform_position"
+- **conversion_event** (optional): default "mobile_app_install"
+- **fields, filtering, sort, limit, after** (optional)
+
+### get_meta_ad_fatigue
+Built-in report: detect creative fatigue via frequency, CTR decline, CPA trends.
+- **ad_account_id** (required)
+- **campaign_id** (optional): Scope to specific campaign
+- **conversion_event** (optional): default "mobile_app_install"
+- **frequency_warning** (optional): default 3
+- **frequency_critical** (optional): default 5
+- **ctr_decline_threshold** (optional): default 30%
+
+## Reports (MCP Prompts)
+
+Pre-built analysis workflows. 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 |
+| 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
+Lists all topic tags, applies_to tags, and platforms with counts.
+
+## 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
+`;
+function registerInstructionsResource(server2) {
+  server2.resource(
+    "instructions",
+    "instructions://getting-started",
+    {
+      description: "Getting started guide explaining the knowledge base, Meta API tools, reports, and example queries. Read this first.",
+      mimeType: "text/plain"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "instructions://getting-started",
+          mimeType: "text/plain",
+          text: INSTRUCTIONS
+        }
+      ]
+    })
+  );
+}
+
+// src/index.ts
+var apiKey = process.env.API_KEY;
+if (!apiKey) {
+  console.error(
+    'Error: API_KEY environment variable is required.\nGet your key from the server admin and add it to your MCP config:\n  "env": { "API_KEY": "me_..." }'
+  );
+  process.exit(1);
+}
+var server = new McpServer({
+  name: "mobile-growth-mcp",
+  version: "2.0.0"
+});
+console.error("Connecting to knowledge base...");
+await registerRemoteTools(server, apiKey);
+registerGetMetaCampaigns(server);
+registerGetMetaAdSets(server);
+registerGetMetaAds(server);
+registerGetMetaInsights(server);
+registerGetMetaAdFatigue(server);
+registerVocabularyResource(server);
+registerInstructionsResource(server);
+await registerRemotePrompts(server, apiKey);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "mobile-growth-mcp",
+  "version": "2.0.0",
+  "description": "MCP server for mobile growth & UA knowledge base — campaign optimization, creative strategy, and subscription app insights",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mobile-growth-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@mobile-growth/shared": "*",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "mobile",
+    "growth",
+    "user-acquisition",
+    "meta-ads",
+    "subscription-apps"
+  ],
+  "license": "MIT"
+}