mobile-growth-mcp 2.0.3 → 2.0.8

package/README.md

@@ -12,7 +12,26 @@ You'll need an API key — get one from the person who set up your account.
 
 ## Setup
 
-Add this to your MCP client config (Claude Desktop, Cursor, Claude Code, Codex, etc.):
+There are three ways to provide your API key and Meta token. The server checks them in this order:
+
+### Option 1: CLI arguments
+
+Pass keys directly in the `args` array. Works with every MCP client.
+
+```json
+{
+  "mcpServers": {
+    "mobile-growth": {
+      "command": "npx",
+      "args": ["-y", "mobile-growth-mcp", "--api-key=me_your-api-key", "--meta-token=your-meta-access-token"]
+    }
+  }
+}
+```
+
+### Option 2: Environment variables
+
+Use the `env` block in your MCP client config.
 
 ```json
 {
@@ -29,7 +48,18 @@ Add this to your MCP client config (Claude Desktop, Cursor, Claude Code, Codex,
 }
 ```
 
-- `API_KEY` (required) — authenticates with the knowledge base. You'll get this when your account is created.
+### Option 3: `.env` file
+
+Create a `.env` file in your working directory:
+
+```
+API_KEY=me_your-api-key
+META_ACCESS_TOKEN=your-meta-access-token
+```
+
+### Keys
+
+- `API_KEY` — authenticates with the knowledge base. Without it, the server still starts but only Meta tools are available. Call the `connection_status` tool to see what's connected.
 - `META_ACCESS_TOKEN` (optional) — enables Meta Marketing API tools. Without it, knowledge base tools still work.
 
 ## What you get
