pabal-web-mcp 1.3.5 → 1.3.7

package/dist/bin/mcp-server.js

@@ -2380,6 +2380,8 @@ import fs11 from "fs";
 import path11 from "path";
 import { z as z6 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema6 } from "zod-to-json-schema";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
 // src/utils/registered-apps.util.ts
 import fs10 from "fs";
@@ -2413,45 +2415,28 @@ function findRegisteredApp(slug, filePath) {
   const app = apps.find((a) => a.slug === slug);
   return { app, path: usedPath };
 }
-function getSupportedLocalesForSlug(slug, platform, filePath) {
-  const { app, path: usedPath } = findRegisteredApp(slug, filePath);
-  if (!app) return { supportedLocales: [], path: usedPath };
-  if (platform === "ios") {
-    return {
-      supportedLocales: app.appStore?.supportedLocales || [],
-      path: usedPath
-    };
-  }
-  return {
-    supportedLocales: app.googlePlay?.supportedLocales || [],
-    path: usedPath
-  };
-}
 
 // src/tools/keyword-research.ts
 var TOOL_NAME = "keyword-research";
 var keywordResearchInputSchema = z6.object({
   slug: z6.string().trim().describe("Product slug"),
-  locale: z6.string().trim().describe("Locale code (e.g., en-US, ko-KR). Used for storage under .aso/keywordResearch/products/[slug]/locales/."),
+  locale: z6.string().trim().describe(
+    "Locale code (e.g., en-US, ko-KR). Stored under .aso/keywordResearch/products/[slug]/locales/."
+  ),
   platform: z6.enum(["ios", "android"]).default("ios").describe("Store to target ('ios' or 'android'). Run separately per platform."),
   country: z6.string().length(2).optional().describe(
     "Two-letter store country code. If omitted, derived from locale region (e.g., ko-KR -> kr), else 'us'."
   ),
-  seedKeywords: z6.array(z6.string().trim()).default([]).describe("Seed keywords to start from."),
+  seedKeywords: z6.array(z6.string().trim()).default([]),
   competitorApps: z6.array(
     z6.object({
       appId: z6.string().trim().describe("App ID (package name or iOS ID/bundle)"),
       platform: z6.enum(["ios", "android"])
     })
-  ).default([]).describe("Known competitor apps to probe."),
-  filename: z6.string().trim().optional().describe("Override output filename. Defaults to keyword-research-[platform]-[country].json"),
-  writeTemplate: z6.boolean().default(false).describe("If true, write a JSON template at the output path."),
-  researchData: z6.string().trim().optional().describe(
-    "Optional JSON string with research results (e.g., from mcp-appstore tools). If provided, saves it to the output path."
-  ),
-  researchDataPath: z6.string().trim().optional().describe(
-    "Optional path to a JSON file containing research results. If set, file content is saved to the output path (preferred to avoid escape errors)."
-  )
+  ).default([]),
+  serverCwd: z6.string().trim().optional().describe("Path to mcp-appstore cwd (default: external-tools/mcp-appstore)"),
+  serverCommand: z6.array(z6.string()).optional().describe("Command + args to start mcp-appstore (default: ['node','server.js'])"),
+  numSuggestions: z6.number().int().positive().max(50).default(20).describe("Number of keyword suggestions per strategy (default: 20)")
 });
 var jsonSchema6 = zodToJsonSchema6(keywordResearchInputSchema, {
   name: "KeywordResearchInput",
@@ -2460,328 +2445,10 @@ var jsonSchema6 = zodToJsonSchema6(keywordResearchInputSchema, {
 var inputSchema6 = jsonSchema6.definitions?.KeywordResearchInput || jsonSchema6;
 var keywordResearchTool = {
   name: TOOL_NAME,
-  description: `Prep + persist keyword research ahead of improve-public using mcp-appstore outputs.
-
-Run this before improve-public. It gives a concrete MCP-powered research plan and a storage path under .aso/keywordResearch/products/[slug]/locales/[locale]/. Optionally writes a template or saves raw JSON from mcp-appstore tools.`,
+  description: "Runs mcp-appstore calls to collect 10\u201315 keywords per locale and saves to .aso/keywordResearch/products/[slug]/locales/[locale]/keyword-research-[platform]-[country].json.",
   inputSchema: inputSchema6
 };
-function buildTemplate({
-  slug,
-  locale,
-  platform,
-  country,
-  seedKeywords,
-  competitorApps
-}) {
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  return {
-    meta: {
-      slug,
-      locale,
-      platform,
-      country,
-      seedKeywords,
-      competitorApps,
-      source: "mcp-appstore",
-      updatedAt: timestamp
-    },
-    plan: {
-      steps: [
-        "Start mcp-appstore server (node server.js in external-tools/mcp-appstore).",
-        "Confirm app IDs/locales: get_app_details(appId from config/registered-apps) to lock country/lang and 3\u20135 competitors.",
-        "Discover competitors: search_app(term=seed keyword, num=10\u201320), get_similar_apps(appId=top competitor, num=10).",
-        "Collect candidates (all of these, num=20\u201330): suggest_keywords_by_seeds/by_category/by_similarity/by_competition/by_search; suggest_keywords_by_apps(apps=[top competitors]).",
-        "Score shortlist: get_keyword_scores for 15\u201330 candidates per platform/country.",
-        "Context check: analyze_reviews (num=100\u2013200) and fetch_reviews (num=50\u2013100) on top apps for language/tone cues.",
-        "If keywordSuggestions/similar/reviews are sparse, rerun calls (add more competitors/seeds) until you have 10\u201315 strong keywords.",
-        "For any recommended keyword without scores, rerun get_keyword_scores to fill traffic/difficulty.",
-        "Keep rationale/nextActions in English by default unless you intentionally localize them."
-      ],
-      note: "Run per platform/country. Save raw tool outputs plus curated top keywords (target 10\u201315 per locale: 2\u20133 high-traffic core, 4\u20136 mid-competition, 4\u20136 longtail). Minimum checklist before saving: search_app results present, keywordSuggestions.* NOT empty, keywordScores >= 10 items, recommendedKeywords 10\u201315 items."
-    },
-    data: {
-      raw: {
-        searchApp: [],
-        getAppDetails: [],
-        similarApps: [],
-        keywordSuggestions: {
-          bySeeds: [],
-          byCategory: [],
-          bySimilarity: [],
-          byCompetition: [],
-          bySearchHints: [],
-          byApps: []
-        },
-        keywordScores: [],
-        reviewsAnalysis: [],
-        reviewsRaw: []
-      },
-      summary: {
-        recommendedKeywords: [],
-        rationale: "",
-        nextActions: "Feed 10\u201315 mixed keywords (core/mid/longtail) into improve-public Stage 1."
-      }
-    }
-  };
-}
-function saveJsonFile({
-  researchDir,
-  fileName,
-  payload
-}) {
-  fs11.mkdirSync(researchDir, { recursive: true });
-  const outputPath = path11.join(researchDir, fileName);
-  fs11.writeFileSync(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
-  return outputPath;
-}
 function normalizeKeywords(raw) {
-  if (!raw) return [];
-  if (Array.isArray(raw)) {
-    return raw.map((k) => k.trim()).filter((k) => k.length > 0);
-  }
-  return raw.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
-}
-async function handleKeywordResearch(input) {
-  const {
-    slug,
-    locale,
-    platform = "ios",
-    country,
-    seedKeywords = [],
-    competitorApps = [],
-    filename,
-    writeTemplate = false,
-    researchData,
-    researchDataPath
-  } = input;
-  const { config, locales } = loadProductLocales(slug);
-  const primaryLocale = resolvePrimaryLocale(config, locales);
-  const primaryLocaleData = locales[primaryLocale];
-  const { app: registeredApp, path: registeredPath } = findRegisteredApp(slug);
-  const { supportedLocales, path: supportedPath } = getSupportedLocalesForSlug(slug, platform);
-  const autoSeeds = [];
-  const autoCompetitors = [];
-  if (primaryLocaleData?.aso?.title) {
-    autoSeeds.push(primaryLocaleData.aso.title);
-  }
-  const parsedKeywords = normalizeKeywords(primaryLocaleData?.aso?.keywords);
-  autoSeeds.push(...parsedKeywords.slice(0, 5));
-  if (config?.name) autoSeeds.push(config.name);
-  if (config?.tagline) autoSeeds.push(config.tagline);
-  if (!config?.name && registeredApp?.name) autoSeeds.push(registeredApp.name);
-  if (!primaryLocaleData?.aso?.title) {
-    if (platform === "ios" && registeredApp?.appStore?.name) {
-      autoSeeds.push(registeredApp.appStore.name);
-    }
-    if (platform === "android" && registeredApp?.googlePlay?.name) {
-      autoSeeds.push(registeredApp.googlePlay.name);
-    }
-  }
-  if (platform === "ios") {
-    if (config?.appStoreAppId) {
-      autoCompetitors.push({ appId: String(config.appStoreAppId), platform });
-    } else if (config?.bundleId) {
-      autoCompetitors.push({ appId: config.bundleId, platform });
-    } else if (registeredApp?.appStore?.appId) {
-      autoCompetitors.push({
-        appId: String(registeredApp.appStore.appId),
-        platform
-      });
-    } else if (registeredApp?.appStore?.bundleId) {
-      autoCompetitors.push({
-        appId: registeredApp.appStore.bundleId,
-        platform
-      });
-    }
-  } else if (platform === "android" && config?.packageName) {
-    autoCompetitors.push({ appId: config.packageName, platform });
-  } else if (platform === "android" && registeredApp?.googlePlay?.packageName) {
-    autoCompetitors.push({
-      appId: registeredApp.googlePlay.packageName,
-      platform
-    });
-  }
-  const resolvedSeeds = seedKeywords.length > 0 ? seedKeywords : Array.from(new Set(autoSeeds));
-  const resolvedCompetitors = competitorApps.length > 0 ? competitorApps : autoCompetitors;
-  const resolvedCountry = country || (locale?.includes("-") ? locale.split("-")[1].toLowerCase() : "us");
-  const researchDir = path11.join(
-    getKeywordResearchDir(),
-    "products",
-    slug,
-    "locales",
-    locale
-  );
-  const defaultFileName = `keyword-research-${platform}-${resolvedCountry}.json`;
-  const fileName = filename || defaultFileName;
-  let outputPath = path11.join(researchDir, fileName);
-  let fileAction;
-  const parseJsonWithContext = (text) => {
-    try {
-      return JSON.parse(text);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const match = /position (\d+)/i.exec(message) || /column (\d+)/i.exec(message) || /char (\d+)/i.exec(message);
-      if (match) {
-        const pos = Number(match[1]);
-        const start = Math.max(0, pos - 40);
-        const end = Math.min(text.length, pos + 40);
-        const context = text.slice(start, end);
-        throw new Error(
-          `Failed to parse researchData JSON: ${message}
-Context around ${pos}: ${context}`
-        );
-      }
-      throw new Error(`Failed to parse researchData JSON: ${message}`);
-    }
-  };
-  const loadResearchDataFromPath = (p) => {
-    if (!fs11.existsSync(p)) {
-      throw new Error(`researchDataPath not found: ${p}`);
-    }
-    const raw = fs11.readFileSync(p, "utf-8");
-    return parseJsonWithContext(raw);
-  };
-  if (writeTemplate || researchData) {
-    const payload = researchData ? parseJsonWithContext(researchData) : researchDataPath ? loadResearchDataFromPath(researchDataPath) : buildTemplate({
-      slug,
-      locale,
-      platform,
-      country: resolvedCountry,
-      seedKeywords: resolvedSeeds,
-      competitorApps: resolvedCompetitors
-    });
-    outputPath = saveJsonFile({ researchDir, fileName, payload });
-    fileAction = researchData ? "Saved provided researchData" : "Wrote template";
-  }
-  const templatePreview = JSON.stringify(
-    buildTemplate({
-      slug,
-      locale,
-      platform,
-      country: resolvedCountry,
-      seedKeywords: resolvedSeeds,
-      competitorApps: resolvedCompetitors
-    }),
-    null,
-    2
-  );
-  const lines = [];
-  lines.push(`# Keyword research plan (${slug})`);
-  lines.push(`Locale: ${locale} | Platform: ${platform} | Country: ${resolvedCountry}`);
-  lines.push(`Primary locale detected: ${primaryLocale}`);
-  if (supportedLocales.length > 0) {
-    lines.push(
-      `Registered supported locales (${platform}): ${supportedLocales.join(
-        ", "
-      )} (source: ${supportedPath})`
-    );
-    if (!supportedLocales.includes(locale)) {
-      lines.push(
-        `WARNING: locale ${locale} not in registered supported locales. Confirm this locale or update registered-apps.json.`
-      );
-    }
-  } else {
-    lines.push(
-      `Registered supported locales not found for ${platform} (checked: ${supportedPath}).`
-    );
-  }
-  lines.push(
-    `Seeds: ${resolvedSeeds.length > 0 ? resolvedSeeds.join(", ") : "(none set; add seedKeywords or ensure ASO keywords/title exist)"}`
-  );
-  lines.push(
-    `Competitors (from config if empty): ${resolvedCompetitors.length > 0 ? resolvedCompetitors.map((c) => `${c.platform}:${c.appId}`).join(", ") : "(none set; add competitorApps or set appStoreAppId/bundleId/packageName in config.json)"}`
-  );
-  lines.push("");
-  lines.push("How to run (uses mcp-appstore):");
-  lines.push(
-    `1) Start the local mcp-appstore server for this run: node server.js (cwd: /ABSOLUTE/PATH/TO/pabal-web-mcp/external-tools/mcp-appstore). LLM should start it before calling tools and stop it after, if the client supports process management; otherwise, start/stop manually.`
-  );
-  lines.push(
-    `2) Confirm IDs/locales: get_app_details(appId from config/registered-apps) to lock locale/country and competitor list.`
-  );
-  lines.push(
-    `3) Discover apps: search_app(term=seed, num=10-20, platform=${platform}, country=${resolvedCountry}); get_similar_apps(appId=top competitor, num=10).`
-  );
-  lines.push(
-    `4) Expand keywords (num=20-30 each): suggest_keywords_by_seeds/by_category/by_similarity/by_competition/by_search + suggest_keywords_by_apps(apps=[top competitors]).`
-  );
-  lines.push(
-    `5) Score shortlist: get_keyword_scores for 15\u201330 candidates (note: scores are heuristic per README).`
-  );
-  lines.push(
-    `6) Context check: analyze_reviews (num=100-200) and fetch_reviews (num=50-100) on top apps to harvest native phrasing; keep snippets for improve-public.`
-  );
-  lines.push(
-    `7) Save all raw responses + your final 10\u201315 keywords (mix of core/high-traffic, mid, longtail) to: ${outputPath} (structure mirrors .aso/pullData/.aso/pushData under products/<slug>/locales/<locale>)`
-  );
-  lines.push(
-    `8) If keywordSuggestions/similarApps/reviews are still empty or <10 solid candidates, add more competitors/seeds and rerun the calls above until you reach 10\u201315 strong keywords.`
-  );
-  lines.push(
-    `9) If any recommended keywords lack scores, rerun get_keyword_scores for those items. Keep rationale/nextActions in English by default unless you explicitly want them localized.`
-  );
-  lines.push(
-    `10) Do not finalize until: search_app has results, keywordSuggestions.* have entries, keywordScores >=10 items, recommendedKeywords 10\u201315 items. If missing, rerun the relevant calls.`
-  );
-  if (fileAction) {
-    lines.push(`File: ${fileAction} at ${outputPath}`);
-  } else {
-    lines.push(
-      `Tip: set writeTemplate=true to create the JSON skeleton at ${outputPath}`
-    );
-  }
-  lines.push("");
-  lines.push("Suggested JSON shape:");
-  lines.push("```json");
-  lines.push(templatePreview);
-  lines.push("```");
-  return {
-    content: [
-      {
-        type: "text",
-        text: lines.join("\n")
-      }
-    ]
-  };
-}
-
-// src/tools/keyword-research-runner.ts
-import fs12 from "fs";
-import path12 from "path";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { z as z7 } from "zod";
-import { zodToJsonSchema as zodToJsonSchema7 } from "zod-to-json-schema";
-var TOOL_NAME2 = "keyword-research-runner";
-var keywordResearchRunnerInputSchema = z7.object({
-  slug: z7.string().trim().describe("Product slug"),
-  locale: z7.string().trim().describe("Locale code (e.g., en-US, ko-KR)"),
-  platform: z7.enum(["ios", "android"]).default("ios"),
-  country: z7.string().length(2).optional().describe("Store country (default derived from locale region or 'us')"),
-  seedKeywords: z7.array(z7.string().trim()).default([]),
-  competitorApps: z7.array(
-    z7.object({
-      appId: z7.string().trim(),
-      platform: z7.enum(["ios", "android"])
-    })
-  ).default([]),
-  serverCwd: z7.string().trim().optional().describe("Path to mcp-appstore cwd (default: external-tools/mcp-appstore)"),
-  serverCommand: z7.array(z7.string()).optional().describe(
-    "Command + args to start mcp-appstore (default: ['node','server.js'])"
-  ),
-  numSuggestions: z7.number().int().positive().max(50).default(20).describe("Number of keyword suggestions per strategy (default: 20)")
-});
-var jsonSchema7 = zodToJsonSchema7(keywordResearchRunnerInputSchema, {
-  name: "KeywordResearchRunnerInput",
-  $refStrategy: "none"
-});
-var inputSchema7 = jsonSchema7.definitions?.KeywordResearchRunnerInput || jsonSchema7;
-var keywordResearchRunnerTool = {
-  name: TOOL_NAME2,
-  description: "Automatically call mcp-appstore tools to collect 10\u201315 keywords per locale and save to .aso/keywordResearch/...",
-  inputSchema: inputSchema7
-};
-function normalizeKeywords2(raw) {
   if (!raw) return [];
   if (Array.isArray(raw)) {
     return raw.map((k) => k.trim()).filter(Boolean);
@@ -2799,9 +2466,9 @@ async function callToolJSON(client, name, args) {
   }
 }
 function ensureDir(dir) {
-  fs12.mkdirSync(dir, { recursive: true });
+  fs11.mkdirSync(dir, { recursive: true });
 }
-async function handleKeywordResearchRunner(input) {
+async function handleKeywordResearch(input) {
   const {
     slug,
     locale,
@@ -2815,12 +2482,12 @@ async function handleKeywordResearchRunner(input) {
   } = input;
   const { config, locales } = loadProductLocales(slug);
   const primaryLocale = resolvePrimaryLocale(config, locales);
+  const primaryLocaleData = locales[primaryLocale];
   const { app: registeredApp } = findRegisteredApp(slug);
   const resolvedCountry = country || (locale.includes("-") ? locale.split("-")[1].toLowerCase() : "us");
   const autoSeeds = [];
-  const primaryLocaleData = locales[primaryLocale];
   if (primaryLocaleData?.aso?.title) autoSeeds.push(primaryLocaleData.aso.title);
-  const parsedKeywords = normalizeKeywords2(primaryLocaleData?.aso?.keywords);
+  const parsedKeywords = normalizeKeywords(primaryLocaleData?.aso?.keywords);
   autoSeeds.push(...parsedKeywords.slice(0, 5));
   if (config?.name) autoSeeds.push(config.name);
   if (config?.tagline) autoSeeds.push(config.tagline);
@@ -2837,9 +2504,15 @@ async function handleKeywordResearchRunner(input) {
     } else if (config?.bundleId) {
       autoCompetitors.push({ appId: config.bundleId, platform });
     } else if (registeredApp?.appStore?.appId) {
-      autoCompetitors.push({ appId: String(registeredApp.appStore.appId), platform });
+      autoCompetitors.push({
+        appId: String(registeredApp.appStore.appId),
+        platform
+      });
     } else if (registeredApp?.appStore?.bundleId) {
-      autoCompetitors.push({ appId: registeredApp.appStore.bundleId, platform });
+      autoCompetitors.push({
+        appId: registeredApp.appStore.bundleId,
+        platform
+      });
     }
   } else {
     if (config?.packageName) {
@@ -2859,12 +2532,24 @@ async function handleKeywordResearchRunner(input) {
       ])
     ).values()
   ).slice(0, 5);
-  const cwd = serverCwd || path12.resolve(process.cwd(), "external-tools", "mcp-appstore");
-  const cmd = serverCommand?.[0] || "node";
-  const args = serverCommand?.length ? serverCommand.slice(1) : ["server.js"];
+  const cwd = serverCwd || path11.resolve(process.cwd(), "external-tools", "mcp-appstore");
+  const cmd = serverCommand?.[0] || "npm";
+  const args = serverCommand?.length ? serverCommand.slice(1) : ["start"];
+  if (!fs11.existsSync(cwd)) {
+    throw new Error(
+      `mcp-appstore cwd not found: ${cwd}. Set 'serverCwd' to the absolute path (e.g., /Users/you/pabal-web-mcp/external-tools/mcp-appstore).`
+    );
+  }
+  const serverJsPath = path11.join(cwd, "server.js");
+  const usingNodeServer = cmd === "node" || args.includes("server.js");
+  if (usingNodeServer && !fs11.existsSync(serverJsPath)) {
+    throw new Error(
+      `mcp-appstore server.js not found under ${cwd}. Set 'serverCommand' (e.g., ["npm","start"] or ["node","/abs/path/server.js"]).`
+    );
+  }
   const transport = new StdioClientTransport({ command: cmd, args, cwd });
   const client = new Client(
-    { name: "keyword-research-runner", version: "1.0.0" },
+    { name: "keyword-research", version: "1.0.0" },
     { capabilities: { tools: {} } }
   );
   await client.connect(transport);
@@ -2872,6 +2557,7 @@ async function handleKeywordResearchRunner(input) {
     searchApp: [],
     getAppDetails: [],
     similarApps: [],
+    searchAppFallbackApps: [],
     keywordSuggestions: {
       bySeeds: [],
       byCategory: [],
@@ -2884,6 +2570,7 @@ async function handleKeywordResearchRunner(input) {
     reviewsAnalysis: [],
     reviewsRaw: []
   };
+  const fallbackAppIds = [];
   for (const term of seeds.slice(0, 3)) {
     const res = await callToolJSON(client, "search_app", {
       term,
@@ -2891,8 +2578,19 @@ async function handleKeywordResearchRunner(input) {
       num: 20,
       country: resolvedCountry
     });
-    raw.searchApp.push({ query: term, platform, country: resolvedCountry, results: res?.results ?? res });
+    raw.searchApp.push({
+      query: term,
+      platform,
+      country: resolvedCountry,
+      results: res?.results ?? res
+    });
+    const apps = (res?.results ?? res) || [];
+    apps.slice(0, 5).forEach((app) => {
+      const appId = app?.appId || app?.id;
+      if (appId) fallbackAppIds.push(String(appId));
+    });
   }
+  raw.searchAppFallbackApps = Array.from(new Set(fallbackAppIds));
   for (const comp of competitors.slice(0, 5)) {
     const res = await callToolJSON(client, "get_app_details", {
       appId: comp.appId,
@@ -2901,47 +2599,77 @@ async function handleKeywordResearchRunner(input) {
     });
     raw.getAppDetails.push(res);
   }
-  if (competitors.length > 0) {
-    const first = competitors[0];
+  const firstCompId = competitors[0]?.appId || raw.searchAppFallbackApps[0];
+  if (firstCompId) {
     const res = await callToolJSON(client, "get_similar_apps", {
-      appId: first.appId,
+      appId: firstCompId,
       platform,
       num: 10,
       country: resolvedCountry
     });
     raw.similarApps = res?.similarApps || res || [];
   }
-  const firstComp = competitors[0]?.appId;
-  const appsList = competitors.map((c) => c.appId);
+  const firstComp = firstCompId;
+  const appsList = competitors.length ? competitors.map((c) => c.appId) : raw.searchAppFallbackApps.slice(0, 5);
   const suggestCalls = [
     [
       "suggest_keywords_by_seeds",
-      { keywords: seeds, platform, num: numSuggestions, country: resolvedCountry },
+      {
+        keywords: seeds,
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      },
       "bySeeds"
     ],
     [
       "suggest_keywords_by_category",
-      firstComp ? { appId: firstComp, platform, num: numSuggestions, country: resolvedCountry } : null,
+      firstComp ? {
+        appId: firstComp,
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      } : null,
       "byCategory"
     ],
     [
       "suggest_keywords_by_similarity",
-      firstComp ? { appId: firstComp, platform, num: numSuggestions, country: resolvedCountry } : null,
+      firstComp ? {
+        appId: firstComp,
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      } : null,
       "bySimilarity"
     ],
     [
       "suggest_keywords_by_competition",
-      firstComp ? { appId: firstComp, platform, num: numSuggestions, country: resolvedCountry } : null,
+      firstComp ? {
+        appId: firstComp,
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      } : null,
       "byCompetition"
     ],
     [
       "suggest_keywords_by_search",
-      { keywords: seeds.slice(0, 5), platform, num: numSuggestions, country: resolvedCountry },
+      {
+        keywords: seeds.slice(0, 5),
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      },
       "bySearchHints"
     ],
     [
       "suggest_keywords_by_apps",
-      appsList.length ? { apps: appsList, platform, num: numSuggestions, country: resolvedCountry } : null,
+      appsList.length ? {
+        apps: appsList,
+        platform,
+        num: numSuggestions,
+        country: resolvedCountry
+      } : null,
       "byApps"
     ]
   ];
@@ -2967,6 +2695,23 @@ async function handleKeywordResearchRunner(input) {
     });
     raw.reviewsRaw.push(rawReviews);
   }
+  if (competitors.length === 0 && raw.searchAppFallbackApps.length > 0) {
+    const fb = raw.searchAppFallbackApps[0];
+    const analysis = await callToolJSON(client, "analyze_reviews", {
+      appId: fb,
+      platform,
+      country: resolvedCountry,
+      num: 150
+    });
+    raw.reviewsAnalysis.push(analysis);
+    const rawReviews = await callToolJSON(client, "fetch_reviews", {
+      appId: fb,
+      platform,
+      country: resolvedCountry,
+      num: 80
+    });
+    raw.reviewsRaw.push(rawReviews);
+  }
   const candidateSet = /* @__PURE__ */ new Set();
   const addCandidates = (arr) => {
     if (!arr) return;
@@ -2974,13 +2719,18 @@ async function handleKeywordResearchRunner(input) {
       arr.forEach((v) => {
         if (typeof v === "string") candidateSet.add(v);
         if (v?.keyword) candidateSet.add(String(v.keyword));
-        if (v?.suggestions)
-          addCandidates(v.suggestions);
+        if (v?.suggestions) addCandidates(v.suggestions);
       });
     }
   };
   seeds.forEach((s) => candidateSet.add(s));
   Object.values(raw.keywordSuggestions).forEach((arr) => addCandidates(arr));
+  raw.reviewsAnalysis.forEach((ra) => {
+    const freq = ra?.analysis?.keywordFrequency || ra?.keywordFrequency;
+    if (freq && typeof freq === "object") {
+      addCandidates(Object.keys(freq));
+    }
+  });
   const candidates = Array.from(candidateSet).slice(0, 30);
   for (const kw of candidates) {
     const res = await callToolJSON(client, "get_keyword_scores", {
@@ -2992,7 +2742,9 @@ async function handleKeywordResearchRunner(input) {
   }
   const scored = raw.keywordScores.map((s) => {
     const trafficScore = typeof s?.scores?.traffic?.score === "number" ? s.scores.traffic.score : parseFloat(s?.traffic?.score ?? s?.scores?.traffic?.score ?? "0") || 0;
-    const difficultyScore = typeof s?.scores?.difficulty?.score === "number" ? s.scores.difficulty.score : parseFloat(s?.difficulty?.score ?? s?.scores?.difficulty?.score ?? "0") || 0;
+    const difficultyScore = typeof s?.scores?.difficulty?.score === "number" ? s.scores.difficulty.score : parseFloat(
+      s?.difficulty?.score ?? s?.scores?.difficulty?.score ?? "0"
+    ) || 0;
     return {
       keyword: s.keyword || s?.scores?.keyword,
       trafficScore,
@@ -3001,16 +2753,29 @@ async function handleKeywordResearchRunner(input) {
     };
   }).filter((s) => s.keyword);
   const recommended = scored.sort((a, b) => b.trafficScore - a.trafficScore).slice(0, 15);
+  const recommendedKeywords = recommended.map((r) => r.keyword).filter(Boolean);
+  const top1 = recommended[0];
+  const top3 = recommendedKeywords.slice(0, 3);
+  const rationaleText = top1 && top1.keyword ? `Highest traffic: ${top1.keyword} (traffic ${top1.trafficScore.toFixed(
+    2
+  )}, difficulty ${top1.difficultyScore.toFixed(
+    2
+  )}). Blend core/high-traffic and mid/longtail terms for coverage.` : "Sorted by traffic score (desc). Blend of core/high-traffic and mid/longtail technical terms.";
+  const nextActionsText = recommendedKeywords.length ? `Use top keywords in improve-public Stage 1. Emphasize: ${top3.join(
+    ", "
+  )}. Keep app name in English; target 10\u201315 keywords in keyword fields.` : "Run again to produce at least 10\u201315 keywords, then feed into improve-public Stage 1.";
   const summary = {
-    recommendedKeywords: recommended.map((r) => ({
+    recommendedKeywords,
+    recommendedDetails: recommended.map((r) => ({
       keyword: r.keyword,
       trafficScore: r.trafficScore,
       difficultyScore: r.difficultyScore
     })),
-    rationale: "Sorted by traffic score (desc). Blend of core/high-traffic and mid/longtail technical terms.",
-    nextActions: "Feed top 10\u201315 into improve-public Stage 1. If any sections are empty (suggestions/reviews), add more competitors/seeds and rerun."
+    rationale: rationaleText,
+    nextActions: nextActionsText
   };
-  const researchDir = path12.join(
+  await client.close();
+  const researchDir = path11.join(
     getKeywordResearchDir(),
     "products",
     slug,
@@ -3019,7 +2784,7 @@ async function handleKeywordResearchRunner(input) {
   );
   ensureDir(researchDir);
   const fileName = `keyword-research-${platform}-${resolvedCountry}.json`;
-  const outputPath = path12.join(researchDir, fileName);
+  const outputPath = path11.join(researchDir, fileName);
   const payload = {
     meta: {
       slug,
@@ -3043,21 +2808,24 @@ async function handleKeywordResearchRunner(input) {
         "For any recommended keyword without scores, rerun get_keyword_scores to fill traffic/difficulty.",
         "Keep rationale/nextActions in English by default unless you intentionally localize them."
       ],
-      note: "Generated by keyword-research-runner"
+      note: "Generated automatically by keyword-research"
     },
     data: { raw, summary }
   };
-  fs12.writeFileSync(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
-  await client.close();
+  fs11.writeFileSync(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
   const lines = [];
-  lines.push(`# keyword-research-runner`);
+  lines.push(`# keyword-research`);
   lines.push(`Saved to ${outputPath}`);
   lines.push(
     `Candidates scored: ${scored.length}, Recommended: ${summary.recommendedKeywords.length}`
   );
-  lines.push(
-    `Warnings: rerun if keywordSuggestions are empty or recommended < 10.`
-  );
+  if (scored.length < 10 || summary.recommendedKeywords.length < 10 || Object.values(raw.keywordSuggestions).some(
+    (arr) => Array.isArray(arr) && arr.length === 0
+  )) {
+    lines.push(
+      `Warning: results look sparse. Add more competitors/seeds and rerun.`
+    );
+  }
   return {
     content: [{ type: "text", text: lines.join("\n") }]
   };
@@ -3112,13 +2880,6 @@ var tools = [
     zodSchema: keywordResearchInputSchema,
     handler: handleKeywordResearch,
     category: "ASO Research"
-  },
-  {
-    name: keywordResearchRunnerTool.name,
-    description: keywordResearchRunnerTool.description,
-    inputSchema: keywordResearchRunnerTool.inputSchema,
-    handler: handleKeywordResearchRunner,
-    category: "ASO Research"
   }
 ];
 function getToolDefinitions() {
@@ -3128,7 +2889,6 @@ function getToolDefinitions() {
     improvePublicTool,
     initProjectTool,
     createBlogHtmlTool,
-    keywordResearchRunnerTool,
     keywordResearchTool
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pabal-web-mcp",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "type": "module",
   "description": "MCP server for ASO data management with shared types and utilities",
   "author": "skyu",