pabal-web-mcp 1.3.9 → 1.3.11

package/dist/bin/mcp-server.js

@@ -1215,13 +1215,30 @@ function generatePrimaryOptimizationPrompt(args) {
   prompt += `Optimize the PRIMARY locale (${primaryLocale}) using **saved keyword research** + full ASO field optimization.
 
 `;
-  prompt += `## Step 1: Keyword Research (${primaryLocale})
+  prompt += `## Step 1: Use Saved Keyword Research (${primaryLocale})
 
 `;
   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 += `**CRITICAL: Use ONLY the saved keyword research below. Do NOT invent or research new keywords.**
+
+`;
+    prompt += `The research data includes:
+`;
+    prompt += `- **Tier 1 (Core):** Use these in title and subtitle - highest traffic, best opportunity
+`;
+    prompt += `- **Tier 2 (Feature):** Use these in keywords field and descriptions
+`;
+    prompt += `- **Tier 3 (Longtail):** Use these in intro, outro, and feature descriptions
+`;
+    prompt += `- **Keyword Details:** Each keyword has traffic/difficulty scores and rationale - use this to prioritize
+`;
+    prompt += `- **Strategy:** Overall optimization strategy based on competitor analysis
+`;
+    prompt += `- **Keyword Gaps:** Opportunities where competitors are weak
+`;
+    prompt += `- **User Language Patterns:** Phrases real users use in reviews - incorporate naturally
 
 `;
     prompt += `Saved research:
@@ -1238,46 +1255,60 @@ ${researchSections.join("\n")}
   prompt += `## Step 2: Optimize All Fields (${primaryLocale})
 
 `;
-  prompt += `Apply the selected keywords to ALL fields:
+  prompt += `**Apply keywords strategically based on tier priority:**
+
+`;
+  prompt += `### Tier 1 Keywords (Core) \u2192 Title & Subtitle
 `;
-  prompt += `- \`aso.title\` (\u226430): **"App Name: Primary Keyword"** format (app name in English, keyword in target language, keyword starts with uppercase after the colon)
+  prompt += `- \`aso.title\` (\u226430): **"App Name: [Tier1 Keyword]"** format
 `;
-  prompt += `  - **Do NOT translate/rename the app name**; keep the original English app name across all locales.
+  prompt += `  - App name in English, keyword in target language, uppercase after colon
 `;
-  prompt += `- \`aso.subtitle\` (\u226430): Complementary keywords
+  prompt += `  - **Do NOT translate/rename the app name**
 `;
-  prompt += `- \`aso.shortDescription\` (\u226480): Primary keywords (no emojis/CAPS)
+  prompt += `- \`aso.subtitle\` (\u226430): Use remaining Tier 1 keywords
 `;
-  prompt += `- \`aso.keywords\` (\u2264100): Comma-separated 10 keywords
+  prompt += `- \`aso.shortDescription\` (\u226480): Tier 1 + Tier 2 keywords (no emojis/CAPS)
+
+`;
+  prompt += `### Tier 2 Keywords (Feature) \u2192 Keywords Field & Descriptions
 `;
-  prompt += `- \`aso.template.intro\` (\u2264300): Keyword-rich, use full length
+  prompt += `- \`aso.keywords\` (\u2264100): ALL tiers, comma-separated (Tier 1 first, then Tier 2, then Tier 3)
 `;
-  prompt += `- \`aso.template.outro\` (\u2264200): Natural keyword integration
+  prompt += `- \`landing.hero.title\`: Tier 1 + Tier 2 keywords
 `;
-  prompt += `- \`landing.hero.title\`: Primary keywords
+  prompt += `- \`landing.hero.description\`: Tier 2 keywords naturally integrated
 `;
-  prompt += `- \`landing.hero.description\`: Keywords if present
+  prompt += `- \`landing.screenshots.images[].title\`: Tier 2 keywords
 `;
-  prompt += `- \`landing.screenshots.images[].title\`: Keywords in screenshot titles
+  prompt += `- \`landing.screenshots.images[].description\`: Tier 2 + Tier 3 keywords
+
 `;
-  prompt += `- \`landing.screenshots.images[].description\`: Keywords in screenshot descriptions
+  prompt += `### Tier 3 Keywords (Longtail) \u2192 Content Sections
 `;
-  prompt += `- \`landing.features.items[].title\`: Keywords in feature titles
+  prompt += `- \`aso.template.intro\` (\u2264300): Tier 2 + Tier 3 keywords, keyword-rich, use full length
 `;
-  prompt += `- \`landing.features.items[].body\`: Keywords in feature descriptions
+  prompt += `- \`aso.template.outro\` (\u2264200): Tier 3 keywords, natural integration
 `;
-  prompt += `- \`landing.reviews.title\`: Keywords if applicable
+  prompt += `- \`landing.features.items[].title\`: Tier 2 keywords
 `;
-  prompt += `- \`landing.reviews.description\`: Keywords if applicable
+  prompt += `- \`landing.features.items[].body\`: Tier 3 keywords with user language patterns
 `;
-  prompt += `- \`landing.cta.headline\`: Keywords if applicable
+  prompt += `- \`landing.reviews.title/description\`: Keywords if applicable
 `;
-  prompt += `- \`landing.cta.description\`: Keywords if applicable
+  prompt += `- \`landing.cta.headline/description\`: Keywords if applicable
+
+`;
+  prompt += `### User Language Integration
+`;
+  prompt += `- Use **User Language Patterns** from research in intro/outro/features
+`;
+  prompt += `- These are actual phrases users search for - incorporate naturally
 
 `;
   prompt += `**Guidelines**: 2.5-3% keyword density, natural flow, cultural appropriateness
 `;
-  prompt += `**CRITICAL**: You MUST include the complete \`landing\` object in your optimized JSON output, with all screenshots, features, reviews, and cta sections properly translated and keyword-optimized.
+  prompt += `**CRITICAL**: You MUST include the complete \`landing\` object in your optimized JSON output.
 
 `;
   prompt += `## Step 3: Validate
@@ -1622,13 +1653,46 @@ 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 recommended.map((item) => {
+      if (typeof item === "object" && item?.keyword) {
+        return {
+          keyword: String(item.keyword),
+          tier: String(item.tier || ""),
+          difficulty: Number(item.difficulty) || 0,
+          traffic: Number(item.traffic) || 0,
+          rationale: String(item.rationale || "")
+        };
+      }
+      if (typeof item === "string") {
+        return { keyword: item, tier: "", difficulty: 0, traffic: 0, rationale: "" };
+      }
+      return null;
+    }).filter((item) => item !== null);
   }
   return [];
 }
+function extractKeywordsByTier(data) {
+  const summary = data?.summary || data?.data?.summary;
+  const byTier = summary?.keywordsByTier || {};
+  const extractKeywords = (tier) => Array.isArray(tier) ? tier.map((k) => typeof k === "object" ? k.keyword : String(k)).filter(Boolean) : [];
+  return {
+    tier1_core: extractKeywords(byTier.tier1_core),
+    tier2_feature: extractKeywords(byTier.tier2_feature),
+    tier3_longtail: extractKeywords(byTier.tier3_longtail)
+  };
+}
+function extractRationale(data) {
+  const summary = data?.summary || data?.data?.summary;
+  return summary?.rationale || "";
+}
+function extractCompetitorInsights(data) {
+  const summary = data?.summary || data?.data?.summary;
+  const insights = summary?.competitorInsights || {};
+  return {
+    keywordGaps: Array.isArray(insights.keywordGaps) ? insights.keywordGaps : [],
+    userLanguagePatterns: Array.isArray(insights.userLanguagePatterns) ? insights.userLanguagePatterns : []
+  };
+}
 function extractMeta(data) {
   const meta = data?.meta || data?.data?.meta || {};
   return {
@@ -1642,31 +1706,170 @@ function formatEntry(entry) {
   const { filePath, data } = entry;
   const recommended = extractRecommended(data);
   const meta = extractMeta(data);
+  const byTier = extractKeywordsByTier(data);
+  const rationale = extractRationale(data);
+  const insights = extractCompetitorInsights(data);
   if (data?.parseError) {
     return `File: ${filePath}
 Parse error: ${data.parseError}
 ----`;
   }
   const lines = [];
-  lines.push(`File: ${filePath}`);
+  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 (byTier.tier1_core.length > 0) {
+    lines.push(`
+**Tier 1 (Core - use in title/subtitle):** ${byTier.tier1_core.join(", ")}`);
+  }
+  if (byTier.tier2_feature.length > 0) {
+    lines.push(`**Tier 2 (Feature - use in keywords field/descriptions):** ${byTier.tier2_feature.join(", ")}`);
+  }
+  if (byTier.tier3_longtail.length > 0) {
+    lines.push(`**Tier 3 (Longtail - use in intro/outro/features):** ${byTier.tier3_longtail.join(", ")}`);
+  }
+  if (recommended.length > 0) {
+    lines.push(`
+**Keyword Details (${recommended.length} keywords):**`);
+    recommended.forEach((kw, idx) => {
+      const tierLabel = kw.tier ? ` [${kw.tier}]` : "";
+      const scores = kw.traffic > 0 || kw.difficulty > 0 ? ` (traffic: ${kw.traffic.toFixed(2)}, difficulty: ${kw.difficulty.toFixed(2)})` : "";
+      lines.push(`${idx + 1}. **${kw.keyword}**${tierLabel}${scores}`);
+      if (kw.rationale) {
+        lines.push(`   \u2192 ${kw.rationale}`);
+      }
+    });
   }
-  if (meta.competitorApps?.length) {
-    const competitors = meta.competitorApps.map((c) => `${c.platform || "?"}:${c.appId || "?"}`).join(", ");
-    lines.push(`Competitors: ${competitors}`);
+  if (rationale) {
+    lines.push(`
+**Strategy:** ${rationale}`);
   }
-  if (recommended.length) {
-    lines.push(`Recommended keywords (${recommended.length}): ${recommended.join(", ")}`);
-  } else {
-    lines.push("Recommended keywords: (not provided)");
+  if (insights.keywordGaps.length > 0) {
+    lines.push(`
+**Keyword Gaps (opportunities):**`);
+    insights.keywordGaps.forEach((gap) => lines.push(`- ${gap}`));
+  }
+  if (insights.userLanguagePatterns.length > 0) {
+    lines.push(`
+**User Language Patterns (from reviews):**`);
+    insights.userLanguagePatterns.forEach((pattern) => lines.push(`- ${pattern}`));
+  }
+  lines.push("\n----");
+  return lines.join("\n");
+}
+function mergeKeywordData(entries) {
+  const merged = {
+    tier1_core: [],
+    tier2_feature: [],
+    tier3_longtail: [],
+    allKeywords: [],
+    rationale: "",
+    keywordGaps: [],
+    userLanguagePatterns: [],
+    platforms: []
+  };
+  const seenKeywords = /* @__PURE__ */ new Set();
+  const seenGaps = /* @__PURE__ */ new Set();
+  const seenPatterns = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (entry.data?.parseError) continue;
+    const meta = extractMeta(entry.data);
+    if (meta.platform && !merged.platforms.includes(meta.platform)) {
+      merged.platforms.push(meta.platform);
+    }
+    const byTier = extractKeywordsByTier(entry.data);
+    byTier.tier1_core.forEach((kw) => {
+      if (!seenKeywords.has(kw.toLowerCase())) {
+        merged.tier1_core.push(kw);
+        seenKeywords.add(kw.toLowerCase());
+      }
+    });
+    byTier.tier2_feature.forEach((kw) => {
+      if (!seenKeywords.has(kw.toLowerCase())) {
+        merged.tier2_feature.push(kw);
+        seenKeywords.add(kw.toLowerCase());
+      }
+    });
+    byTier.tier3_longtail.forEach((kw) => {
+      if (!seenKeywords.has(kw.toLowerCase())) {
+        merged.tier3_longtail.push(kw);
+        seenKeywords.add(kw.toLowerCase());
+      }
+    });
+    const recommended = extractRecommended(entry.data);
+    for (const kw of recommended) {
+      if (!seenKeywords.has(kw.keyword.toLowerCase())) {
+        merged.allKeywords.push(kw);
+        seenKeywords.add(kw.keyword.toLowerCase());
+      }
+    }
+    const rationale = extractRationale(entry.data);
+    if (rationale && !merged.rationale) {
+      merged.rationale = rationale;
+    } else if (rationale && merged.rationale) {
+      merged.rationale += ` | ${meta.platform}: ${rationale}`;
+    }
+    const insights = extractCompetitorInsights(entry.data);
+    insights.keywordGaps.forEach((gap) => {
+      if (!seenGaps.has(gap)) {
+        merged.keywordGaps.push(gap);
+        seenGaps.add(gap);
+      }
+    });
+    insights.userLanguagePatterns.forEach((pattern) => {
+      if (!seenPatterns.has(pattern)) {
+        merged.userLanguagePatterns.push(pattern);
+        seenPatterns.add(pattern);
+      }
+    });
+  }
+  merged.allKeywords.sort((a, b) => b.traffic - a.traffic);
+  return merged;
+}
+function formatMergedData(merged, researchDir) {
+  const lines = [];
+  lines.push(`### Combined Keyword Research (${merged.platforms.join(" + ")})`);
+  lines.push(`Source: ${researchDir}`);
+  if (merged.tier1_core.length > 0) {
+    lines.push(`
+**Tier 1 (Core - use in title/subtitle):** ${merged.tier1_core.join(", ")}`);
+  }
+  if (merged.tier2_feature.length > 0) {
+    lines.push(`**Tier 2 (Feature - use in keywords field/descriptions):** ${merged.tier2_feature.join(", ")}`);
+  }
+  if (merged.tier3_longtail.length > 0) {
+    lines.push(`**Tier 3 (Longtail - use in intro/outro/features):** ${merged.tier3_longtail.join(", ")}`);
+  }
+  if (merged.allKeywords.length > 0) {
+    lines.push(`
+**Top Keywords by Traffic (${merged.allKeywords.length} total):**`);
+    merged.allKeywords.slice(0, 15).forEach((kw, idx) => {
+      const tierLabel = kw.tier ? ` [${kw.tier}]` : "";
+      const scores = kw.traffic > 0 || kw.difficulty > 0 ? ` (traffic: ${kw.traffic.toFixed(2)}, difficulty: ${kw.difficulty.toFixed(2)})` : "";
+      lines.push(`${idx + 1}. **${kw.keyword}**${tierLabel}${scores}`);
+      if (kw.rationale) {
+        lines.push(`   \u2192 ${kw.rationale}`);
+      }
+    });
   }
-  lines.push("----");
+  if (merged.rationale) {
+    lines.push(`
+**Strategy:** ${merged.rationale}`);
+  }
+  if (merged.keywordGaps.length > 0) {
+    lines.push(`
+**Keyword Gaps (opportunities):**`);
+    merged.keywordGaps.slice(0, 5).forEach((gap) => lines.push(`- ${gap}`));
+  }
+  if (merged.userLanguagePatterns.length > 0) {
+    lines.push(`
+**User Language Patterns (from reviews):**`);
+    merged.userLanguagePatterns.slice(0, 5).forEach((pattern) => lines.push(`- ${pattern}`));
+  }
+  lines.push("\n----");
   return lines.join("\n");
 }
 function loadKeywordResearchForLocale(slug, locale) {
@@ -1697,6 +1900,15 @@ function loadKeywordResearchForLocale(slug, locale) {
       });
     }
   }
