pabal-web-mcp 1.3.7 → 1.3.9

package/dist/bin/mcp-server.js

@@ -212,7 +212,7 @@ var asoToPublicTool = {
   name: "aso-to-public",
   description: `Converts ASO data from pullData to public/products/[slug]/ structure.
 
-**IMPORTANT:** The 'slug' parameter is REQUIRED. If the user does not provide a slug, you MUST ask them to provide it. This tool processes only ONE product at a time.
+**IMPORTANT:** Always use 'search-app' tool first to resolve the exact slug before calling this tool. The user may provide an approximate name, bundleId, or packageName - search-app will find and return the correct slug. Never pass user input directly as slug.
 
 This tool:
 1. Loads ASO data from .aso/pullData/products/[slug]/store/ (path from ~/.config/pabal-mcp/config.json dataDir)
@@ -665,7 +665,7 @@ var publicToAsoTool = {
   name: "public-to-aso",
   description: `Prepares ASO data from public/products/[slug]/ to pushData format.
 
-**IMPORTANT:** The 'slug' parameter is REQUIRED. If the user does not provide a slug, you MUST ask them to provide it. This tool processes only ONE product at a time.
+**IMPORTANT:** Always use 'search-app' tool first to resolve the exact slug before calling this tool. The user may provide an approximate name, bundleId, or packageName - search-app will find and return the correct slug. Never pass user input directly as slug.
 
 This tool:
 1. Loads ASO data from public/products/[slug]/config.json + locales/
@@ -1727,7 +1727,7 @@ var improvePublicTool = {
   name: "improve-public",
   description: `Optimizes locale JSON in public/products/[slug]/locales for ASO.
 
-**IMPORTANT:** The 'slug' parameter is REQUIRED. If the user does not provide a slug, you MUST ask them to provide it. This tool processes only ONE product at a time.
+**IMPORTANT:** Always use 'search-app' tool first to resolve the exact slug before calling this tool. The user may provide an approximate name, bundleId, or packageName - search-app will find and return the correct slug. Never pass user input directly as slug.
 
 **CRITICAL: Only processes existing locale files. Does NOT create new locale files.**
 - Only improves locales that already exist in public/products/[slug]/locales/
@@ -2378,10 +2378,8 @@ Writing style reference for ${locale}: Found ${posts.length} existing post(s) us
 // src/tools/keyword-research.ts
 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";
+import { z as z7 } from "zod";
+import { zodToJsonSchema as zodToJsonSchema7 } from "zod-to-json-schema";
 
 // src/utils/registered-apps.util.ts
 import fs10 from "fs";
@@ -2415,58 +2413,306 @@ 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). Stored under .aso/keywordResearch/products/[slug]/locales/."
+// src/tools/search-app.ts
+import { z as z6 } from "zod";
+import { zodToJsonSchema as zodToJsonSchema6 } from "zod-to-json-schema";
+var TOOL_NAME = "search-app";
+var searchAppInputSchema = z6.object({
+  query: z6.string().trim().optional().describe(
+    "Search term (slug, bundleId, packageName, name). Returns all apps if empty."
   ),
-  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(
+  store: z6.enum(["all", "appStore", "googlePlay"]).default("all").describe("Store filter (default: all)")
+});
+var jsonSchema6 = zodToJsonSchema6(searchAppInputSchema, {
+  name: "SearchAppInput",
+  $refStrategy: "none"
+});
+var inputSchema6 = jsonSchema6.definitions?.SearchAppInput || jsonSchema6;
+var searchAppTool = {
+  name: TOOL_NAME,
+  description: `Search registered apps from registered-apps.json.
+
+- Called without query: Returns all app list
+- Called with query: Search by slug, bundleId, packageName, name
+- Use store filter to narrow results to appStore or googlePlay only`,
+  inputSchema: inputSchema6
+};
+function matchesQuery(app, query) {
+  const lowerQuery = query.toLowerCase();
+  if (app.slug.toLowerCase().includes(lowerQuery)) return true;
+  if (app.name?.toLowerCase().includes(lowerQuery)) return true;
+  if (app.appStore?.bundleId?.toLowerCase().includes(lowerQuery)) return true;
+  if (app.appStore?.name?.toLowerCase().includes(lowerQuery)) return true;
+  if (app.googlePlay?.packageName?.toLowerCase().includes(lowerQuery))
+    return true;
+  if (app.googlePlay?.name?.toLowerCase().includes(lowerQuery)) return true;
+  return false;
+}
+function filterByStore(apps, store) {
+  if (store === "all") return apps;
+  return apps.filter((app) => {
+    if (store === "appStore") return !!app.appStore;
+    if (store === "googlePlay") return !!app.googlePlay;
+    return true;
+  });
+}
+function formatAppInfo(app) {
+  const lines = [];
+  lines.push(`\u{1F4F1} **${app.name || app.slug}** (\`${app.slug}\`)`);
+  if (app.appStore) {
+    lines.push(`   \u{1F34E} App Store: \`${app.appStore.bundleId || "N/A"}\``);
+    if (app.appStore.appId) {
+      lines.push(`      App ID: ${app.appStore.appId}`);
+    }
+    if (app.appStore.name) {
+      lines.push(`      Name: ${app.appStore.name}`);
+    }
+  }
+  if (app.googlePlay) {
+    lines.push(
+      `   \u{1F916} Google Play: \`${app.googlePlay.packageName || "N/A"}\``
+    );
+    if (app.googlePlay.name) {
+      lines.push(`      Name: ${app.googlePlay.name}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function handleSearchApp(input) {
+  const { query, store = "all" } = input;
+  try {
+    const { apps: allApps, path: configPath } = loadRegisteredApps();
+    let results;
+    if (!query) {
+      results = allApps;
+    } else {
+      const { app: exactMatch } = findRegisteredApp(query);
+      const partialMatches = allApps.filter((app) => matchesQuery(app, query));
+      const seenSlugs = /* @__PURE__ */ new Set();
+      results = [];
+      if (exactMatch && !seenSlugs.has(exactMatch.slug)) {
+        results.push(exactMatch);
+        seenSlugs.add(exactMatch.slug);
+      }
+      for (const app of partialMatches) {
+        if (!seenSlugs.has(app.slug)) {
+          results.push(app);
+          seenSlugs.add(app.slug);
+        }
+      }
+    }
+    results = filterByStore(results, store);
+    if (results.length === 0) {
+      const message = query ? `No apps found matching "${query}".` : "No apps registered.";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `\u274C ${message}
+
+\u{1F4A1} Register apps in ${configPath}`
+          }
+        ],
+        _meta: { apps: [], count: 0, configPath }
+      };
+    }
+    const header = query ? `\u{1F50D} Search results for "${query}": ${results.length} app(s)` : `\u{1F4CB} Registered app list: ${results.length} app(s)`;
+    const appList = results.map(formatAppInfo).join("\n\n");
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${header}
+
+${appList}
+
+---
+Config: ${configPath}`
+        }
+      ],
+      _meta: { apps: results, count: results.length, configPath }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `\u274C App search failed: ${message}`
+        }
+      ]
+    };
+  }
+}
+
+// src/tools/keyword-research.ts
+var TOOL_NAME2 = "keyword-research";
+var keywordResearchInputSchema = z7.object({
+  slug: z7.string().trim().describe("Product slug"),
+  locale: z7.string().trim().describe("Locale code (e.g., en-US, ko-KR). Used for storage under .aso/keywordResearch/products/[slug]/locales/."),
+  platform: z7.enum(["ios", "android"]).default("ios").describe("Store to target ('ios' or 'android'). Run separately per platform."),
+  country: z7.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([]),
-  competitorApps: z6.array(
-    z6.object({
-      appId: z6.string().trim().describe("App ID (package name or iOS ID/bundle)"),
-      platform: z6.enum(["ios", "android"])
+  seedKeywords: z7.array(z7.string().trim()).default([]).describe("Seed keywords to start from."),
+  competitorApps: z7.array(
+    z7.object({
+      appId: z7.string().trim().describe("App ID (package name or iOS ID/bundle)"),
+      platform: z7.enum(["ios", "android"])
     })
-  ).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)")
+  ).default([]).describe("Known competitor apps to probe."),
+  filename: z7.string().trim().optional().describe("Override output filename. Defaults to keyword-research-[platform]-[country].json"),
+  writeTemplate: z7.boolean().default(false).describe("If true, write a JSON template at the output path."),
+  researchData: z7.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: z7.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)."
+  )
 });
