pabal-web-mcp 1.2.3 → 1.3.0

package/dist/bin/mcp-server.js

@@ -1,21 +1,27 @@
 #!/usr/bin/env node
 import {
-  DEFAULT_LOCALE,
-  appStoreToUnified,
+  DEFAULT_APP_SLUG
+} from "../chunk-DLCIXAUB.js";
+import {
+  getKeywordResearchDir,
   getProductsDir,
   getPublicDir,
   getPullDataDir,
   getPushDataDir,
+  loadAsoFromConfig,
+  saveAsoToAsoDir
+} from "../chunk-W62HB2ZL.js";
+import {
+  DEFAULT_LOCALE,
+  appStoreToUnified,
   googlePlayToUnified,
   isAppStoreLocale,
   isAppStoreMultilingual,
   isGooglePlayLocale,
   isGooglePlayMultilingual,
-  loadAsoFromConfig,
-  saveAsoToAsoDir,
   unifiedToAppStore,
   unifiedToGooglePlay
-} from "../chunk-FDI7WF45.js";
+} from "../chunk-BOWRBVVV.js";
 
 // src/bin/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -1189,7 +1195,14 @@ ${json}
 // src/tools/utils/improve-public/generate-aso-prompt.util.ts
 var FIELD_LIMITS_DOC_PATH2 = "docs/aso/ASO_FIELD_LIMITS.md";
 function generatePrimaryOptimizationPrompt(args) {
-  const { slug, category, primaryLocale, localeSections } = args;
+  const {
+    slug,
+    category,
+    primaryLocale,
+    localeSections,
+    keywordResearchByLocale,
+    keywordResearchDirByLocale
+  } = args;
   let prompt = `# ASO Optimization - Stage 1: Primary Locale
 
 `;
@@ -1199,32 +1212,33 @@ function generatePrimaryOptimizationPrompt(args) {
   prompt += `## Task
 
 `;
-  prompt += `Optimize the PRIMARY locale (${primaryLocale}) with keyword research + full ASO field optimization.
+  prompt += `Optimize the PRIMARY locale (${primaryLocale}) using **saved keyword research** + full ASO field optimization.
 
 `;
   prompt += `## Step 1: Keyword Research (${primaryLocale})
 
 `;
-  prompt += `**Strategies** (apply all 5):
-`;
-  prompt += `1. **App Store**: Search top apps in category \u2192 extract keywords from titles/descriptions
-`;
-  prompt += `2. **Description-Based**: Use current shortDescription \u2192 find related ASO keywords
-`;
-  prompt += `3. **Feature-Based**: Identify 2-3 core features \u2192 search feature-specific keywords
-`;
-  prompt += `4. **User Intent**: Research user search patterns for the app's use case
+  const researchSections = keywordResearchByLocale[primaryLocale] || [];
+  const researchDir = keywordResearchDirByLocale[primaryLocale];
+  if (researchSections.length > 0) {
+    prompt += `Use the **saved keyword research below**. Do NOT invent new keywords. Choose the top 10 from the recommended set.
+
 `;
-  prompt += `5. **Competitor**: Analyze 3+ successful apps \u2192 find common keyword patterns
+    prompt += `Saved research:
+${researchSections.join("\n")}
 
 `;
-  prompt += `**Output**: 10 high-performing keywords
+  } else {
+    prompt += `No saved keyword research found at ${researchDir}.
+`;
+    prompt += `**Stop and request action**: Run the 'keyword-research' tool with slug='${slug}', locale='${primaryLocale}', and the appropriate platform/country, then rerun improve-public stage 1.
 
 `;
+  }
   prompt += `## Step 2: Optimize All Fields (${primaryLocale})
 
 `;
-  prompt += `Apply the 10 keywords to ALL fields:
+  prompt += `Apply the selected keywords to ALL fields:
 `;
   prompt += `- \`aso.title\` (\u226430): **"App Name: Primary Keyword"** format (app name in English, keyword in target language, keyword starts with uppercase after the colon)
 `;
@@ -1279,11 +1293,11 @@ function generatePrimaryOptimizationPrompt(args) {
   prompt += `## Output Format
 
 `;
-  prompt += `**1. Keyword Research**
+  prompt += `**1. Keyword Research (from saved data)**
 `;
-  prompt += `   - Query: "[query]" \u2192 Found: [apps] \u2192 Keywords: [list]
+  prompt += `   - Cite file(s) used and list the selected top 10 keywords (no new research)
 `;
-  prompt += `   - Final 10 keywords: [list] with rationale
+  prompt += `   - Rationale: why these 10 were chosen from saved research
 
 `;
   prompt += `**2. Optimized JSON** (complete ${primaryLocale} locale structure)
@@ -1331,6 +1345,8 @@ function generateKeywordLocalizationPrompt(args) {
     targetLocales,
     localeSections,
     optimizedPrimary,
+    keywordResearchByLocale,
+    keywordResearchDirByLocale,
     batchLocales,
     batchIndex,
     totalBatches,
@@ -1374,7 +1390,7 @@ function generateKeywordLocalizationPrompt(args) {
 `;
   prompt += `For EACH target locale in this batch:
 `;
-  prompt += `1. Research 10 language-specific keywords
+  prompt += `1. Use SAVED keyword research (see per-locale data below). Do NOT invent keywords.
 `;
   prompt += `2. Replace keywords in translated content (preserve structure/tone/context)
 `;
@@ -1395,18 +1411,22 @@ ${optimizedPrimary}
   prompt += `## Keyword Research (Per Locale)
 
 `;
-  prompt += `For EACH locale, perform lightweight keyword research:
-`;
-  prompt += `1. **App Store Search**: "[core feature] [lang] \uC571/app" \u2192 top 5 apps
-`;
-  prompt += `2. **Competitor Keywords**: Extract keywords from successful apps in that language
-`;
-  prompt += `3. **Search Trends**: Check what users actually search in that language
+  nonPrimaryLocales.forEach((loc) => {
+    const researchSections = keywordResearchByLocale[loc] || [];
+    const researchDir = keywordResearchDirByLocale[loc];
+    if (researchSections.length > 0) {
+      prompt += `Locale ${loc}: use saved research below. Do NOT invent keywords.
+${researchSections.join(
+        "\n"
+      )}
 
 `;
-  prompt += `**Output**: 10 keywords per locale
+    } else {
+      prompt += `Locale ${loc}: no saved keyword research found at ${researchDir}. Stop and request running 'keyword-research' tool (slug='${slug}', locale='${loc}', platform/country as appropriate\u2014match the store locale), then rerun stage 2.
 
 `;
+    }
+  });
   prompt += `## Keyword Replacement Strategy
 
 `;
@@ -1487,7 +1507,7 @@ ${optimizedPrimary}
 `;
   prompt += `Process EACH locale in this batch sequentially:
 `;
-  prompt += `1. Research 10 keywords for locale
+  prompt += `1. Use saved keyword research (or pause if missing and request keyword-research run)
 `;
   prompt += `2. Replace keywords in ALL fields:
 `;
@@ -1543,11 +1563,11 @@ ${optimizedPrimary}
   prompt += `### Locale [locale-code]:
 
 `;
-  prompt += `**1. Keyword Research**
+  prompt += `**1. Keyword Research (saved)**
 `;
-  prompt += `   - Query: "[query]" \u2192 Keywords: [list]
+  prompt += `   - Cite file(s) used; list selected top 10 keywords (no new research)
 `;
-  prompt += `   - Final 10: [list] with rationale
+  prompt += `   - Rationale: why these were chosen from saved research
 
 `;
   prompt += `**2. Updated JSON** (complete locale structure with keyword replacements)
@@ -1591,6 +1611,92 @@ ${optimizedPrimary}
   return prompt;
 }
 
+// src/tools/utils/improve-public/load-keyword-research.util.ts
+import fs6 from "fs";
+import path6 from "path";
+function extractRecommended(data) {
+  const summary = data?.summary || data?.data?.summary;
+  const recommended = summary?.recommendedKeywords;
+  if (Array.isArray(recommended)) {
+    return recommended.map(String);
+  }
+  if (typeof recommended === "string") {
+    return [recommended];
+  }
+  return [];
+}
+function extractMeta(data) {
+  const meta = data?.meta || data?.data?.meta || {};
+  return {
+    platform: meta.platform,
+    country: meta.country,
+    seedKeywords: Array.isArray(meta.seedKeywords) ? meta.seedKeywords.map(String) : void 0,
+    competitorApps: Array.isArray(meta.competitorApps) ? meta.competitorApps : void 0
+  };
+}
+function formatEntry(entry) {
+  const { filePath, data } = entry;
+  const recommended = extractRecommended(data);
+  const meta = extractMeta(data);
+  if (data?.parseError) {
+    return `File: ${filePath}
+Parse error: ${data.parseError}
+----`;
+  }
+  const lines = [];
+  lines.push(`File: ${filePath}`);
+  if (meta.platform || meta.country) {
+    lines.push(
+      `Platform: ${meta.platform || "unknown"} | Country: ${meta.country || "unknown"}`
+    );
+  }
+  if (meta.seedKeywords?.length) {
+    lines.push(`Seeds: ${meta.seedKeywords.join(", ")}`);
+  }
+  if (meta.competitorApps?.length) {
+    const competitors = meta.competitorApps.map((c) => `${c.platform || "?"}:${c.appId || "?"}`).join(", ");
+    lines.push(`Competitors: ${competitors}`);
+  }
+  if (recommended.length) {
+    lines.push(`Recommended keywords (${recommended.length}): ${recommended.join(", ")}`);
+  } else {
+    lines.push("Recommended keywords: (not provided)");
+  }
+  lines.push("----");
+  return lines.join("\n");
+}
+function loadKeywordResearchForLocale(slug, locale) {
+  const researchDir = path6.join(
+    getKeywordResearchDir(),
+    "products",
+    slug,
+    "locales",
+    locale
+  );
+  if (!fs6.existsSync(researchDir)) {
+    return { entries: [], sections: [], researchDir };
+  }
+  const files = fs6.readdirSync(researchDir).filter((file) => file.endsWith(".json"));
+  const entries = [];
+  for (const file of files) {
+    const filePath = path6.join(researchDir, file);
+    try {
+      const raw = fs6.readFileSync(filePath, "utf-8");
+      const data = JSON.parse(raw);
+      entries.push({ filePath, data });
+    } catch (err) {
+      entries.push({
+        filePath,
+        data: {
+          parseError: err instanceof Error ? err.message : "Unknown parse error"
+        }
+      });
+    }
+  }
+  const sections = entries.map(formatEntry);
+  return { entries, sections, researchDir };
+}
+
 // src/tools/improve-public.ts
 var FIELD_LIMITS_DOC_PATH3 = "docs/aso/ASO_FIELD_LIMITS.md";
 var toJsonSchema3 = zodToJsonSchema3;
@@ -1707,12 +1813,21 @@ async function handleImprovePublic(input) {
       })
     );
   }