@@ -44,6 +74,7 @@ Add this to your MCP client config (Claude Desktop, Cursor, Claude Code, Codex,
 
 | Tool | Description |
 |------|-------------|
+| `connection_status` | Check KB and Meta API connection status; shows how to fix issues |
 | `search_insights` | Semantic + keyword hybrid search across curated insights |
 | `get_insight` | Full content of a specific insight by slug or ID |
 | `get_meta_campaigns` | List campaigns with objectives, budgets, bid strategies |

package/dist/index.js

@@ -83,16 +83,7 @@ function jsonSchemaToZodShape(inputSchema) {
   }
   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;
-  }
+function registerFetchedTools(server2, apiKey2, tools) {
   for (const tool of tools) {
     const zodShape = jsonSchemaToZodShape(tool.inputSchema);
     server2.tool(tool.name, tool.description, zodShape, async (args) => {
@@ -124,17 +115,8 @@ async function getRemotePrompt(apiKey2, name, args) {
   }
   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) {
+function registerFetchedPrompts(server2, apiKey2, prompts) {
+  for (const prompt of prompts) {
     const zodShape = {};
     for (const arg of prompt.arguments) {
       let field = z.string().describe(arg.description);
@@ -729,26 +711,26 @@ function registerGetMetaAdFatigue(server2) {
           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 status2 = "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";
+            status2 = "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";
+            status2 = "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";
+            status2 = "WARNING";
             diagnosis = `High frequency (${avgFreq.toFixed(1)}) \u2014 approaching saturation [ds-pt-003]. CPA ${cpaRising ? "rising" : "stable"}.`;
           } else if (ctrDeclining) {
-            status = "WARNING";
+            status2 = "WARNING";
             diagnosis = `CTR declining ${ctrDecline.toFixed(0)}% from peak \u2014 early fatigue signal [wk-tw-001 #4].`;
           } else if (medFreq && cpaRising) {
-            status = "WARNING";
+            status2 = "WARNING";
             diagnosis = `Frequency ${avgFreq.toFixed(1)} + CPA trending up ${cpaChange.toFixed(0)}% \u2014 monitor closely [wk-tw-001 #1].`;
           }
           results.push({
@@ -762,7 +744,7 @@ function registerGetMetaAdFatigue(server2) {
             early_cpa: earlyCpa,
             recent_cpa: recentCpa,
             cpa_change_pct: cpaChange,
-            status,
+            status: status2,
             diagnosis
           });
         }
@@ -837,6 +819,58 @@ ${text}`;
   );
 }
 
+// src/tools/connection-status.ts
+function registerConnectionStatus(server2, status2) {
+  server2.tool(
+    "connection_status",
+    "Check the connection status of the knowledge base and Meta API. Call this if tools seem missing or you get unexpected errors.",
+    {},
+    async () => {
+      const lines = ["# Connection Status", ""];
+      if (status2.kb.connected) {
+        lines.push(
+          `## Knowledge Base: Connected`,
+          `- ${status2.kb.toolCount} KB tools loaded`,
+          `- ${status2.kb.promptCount} prompts loaded`,
+          `- API key source: ${status2.apiKey.source}`
+        );
+      } else {
+        lines.push(
+          `## Knowledge Base: Not Connected`,
+          `- Reason: ${status2.kb.error ?? "API_KEY not configured"}`,
+          "",
+          "### How to fix",
+          "Provide your API key using one of these methods (in priority order):",
+          "1. CLI argument: add `--api-key=me_...` to the args array in your MCP config",
+          '2. Environment variable: add `"API_KEY": "me_..."` to the env block in your MCP config',
+          "3. `.env` file: create a `.env` file in your working directory with `API_KEY=me_...`"
+        );
+      }
+      lines.push("");
+      if (status2.meta.tokenConfigured) {
+        lines.push(
+          "## Meta Marketing API: Configured",
+          "- Meta tools are available and ready to use"
+        );
+      } else {
+        lines.push(
+          "## Meta Marketing API: Not Configured",
+          "- Meta tools will return an error when called",
+          "",
+          "### How to fix",
+          "Provide your Meta access token using one of these methods:",
+          "1. CLI argument: add `--meta-token=...` to the args array",
+          '2. Environment variable: add `"META_ACCESS_TOKEN": "..."` to the env block',
+          "3. `.env` file: add `META_ACCESS_TOKEN=...` to your `.env` file"
+        );
+      }
+      return {
+        content: [{ type: "text", text: lines.join("\n") }]
+      };
+    }
+  );
+}
+
 // ../shared/dist/types.js
 var VALID_PLATFORMS = [
   "meta",
@@ -1042,7 +1076,35 @@ Lists all topic tags, applies_to tags, and platforms with counts.
 - 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) {
+function buildStatusSection(status2) {
+  if (!status2) return "";
+  const lines = ["\n## Connection Status\n"];
+  if (status2.kb.connected) {
+    lines.push(
+      `- **Knowledge Base**: Connected (${status2.kb.toolCount} tools, ${status2.kb.promptCount} prompts)`
+    );
+  } else {
+    lines.push(
+      `- **Knowledge Base**: Not connected \u2014 ${status2.kb.error ?? "API_KEY not configured"}`
+    );
+    lines.push(
+      "  - Fix: provide your API key via `--api-key=me_...` CLI arg, `API_KEY` env var, or `.env` file"
+    );
+  }
+  if (status2.meta.tokenConfigured) {
+    lines.push("- **Meta Marketing API**: Token configured");
+  } else {
+    lines.push(
+      "- **Meta Marketing API**: Token not configured \u2014 Meta tools will return errors"
+    );
+    lines.push(
+      "  - Fix: provide your token via `--meta-token=...` CLI arg, `META_ACCESS_TOKEN` env var, or `.env` file"
+    );
+  }
+  return lines.join("\n");
+}
+function registerInstructionsResource(server2, status2) {
+  const text = INSTRUCTIONS + buildStatusSection(status2);
   server2.resource(
     "instructions",
     "instructions://getting-started",
@@ -1055,34 +1117,126 @@ function registerInstructionsResource(server2) {
         {
           uri: "instructions://getting-started",
           mimeType: "text/plain",
-          text: INSTRUCTIONS
+          text
         }
       ]
     })
   );
 }
 
-// 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);
+// src/config.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+function parseEnvFile(path) {
+  let content;
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return {};
+  }
+  const vars = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}
+function getCliArg(name) {
+  const prefix = `--${name}=`;
+  for (const arg of process.argv) {
+    if (arg.startsWith(prefix)) {
+      return arg.slice(prefix.length).trim();
+    }
+  }
+  return void 0;
+}
+var dotEnvCache;
+function getDotEnv() {
+  if (!dotEnvCache) {
+    dotEnvCache = parseEnvFile(join(process.cwd(), ".env"));
+  }
+  return dotEnvCache;
+}
+function resolve(envName, cliName) {
+  const cli = getCliArg(cliName);
+  if (cli) return { value: cli, source: `--${cliName} argument` };
+  const env = process.env[envName]?.trim();
+  if (env) return { value: env, source: `${envName} env var` };
+  const dotenv = getDotEnv()[envName];
+  if (dotenv) return { value: dotenv, source: ".env file" };
+  return { value: void 0, source: "not configured" };
 }