-var jsonSchema6 = zodToJsonSchema6(keywordResearchInputSchema, {
+var jsonSchema7 = zodToJsonSchema7(keywordResearchInputSchema, {
   name: "KeywordResearchInput",
   $refStrategy: "none"
 });
-var inputSchema6 = jsonSchema6.definitions?.KeywordResearchInput || jsonSchema6;
+var inputSchema7 = jsonSchema7.definitions?.KeywordResearchInput || jsonSchema7;
 var keywordResearchTool = {
-  name: TOOL_NAME,
-  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
+  name: TOOL_NAME2,
+  description: `Prep + persist keyword research ahead of improve-public using mcp-appstore outputs.
+
+**IMPORTANT:** Always use 'search-app' tool first to resolve the exact slug before calling this tool. The user may provide an approximate name, bundleId, or packageName - search-app will find and return the correct slug. Never pass user input directly as slug.
+
+**Locale coverage:** If the product ships multiple locales, run this tool SEPARATELY for EVERY locale (including non-primary markets). Do NOT rely on "template-only" coverage for secondary locales\u2014produce a full keyword research file per locale.
+
+**Platform coverage:** Use search-app results to confirm supported platforms/locales (App Store + Google Play). Run this tool for EVERY supported platform/locale combination\u2014ios + android runs are separate.
+
+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.`,
+  inputSchema: inputSchema7
 };
+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: [
+        "1. SETUP: Start mcp-appstore server (node server.js in external-tools/mcp-appstore).",
+        "2. APP IDENTITY: get_app_details(appId) \u2192 confirm exact app name, category, current keywords, and store listing quality.",
+        "3. COMPETITOR DISCOVERY: search_app(term=seed, num=15) + get_similar_apps(appId=your app, num=20) \u2192 identify 5-10 direct competitors (same category, similar size) + 3-5 aspirational competitors (top performers).",
+        "4. COMPETITOR KEYWORD MINING: For top 5 competitors, run suggest_keywords_by_apps \u2192 extract keywords they rank for but you don't.",
+        "5. KEYWORD EXPANSION (run ALL, num=30 each): suggest_keywords_by_seeds (your app name + core features), by_category (your primary category), by_similarity (semantic variations), by_competition (gap analysis), by_search (autocomplete/trending).",
+        "6. KEYWORD SCORING: get_keyword_scores for ALL candidates (50-100 keywords) \u2192 filter by: traffic \u226510, difficulty \u226470, relevance to your app.",
+        "7. REVIEW INTELLIGENCE: analyze_reviews(num=200) + fetch_reviews(num=100) on top 3 competitors \u2192 extract: user pain points, feature requests, emotional language, native phrases users actually use.",
+        "8. KEYWORD CATEGORIZATION: Group into tiers - Tier1 (3-5): high traffic (\u22651000), high relevance, moderate difficulty (\u226450); Tier2 (5-7): medium traffic (100-1000), exact feature match; Tier3 (5-8): longtail (<100 traffic), very low difficulty (\u226430), high conversion intent.",
+        "9. LOCALIZATION CHECK: Verify keywords are natural in target locale - avoid direct translations, prefer native expressions found in reviews.",
+        "10. GAP ANALYSIS: Compare your current keywords vs competitor keywords \u2192 identify missed opportunities and over-saturated terms to avoid.",
+        "11. VALIDATION: For final 15-20 keywords, ensure each has: score data, clear user intent, natural locale fit, and specific rationale for inclusion.",
+        "Keep rationale/nextActions in English by default unless you intentionally localize them."
+      ],
+      selectionCriteria: {
+        tier1_core: "High traffic (\u22651000), relevance score \u22650.8, difficulty \u226450, brand-safe",
+        tier2_feature: "Medium traffic (100-1000), exact feature/benefit match, difficulty \u226460",
+        tier3_longtail: "Low traffic (<100), very low difficulty (\u226430), high purchase/download intent phrases",
+        avoid: "Generic terms (difficulty \u226580), irrelevant categories, competitor brand names, terms with no search volume"
+      },
+      qualityChecks: [
+        "Each keyword has traffic + difficulty scores (no gaps)",
+        "Mix of 3 tiers represented (not all longtail, not all high-competition)",
+        "Keywords validated against actual user language from reviews",
+        "No duplicate semantic meanings (e.g., 'photo edit' and 'edit photo')",
+        "Locale-appropriate phrasing verified"
+      ],
+      note: "Run per platform/country. Target 15-20 keywords per locale with clear tier distribution. Save ALL raw data for audit trail."
+    },
+    data: {
+      raw: {
+        searchApp: [],
+        getAppDetails: [],
+        similarApps: [],
+        keywordSuggestions: {
+          bySeeds: [],
+          byCategory: [],
+          bySimilarity: [],
+          byCompetition: [],
+          bySearchHints: [],
+          byApps: []
+        },
+        keywordScores: [],
+        reviewsAnalysis: [],
+        reviewsRaw: []
+      },
+      summary: {
+        recommendedKeywords: [],
+        keywordsByTier: {
+          tier1_core: [],
+          tier2_feature: [],
+          tier3_longtail: []
+        },
+        competitorInsights: {
+          topCompetitors: [],
+          keywordGaps: [],
+          userLanguagePatterns: []
+        },
+        rationale: "",
+        confidence: {
+          dataQuality: "",
+          localeRelevance: "",
+          competitivePosition: ""
+        },
+        nextActions: [
+          "Feed tiered keywords into improve-public Stage 1 (prioritize Tier1 for title, Tier2-3 for keyword field)",
+          "Monitor keyword rankings post-update",
+          "Re-run research quarterly or after major competitor changes"
+        ]
+      }
+    }
+  };
+}
+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(Boolean);
-  }
-  return raw.split(",").map((k) => k.trim()).filter(Boolean);
-}
-async function callToolJSON(client, name, args) {
-  const result = await client.callTool({ name, arguments: args });
-  const text = result.content?.[0]?.text;
-  if (!text) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
+    return raw.map((k) => k.trim()).filter((k) => k.length > 0);
   }