+  const validEntries = entries.filter((e) => !e.data?.parseError);
+  if (validEntries.length > 1) {
+    const merged = mergeKeywordData(validEntries);
+    const mergedSection = formatMergedData(merged, researchDir);
+    return { entries, sections: [mergedSection], researchDir };
+  } else if (validEntries.length === 1) {
+    const sections2 = entries.map(formatEntry);
+    return { entries, sections: sections2, researchDir };
+  }
   const sections = entries.map(formatEntry);
   return { entries, sections, researchDir };
 }
@@ -2596,11 +2808,31 @@ var keywordResearchTool = {
 
 **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.
+## CRITICAL: Multi-Locale Execution Plan
+
+**MANDATORY WORKFLOW - Complete each locale fully before moving to next:**
 
-**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.
+For EACH locale+platform combination, execute this cycle:
+1. **Plan:** Call keyword-research(slug, locale, platform) with writeTemplate=false \u2192 get research plan
+2. **Research:** Execute COMPLETE mcp-appstore workflow (all 16 steps) for that locale
+3. **Save:** Call keyword-research again with researchData or researchDataPath \u2192 persist actual data
+4. **Next:** Move to next locale+platform and repeat steps 1-3
 
-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.`,
+**IMPORTANT: Research \u2192 Save \u2192 Next pattern**
+- Complete ONE locale fully (research + save) before starting the next
+- This prevents data loss if the session is interrupted
+- Each locale's data is persisted immediately after research
+
+**FORBIDDEN:**
+- \u274C Using writeTemplate=true as final output
+- \u274C Skipping secondary locales
+- \u274C Researching multiple locales then saving all at once at the end
+- \u274C Stopping before all locale+platform combinations are done
+
+**REQUIRED:**
+- \u2705 Research locale \u2192 Save locale \u2192 Move to next (one at a time)
+- \u2705 Run for EVERY platform (ios AND android separately)
+- \u2705 Use researchData or researchDataPath to save (NOT writeTemplate)`,
   inputSchema: inputSchema7
 };
 function buildTemplate({
@@ -2733,7 +2965,6 @@ async function handleKeywordResearch(input) {
   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 { supportedLocales, path: supportedPath } = getSupportedLocalesForSlug(slug, platform);
   const appStoreLocales = registeredApp?.appStore?.supportedLocales || [];
@@ -2879,24 +3110,56 @@ Context around ${pos}: ${context}`
       `Registered supported locales not found for ${platform} (checked: ${supportedPath}).`
     );
   }
+  const allCombinations = [];
+  const platformsToRun = declaredPlatforms.length > 0 ? declaredPlatforms : [platform];
+  for (const plat of platformsToRun) {
+    for (const loc of productLocales.length > 0 ? productLocales : [locale]) {
+      allCombinations.push({ loc, plat });
+    }
+  }
+  const currentIndex = allCombinations.findIndex(
+    (c) => c.loc === locale && c.plat === platform
+  );
+  const completedCount = currentIndex >= 0 ? currentIndex : 0;
+  const remainingCombinations = allCombinations.slice(currentIndex + 1);
   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(", ")}`
-      );
-    }
-    if (declaredPlatforms.length > 1) {
-      lines.push(
-        "Also run separate FULL keyword research for each supported platform (e.g., ios + android) across all locales."
-      );
-    }
   }