+function resolveApiKey() {
+  return resolve("API_KEY", "api-key");
+}
+function resolveMetaToken() {
+  return resolve("META_ACCESS_TOKEN", "meta-token");
+}
+
+// src/index.ts
+var apiKeyResult = resolveApiKey();
+var metaTokenResult = resolveMetaToken();
+if (apiKeyResult.value) process.env.API_KEY = apiKeyResult.value;
+if (metaTokenResult.value) process.env.META_ACCESS_TOKEN = metaTokenResult.value;
+var apiKey = apiKeyResult.value;
+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"
+);
 var server = new McpServer({
   name: "mobile-growth-mcp",
   version: "2.0.0"
 });
-console.error("Connecting to knowledge base...");
-await registerRemoteTools(server, apiKey);
+var status = {
+  kb: { connected: false, toolCount: 0, promptCount: 0 },
+  meta: { tokenConfigured: !!metaTokenResult.value },
+  apiKey: { source: apiKeyResult.source }
+};
+if (apiKey) {
+  console.error("Connecting to knowledge base...");
+  try {
+    const tools = await fetchRemoteTools(apiKey);
+    registerFetchedTools(server, apiKey, tools);
+    status.kb.toolCount = tools.length;
+    status.kb.connected = true;
+    console.error(`KB connected: ${tools.length} tools loaded`);
+  } catch (err) {
+    const msg = err.message;
+    status.kb.error = msg;
+    console.error(`KB tools failed: ${msg}`);
+  }
+} else {
+  status.kb.error = "API_KEY not configured";
+}
 registerGetMetaCampaigns(server);
 registerGetMetaAdSets(server);
 registerGetMetaAds(server);
 registerGetMetaInsights(server);
 registerGetMetaAdFatigue(server);
+registerConnectionStatus(server, status);
 registerVocabularyResource(server);
-registerInstructionsResource(server);
-await registerRemotePrompts(server, apiKey);
+registerInstructionsResource(server, status);
+if (apiKey) {
+  try {
+    const prompts = await fetchRemotePrompts(apiKey);
+    registerFetchedPrompts(server, apiKey, prompts);
+    status.kb.promptCount = prompts.length;
+    console.error(`KB prompts: ${prompts.length} loaded`);
+  } catch (err) {
+    console.error(
+      `KB prompts failed: ${err.message}`
+    );
+  }
+}
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-growth-mcp",
-  "version": "2.0.3",
+  "version": "2.0.8",
   "description": "MCP server for mobile growth & UA knowledge base — campaign optimization, creative strategy, and subscription app insights",
   "type": "module",
   "main": "dist/index.js",
@@ -33,5 +33,13 @@
     "meta-ads",
     "subscription-apps"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kubachour/mobile-growth-mcp.git"
+  },
+  "homepage": "https://github.com/kubachour/mobile-growth-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/kubachour/mobile-growth-mcp/issues"
+  },
   "license": "MIT"
 }