-}
-function ensureDir(dir) {
-  fs11.mkdirSync(dir, { recursive: true });
+  return raw.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
 }
 async function handleKeywordResearch(input) {
   const {
@@ -2476,28 +2722,44 @@ async function handleKeywordResearch(input) {
     country,
     seedKeywords = [],
     competitorApps = [],
-    serverCwd,
-    serverCommand,
-    numSuggestions = 20
+    filename,
+    writeTemplate = false,
+    researchData,
+    researchDataPath
   } = input;
+  const searchResult = await handleSearchApp({ query: slug, store: "all" });
+  const registeredApps = searchResult._meta?.apps || [];
+  const registeredApp = registeredApps.length > 0 ? registeredApps[0] : void 0;
   const { config, locales } = loadProductLocales(slug);
   const primaryLocale = resolvePrimaryLocale(config, locales);
+  const productLocales = Object.keys(locales);
+  const remainingLocales = productLocales.filter((loc) => loc !== locale);
   const primaryLocaleData = locales[primaryLocale];
-  const { app: registeredApp } = findRegisteredApp(slug);
-  const resolvedCountry = country || (locale.includes("-") ? locale.split("-")[1].toLowerCase() : "us");
+  const { supportedLocales, path: supportedPath } = getSupportedLocalesForSlug(slug, platform);
+  const appStoreLocales = registeredApp?.appStore?.supportedLocales || [];
+  const googlePlayLocales = registeredApp?.googlePlay?.supportedLocales || [];
+  const declaredPlatforms = [
+    registeredApp?.appStore ? "ios" : null,
+    registeredApp?.googlePlay ? "android" : null
+  ].filter(Boolean);
   const autoSeeds = [];
-  if (primaryLocaleData?.aso?.title) autoSeeds.push(primaryLocaleData.aso.title);
+  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 (registeredApp?.name) autoSeeds.push(registeredApp.name);
-  if (platform === "ios" && registeredApp?.appStore?.name)
-    autoSeeds.push(registeredApp.appStore.name);
-  if (platform === "android" && registeredApp?.googlePlay?.name)
-    autoSeeds.push(registeredApp.googlePlay.name);
-  const seeds = Array.from(/* @__PURE__ */ new Set([...seedKeywords, ...autoSeeds])).slice(0, 10);
-  const autoCompetitors = [];
+  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 });
@@ -2514,320 +2776,224 @@ async function handleKeywordResearch(input) {
         platform
       });
     }