+  lines.push("");
+  lines.push("---");
+  lines.push("## \u{1F3AF} EXECUTION PROGRESS TRACKER");
+  lines.push("");
+  lines.push(`**Total combinations to complete:** ${allCombinations.length} (${platformsToRun.length} platforms \xD7 ${productLocales.length || 1} locales)`);
+  lines.push(`**Current:** ${locale} + ${platform} (${completedCount + 1}/${allCombinations.length})`);
+  lines.push("");
+  if (researchData || researchDataPath) {
+    lines.push(`\u2705 SAVED: ${locale} + ${platform} - Full research data persisted`);
+  } else if (writeTemplate) {
+    lines.push(`\u26A0\uFE0F WARNING: ${locale} + ${platform} - Only template written! You MUST run full mcp-appstore research and save actual data.`);
+  } else {
+    lines.push(`\u{1F4CB} PLANNING: ${locale} + ${platform} - Research plan shown. Now execute mcp-appstore workflow.`);
+  }
+  if (remainingCombinations.length > 0) {
+    lines.push("");
+    lines.push("## \u23ED\uFE0F MANDATORY NEXT STEPS");
+    lines.push("");
+    lines.push("**After completing current locale+platform, you MUST continue with:**");
+    lines.push("");
+    remainingCombinations.forEach((combo, idx) => {
+      lines.push(`${idx + 1}. keyword-research(slug="${slug}", locale="${combo.loc}", platform="${combo.plat}") \u2192 full mcp-appstore workflow \u2192 save results`);
+    });
+    lines.push("");
+    lines.push("\u26D4 DO NOT mark this task as complete until ALL combinations above have FULL research data (not templates).");
+  } else {
+    lines.push("");
+    lines.push("## \u2705 FINAL STEP");
+    lines.push("");
+    lines.push("This is the LAST locale+platform combination. After saving full research data for this one, the task is complete.");
+  }
+  lines.push("---");
+  lines.push("");
   lines.push(
     `Seeds: ${resolvedSeeds.length > 0 ? resolvedSeeds.join(", ") : "(none set; add seedKeywords or ensure ASO keywords/title exist)"}`
   );

package/package.json

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