+  const keywordResearchByLocale = {};
+  const keywordResearchDirByLocale = {};
+  for (const loc of targetLocales) {
+    const research = loadKeywordResearchForLocale(slug, loc);
+    keywordResearchByLocale[loc] = research.sections;
+    keywordResearchDirByLocale[loc] = research.researchDir;
+  }
   const baseArgs = {
     slug,
     category,
     primaryLocale,
     targetLocales,
-    localeSections
+    localeSections,
+    keywordResearchByLocale,
+    keywordResearchDirByLocale
   };
   if (stage === "1" || stage === "both") {
     const prompt = generatePrimaryOptimizationPrompt(baseArgs);
@@ -1758,6 +1873,8 @@ async function handleImprovePublic(input) {
         primaryLocale: baseArgs.primaryLocale,
         targetLocales: baseArgs.targetLocales,
         localeSections: baseArgs.localeSections,
+        keywordResearchByLocale: baseArgs.keywordResearchByLocale,
+        keywordResearchDirByLocale: baseArgs.keywordResearchDirByLocale,
         optimizedPrimary,
         batchLocales,
         batchIndex: currentBatchIndex,
@@ -1780,13 +1897,13 @@ async function handleImprovePublic(input) {
 }
 
 // src/tools/init-project.ts
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path7 from "path";
 import { z as z4 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema4 } from "zod-to-json-schema";
 var listSlugDirs = (dir) => {
-  if (!fs6.existsSync(dir)) return [];
-  return fs6.readdirSync(dir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
+  if (!fs7.existsSync(dir)) return [];
+  return fs7.readdirSync(dir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name);
 };
 var initProjectInputSchema = z4.object({
   slug: z4.string().trim().optional().describe(
@@ -1811,7 +1928,7 @@ Steps:
   inputSchema: inputSchema4
 };
 async function handleInitProject(input) {
-  const pullDataDir = path6.join(getPullDataDir(), "products");
+  const pullDataDir = path7.join(getPullDataDir(), "products");
   const publicDir = getProductsDir();
   const pullDataSlugs = listSlugDirs(pullDataDir);
   const publicSlugs = listSlugDirs(publicDir);
@@ -1889,14 +2006,14 @@ async function handleInitProject(input) {
 }
 
 // src/tools/create-blog-html.ts
-import fs8 from "fs";
-import path8 from "path";
+import fs9 from "fs";
+import path9 from "path";
 import { z as z5 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema5 } from "zod-to-json-schema";
 
 // src/utils/blog.util.ts
-import fs7 from "fs";
-import path7 from "path";
+import fs8 from "fs";
+import path8 from "path";
 var DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 var BLOG_ROOT = "blogs";
 var removeDiacritics = (value) => value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "");
@@ -1984,13 +2101,13 @@ function resolveTargetLocales(input) {
   return fallback ? [fallback] : [];
 }
 function getBlogOutputPaths(options) {
-  const baseDir = path7.join(
+  const baseDir = path8.join(
     options.publicDir,
     BLOG_ROOT,
     options.appSlug,
     options.slug
   );
-  const filePath = path7.join(baseDir, `${options.locale}.html`);
+  const filePath = path8.join(baseDir, `${options.locale}.html`);
   const publicBasePath = toPublicBlogBase(options.appSlug, options.slug);
   return { baseDir, filePath, publicBasePath };
 }
@@ -2015,18 +2132,18 @@ function findExistingBlogPosts({
   publicDir,
   limit = 2
 }) {
-  const blogAppDir = path7.join(publicDir, BLOG_ROOT, appSlug);
-  if (!fs7.existsSync(blogAppDir)) {
+  const blogAppDir = path8.join(publicDir, BLOG_ROOT, appSlug);
+  if (!fs8.existsSync(blogAppDir)) {
     return [];
   }
   const posts = [];
-  const subdirs = fs7.readdirSync(blogAppDir, { withFileTypes: true });
+  const subdirs = fs8.readdirSync(blogAppDir, { withFileTypes: true });
   for (const subdir of subdirs) {
     if (!subdir.isDirectory()) continue;
-    const localeFile = path7.join(blogAppDir, subdir.name, `${locale}.html`);
-    if (!fs7.existsSync(localeFile)) continue;
+    const localeFile = path8.join(blogAppDir, subdir.name, `${locale}.html`);
+    if (!fs8.existsSync(localeFile)) continue;
     try {
-      const htmlContent = fs7.readFileSync(localeFile, "utf-8");
+      const htmlContent = fs8.readFileSync(localeFile, "utf-8");
       const { meta, body } = parseBlogHtml(htmlContent);
       if (meta && meta.locale === locale) {
         posts.push({
@@ -2052,9 +2169,6 @@ function findExistingBlogPosts({
   }));
 }
 
-// src/constants/blog.constants.ts
-var DEFAULT_APP_SLUG = "developer";
-
 // src/tools/create-blog-html.ts
 var toJsonSchema4 = zodToJsonSchema5;
 var DATE_REGEX2 = /^\d{4}-\d{2}-\d{2}$/;
@@ -2172,7 +2286,7 @@ async function handleCreateBlogHtml(input) {
   }
   const output = {
     slug,
-    baseDir: path8.join(publicDir, "blogs", appSlug, slug),
+    baseDir: path9.join(publicDir, "blogs", appSlug, slug),
     files: [],
     coverImage: coverImage && coverImage.trim().length > 0 ? coverImage.trim() : `/products/${appSlug}/og-image.png`,
     metaByLocale: {}
@@ -2186,7 +2300,7 @@ async function handleCreateBlogHtml(input) {
     })
   );
   const existing = plannedFiles.filter(
-    ({ filePath }) => fs8.existsSync(filePath)
+    ({ filePath }) => fs9.existsSync(filePath)
   );
   if (existing.length > 0 && !overwrite) {
     const existingList = existing.map((f) => f.filePath).join("\n- ");
@@ -2195,7 +2309,7 @@ async function handleCreateBlogHtml(input) {
 - ${existingList}`
     );
   }
-  fs8.mkdirSync(output.baseDir, { recursive: true });
+  fs9.mkdirSync(output.baseDir, { recursive: true });
   for (const locale of targetLocales) {
     const { filePath } = getBlogOutputPaths({
       appSlug,
@@ -2221,7 +2335,7 @@ async function handleCreateBlogHtml(input) {
       meta,
       content
     });
-    fs8.writeFileSync(filePath, html, "utf-8");
+    fs9.writeFileSync(filePath, html, "utf-8");
     output.files.push({ locale, path: filePath });
   }
   const summaryLines = [
@@ -2257,6 +2371,243 @@ Writing style reference for ${locale}: Found ${posts.length} existing post(s) us
   };
 }
 
+// src/tools/keyword-research.ts
+import fs10 from "fs";
+import path10 from "path";
+import { z as z6 } from "zod";
+import { zodToJsonSchema as zodToJsonSchema6 } from "zod-to-json-schema";
+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/."),
+  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."),
+  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."
+  )
+});
+var jsonSchema6 = zodToJsonSchema6(keywordResearchInputSchema, {
+  name: "KeywordResearchInput",
+  $refStrategy: "none"
+});
+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.`,
+  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 (npm start in external-tools/mcp-appstore).",
+        "Discover competitors: search_app(term=seed keyword), get_similar_apps(appId=known competitor).",
+        "Collect candidates: suggest_keywords_by_seeds, suggest_keywords_by_category, suggest_keywords_by_similarity, suggest_keywords_by_competition.",
+        "Score shortlist: get_keyword_scores for 15\u201330 candidates per platform/country.",
+        "Context check: analyze_reviews on top apps for language/tone cues."
+      ],
+      note: "Run per platform/country. Save raw tool outputs plus curated top keywords."
+    },
+    data: {
+      raw: {
+        searchApp: [],
+        keywordSuggestions: {
+          bySeeds: [],
+          byCategory: [],
+          bySimilarity: [],
+          byCompetition: [],
+          bySearchHints: []
+        },
+        keywordScores: [],
+        reviewsAnalysis: []
+      },
+      summary: {
+        recommendedKeywords: [],
+        rationale: "",
+        nextActions: "Feed top 10\u201315 into improve-public Stage 1."
+      }
+    }
+  };
+}
+function saveJsonFile({
+  researchDir,
+  fileName,
+  payload
+}) {
+  fs10.mkdirSync(researchDir, { recursive: true });
+  const outputPath = path10.join(researchDir, fileName);
+  fs10.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
+  } = input;
+  const { config, locales } = loadProductLocales(slug);
+  const primaryLocale = resolvePrimaryLocale(config, locales);
+  const primaryLocaleData = locales[primaryLocale];
+  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 (platform === "ios") {
+    if (config?.appStoreAppId) {
+      autoCompetitors.push({ appId: String(config.appStoreAppId), platform });
+    } else if (config?.bundleId) {
+      autoCompetitors.push({ appId: config.bundleId, platform });
+    }
+  } else if (platform === "android" && config?.packageName) {
+    autoCompetitors.push({ appId: config.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 = path10.join(
+    getKeywordResearchDir(),
+    "products",
+    slug,
+    "locales",
+    locale
+  );
+  const defaultFileName = `keyword-research-${platform}-${resolvedCountry}.json`;
+  const fileName = filename || defaultFileName;
+  let outputPath = path10.join(researchDir, fileName);
+  let fileAction;
+  if (writeTemplate || researchData) {
+    const payload = researchData ? (() => {
+      try {
+        return JSON.parse(researchData);
+      } catch (err) {
+        throw new Error(
+          `Failed to parse researchData JSON: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    })() : 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}`);
+  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) Discover apps: search_app(term=seed, platform=${platform}, country=${country}); get_similar_apps(appId=known competitor).`
+  );
+  lines.push(
+    `3) Expand keywords: suggest_keywords_by_seeds, suggest_keywords_by_category, suggest_keywords_by_similarity, suggest_keywords_by_competition, suggest_keywords_by_search.`
+  );
+  lines.push(
+    `4) Score shortlist: get_keyword_scores for 15\u201330 candidates (note: scores are heuristic per README).`
+  );
+  lines.push(
+    `5) Context check: analyze_reviews on top apps to harvest native phrasing; keep snippets for improve-public.`
+  );
+  lines.push(
+    `6) Save all raw responses + your final top 10\u201315 keywords to: ${outputPath} (structure mirrors .aso/pullData/.aso/pushData under products/<slug>/locales/<locale>)`
+  );
+  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/index.ts
 var tools = [
   {
@@ -2298,6 +2649,14 @@ var tools = [
     zodSchema: createBlogHtmlInputSchema,
     handler: handleCreateBlogHtml,
     category: "Content"
+  },
+  {
+    name: keywordResearchTool.name,
+    description: keywordResearchTool.description,
+    inputSchema: keywordResearchTool.inputSchema,
+    zodSchema: keywordResearchInputSchema,
+    handler: handleKeywordResearch,
+    category: "ASO Research"
   }
 ];
 function getToolDefinitions() {
@@ -2306,7 +2665,8 @@ function getToolDefinitions() {
     publicToAsoTool,
     improvePublicTool,
     initProjectTool,
-    createBlogHtmlTool
+    createBlogHtmlTool,
+    keywordResearchTool
   ];
 }
 function getToolHandler(name) {