-  } else {
-    if (config?.packageName) {
-      autoCompetitors.push({ appId: config.packageName, platform });
-    } else if (registeredApp?.googlePlay?.packageName) {
-      autoCompetitors.push({
-        appId: registeredApp.googlePlay.packageName,
-        platform
-      });
-    }
-  }
-  const competitors = Array.from(
-    new Map(
-      [...competitorApps, ...autoCompetitors].map((c) => [
-        `${c.platform}:${c.appId}`,
-        c
-      ])
-    ).values()
-  ).slice(0, 5);
-  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"]).`
-    );
+  } 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 transport = new StdioClientTransport({ command: cmd, args, cwd });
-  const client = new Client(
-    { name: "keyword-research", version: "1.0.0" },
-    { capabilities: { tools: {} } }
+  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
   );
-  await client.connect(transport);
-  const raw = {
-    searchApp: [],
-    getAppDetails: [],
-    similarApps: [],
-    searchAppFallbackApps: [],
-    keywordSuggestions: {
-      bySeeds: [],
-      byCategory: [],
-      bySimilarity: [],
-      byCompetition: [],
-      bySearchHints: [],
-      byApps: []
-    },
-    keywordScores: [],
-    reviewsAnalysis: [],
-    reviewsRaw: []
+  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 fallbackAppIds = [];
-  for (const term of seeds.slice(0, 3)) {
-    const res = await callToolJSON(client, "search_app", {
-      term,
+  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,
-      num: 20,
-      country: resolvedCountry
+      country: resolvedCountry,
+      seedKeywords: resolvedSeeds,
+      competitorApps: resolvedCompetitors
     });
-    raw.searchApp.push({
-      query: term,
+    outputPath = saveJsonFile({ researchDir, fileName, payload });
+    fileAction = researchData ? "Saved provided researchData" : "Wrote template";
+  }
+  const templatePreview = JSON.stringify(
+    buildTemplate({
+      slug,
+      locale,
       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));
-    });
+      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 (declaredPlatforms.length > 0) {
+    lines.push(`Supported platforms (search-app): ${declaredPlatforms.join(", ")}`);
+  } else {
+    lines.push("Supported platforms (search-app): none detected\u2014update registered-apps.json");
   }
-  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,
-      platform: comp.platform,
-      country: resolvedCountry
-    });
-    raw.getAppDetails.push(res);
+  if (appStoreLocales.length > 0) {
+    lines.push(`Declared App Store locales: ${appStoreLocales.join(", ")}`);
   }
-  const firstCompId = competitors[0]?.appId || raw.searchAppFallbackApps[0];
-  if (firstCompId) {
-    const res = await callToolJSON(client, "get_similar_apps", {
-      appId: firstCompId,
-      platform,
-      num: 10,
-      country: resolvedCountry
-    });
-    raw.similarApps = res?.similarApps || res || [];
+  if (googlePlayLocales.length > 0) {
+    lines.push(`Declared Google Play locales: ${googlePlayLocales.join(", ")}`);
   }
-  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
-      },
-      "bySeeds"
-    ],
-    [
-      "suggest_keywords_by_category",
-      firstComp ? {
-        appId: firstComp,
-        platform,
-        num: numSuggestions,
-        country: resolvedCountry
-      } : null,
-      "byCategory"
-    ],
-    [
-      "suggest_keywords_by_similarity",
-      firstComp ? {
-        appId: firstComp,
-        platform,
-        num: numSuggestions,
-        country: resolvedCountry
-      } : null,
-      "bySimilarity"
-    ],
-    [
-      "suggest_keywords_by_competition",
-      firstComp ? {
-        appId: firstComp,
-        platform,
-        num: numSuggestions,
-        country: resolvedCountry
-      } : null,
-      "byCompetition"
-    ],
-    [
-      "suggest_keywords_by_search",
-      {
-        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,
-      "byApps"
-    ]
-  ];
-  for (const [tool, args2, key] of suggestCalls) {
-    if (!args2) continue;
-    const res = await callToolJSON(client, tool, args2);
-    const suggestions = res?.suggestions || res || [];
-    raw.keywordSuggestions[key] = suggestions;
-  }
-  for (const comp of competitors.slice(0, 2)) {
-    const analysis = await callToolJSON(client, "analyze_reviews", {
-      appId: comp.appId,
-      platform: comp.platform,
-      country: resolvedCountry,
-      num: 150
-    });
-    raw.reviewsAnalysis.push(analysis);
-    const rawReviews = await callToolJSON(client, "fetch_reviews", {
-      appId: comp.appId,
-      platform: comp.platform,
-      country: resolvedCountry,
-      num: 80
-    });
-    raw.reviewsRaw.push(rawReviews);
+  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}).`
+    );
   }
-  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;
-    if (Array.isArray(arr)) {
-      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 (productLocales.length > 0) {
+    lines.push(
+      `Existing product locales (${productLocales.length}): ${productLocales.join(", ")}`
+    );
+    lines.push(
+      "MANDATORY: Run FULL keyword research (mcp-appstore workflow) for EVERY locale above\u2014no template-only coverage for secondary markets."
+    );
+    if (remainingLocales.length > 0) {
+      lines.push(
+        `After finishing ${locale}, immediately queue runs for: ${remainingLocales.join(", ")}`
+      );
     }
-  };
-  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));
+    if (declaredPlatforms.length > 1) {
+      lines.push(
+        "Also run separate FULL keyword research for each supported platform (e.g., ios + android) across all locales."
+      );
     }
-  });
-  const candidates = Array.from(candidateSet).slice(0, 30);
-  for (const kw of candidates) {
-    const res = await callToolJSON(client, "get_keyword_scores", {
-      keyword: kw,
-      platform,
-      country: resolvedCountry
-    });
-    raw.keywordScores.push(res);
   }
-  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;
-    return {
-      keyword: s.keyword || s?.scores?.keyword,
-      trafficScore,
-      difficultyScore,
-      raw: s
-    };
-  }).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,
-    recommendedDetails: recommended.map((r) => ({
-      keyword: r.keyword,
-      trafficScore: r.trafficScore,
-      difficultyScore: r.difficultyScore
-    })),
-    rationale: rationaleText,
-    nextActions: nextActionsText
-  };
-  await client.close();
-  const researchDir = path11.join(
-    getKeywordResearchDir(),
-    "products",
-    slug,
-    "locales",
-    locale
+  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("## Research Workflow (mcp-appstore)");
+  lines.push("");
+  lines.push("### Phase 1: Setup & Discovery");
+  lines.push(
+    `1) Start mcp-appstore server: node server.js (cwd: external-tools/mcp-appstore)`
+  );
+  lines.push(
+    `2) get_app_details(appId) \u2192 confirm app identity, category, current metadata`
+  );
+  lines.push(
+    `3) search_app(term=seed, num=15, platform=${platform}, country=${resolvedCountry}) \u2192 find direct competitors`
+  );
+  lines.push(
+    `4) get_similar_apps(appId=your app, num=20) \u2192 discover related apps in your space`
+  );
+  lines.push("");
+  lines.push("### Phase 2: Keyword Mining (run ALL of these)");
+  lines.push(
+    `5) suggest_keywords_by_apps(apps=[top 5 competitors]) \u2192 steal competitor keywords`
+  );
+  lines.push(
+    `6) suggest_keywords_by_seeds(seeds=[app name, core features], num=30)`
+  );
+  lines.push(
+    `7) suggest_keywords_by_category(category=your primary category, num=30)`
   );
-  ensureDir(researchDir);
-  const fileName = `keyword-research-${platform}-${resolvedCountry}.json`;
-  const outputPath = path11.join(researchDir, fileName);
-  const payload = {
-    meta: {
-      slug,
-      locale,
-      platform,
-      country: resolvedCountry,
-      seedKeywords: seeds,
-      competitorApps: competitors,
-      source: "mcp-appstore",
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    },
-    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: "Generated automatically by keyword-research"
-    },
-    data: { raw, summary }
-  };
-  fs11.writeFileSync(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
-  const lines = [];
-  lines.push(`# keyword-research`);
-  lines.push(`Saved to ${outputPath}`);
   lines.push(
-    `Candidates scored: ${scored.length}, Recommended: ${summary.recommendedKeywords.length}`
+    `8) suggest_keywords_by_similarity + by_competition + by_search (num=30 each)`
   );
-  if (scored.length < 10 || summary.recommendedKeywords.length < 10 || Object.values(raw.keywordSuggestions).some(
-    (arr) => Array.isArray(arr) && arr.length === 0
-  )) {
+  lines.push("");
+  lines.push("### Phase 3: Scoring & Filtering");
+  lines.push(
+    `9) get_keyword_scores for ALL candidates (50-100 keywords) \u2192 get traffic & difficulty`
+  );
+  lines.push(
+    `10) Filter: traffic \u226510, difficulty \u226470, relevant to your app's core value`
+  );
+  lines.push("");
+  lines.push("### Phase 4: User Language Intelligence");
+  lines.push(
+    `11) analyze_reviews(appId=top 3 competitors, num=200) \u2192 sentiment & themes`
+  );
+  lines.push(
+    `12) fetch_reviews(appId=top 3 competitors, num=100) \u2192 extract exact phrases users say`
+  );
+  lines.push(
+    `13) Cross-reference keywords with review language \u2192 validate natural phrasing`
+  );
+  lines.push("");
+  lines.push("### Phase 5: Final Selection");
+  lines.push(
+    `14) Categorize into tiers: Tier1 (3-5 high-traffic core), Tier2 (5-7 feature-match), Tier3 (5-8 longtail)`
+  );
+  lines.push(
+    `15) Validate each keyword has: score, intent, locale fit, inclusion rationale`
+  );
+  lines.push(
+    `16) Save to: ${outputPath}`
+  );
+  lines.push("");
+  lines.push("### Quality Checklist");
+  lines.push("- [ ] 15-20 keywords with complete score data");
+  lines.push("- [ ] All 3 tiers represented (not just longtail)");
+  lines.push("- [ ] Keywords validated against actual review language");
+  lines.push("- [ ] No semantic duplicates");
+  lines.push("- [ ] Locale-appropriate (not direct translations)");
+  if (fileAction) {
+    lines.push(`File: ${fileAction} at ${outputPath}`);
+    if (writeTemplate && !researchData && !researchDataPath) {
+      lines.push(
+        "\u26A0\uFE0F Template is a placeholder\u2014replace with FULL mcp-appstore research results for this locale (no template-only coverage)."
+      );
+    }
+  } else {
     lines.push(
-      `Warning: results look sparse. Add more competitors/seeds and rerun.`
+      `Tip: set writeTemplate=true to create the JSON skeleton at ${outputPath} (still run full research per locale)`
     );
   }
+  lines.push("");
+  lines.push("Suggested JSON shape:");
+  lines.push("```json");
+  lines.push(templatePreview);
+  lines.push("```");
   return {
-    content: [{ type: "text", text: lines.join("\n") }]
+    content: [
+      {
+        type: "text",
+        text: lines.join("\n")
+      }
+    ]
   };
 }
 
@@ -2880,6 +3046,14 @@ var tools = [
     zodSchema: keywordResearchInputSchema,
     handler: handleKeywordResearch,
     category: "ASO Research"
+  },
+  {
+    name: searchAppTool.name,
+    description: searchAppTool.description,
+    inputSchema: searchAppTool.inputSchema,
+    zodSchema: searchAppInputSchema,
+    handler: handleSearchApp,
+    category: "App Management"
   }
 ];
 function getToolDefinitions() {
@@ -2889,7 +3063,8 @@ function getToolDefinitions() {
     improvePublicTool,
     initProjectTool,
     createBlogHtmlTool,
-    keywordResearchTool
+    keywordResearchTool,
+    searchAppTool
   ];
 }
 function getToolHandler(name) {

package/package.json

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