pabal-resource-mcp 1.10.6 → 1.10.7

package/dist/bin/mcp-server.js

@@ -1480,9 +1480,17 @@ ${json}
 // src/tools/aso/utils/improve/generate-aso-prompt.util.ts
 var ASO_RULES_SUMMARY = [
   `Use ${ASO_OVERVIEW_DOC_PATH} for keyword strategy and ${FIELD_LIMITS_DOC_PATH} for hard limits.`,
-  "`aso.title`: keep app name + the most relevant high-priority keyword, usually `App Name: Primary Keyword`.",
+  "Keyword source priority: product-level manual CSV files in `.aso/keywordResearch/products/[slug]/*.csv` first. Check the target country Store Domain first; if missing, translate/localize US CSV keywords for the target locale. Then use locale saved keyword research alongside the CSV to validate and fill remaining opportunities.",
+  "Distribute important terms in this order: title first, subtitle second, keywords third.",
+  "Assign tracked keywords by relevance and current rank: best keyword that fits 30 chars -> title; next best keyword that fits 30 chars -> subtitle; remaining high-value keywords within 100 chars -> keyword field.",
+  "`aso.title`: keep app name + the most relevant high-priority keyword, usually `App Name: Primary Keyword`; remember `&`, `:`, and `-` count as 2 characters in title limits.",
   "`aso.subtitle`: use important keywords that do not repeat the title.",
-  "`aso.keywords`: comma-separated with commas only, no spaces, no duplicates, no title/subtitle repetition.",
+  "`aso.keywords`: comma-separated with commas only, no spaces, no duplicates, no title/subtitle repetition; every word can appear in only one of title, subtitle, or keywords.",
+  "Do not split multi-word keywords across fields; keep the full phrase in one field.",
+  "Use singular forms only because Apple indexes plurals automatically.",
+  "Exclude stop words that Apple ignores, such as `a`, `and`, `the`, `for`, `with`, `app`, and `to`.",
+  "Exclude company/app names and inherited category terms, such as the app brand and categories like `Health & Fitness`.",
+  "For US Store keyword suggestions, find suggestions for the app and only add keywords with popularity >25 and difficulty <75.",
   "`aso.keywords`: use as much of the 100-character limit as possible with relevant keywords; do not leave meaningful capacity unused and do not use filler.",
   '`aso.keywords`: split phrase intent into reusable single terms when appropriate, e.g. `sound,relaxing,rain` for "relaxing sound" + "rain sound".',
   "`aso.keywords`: prefer singular forms, allow real searched misspellings, and order by importance.",
@@ -1512,19 +1520,24 @@ function generatePrimaryOptimizationPrompt(args) {
   prompt += `## Task
 
 `;
-  prompt += `Optimize the PRIMARY locale (${primaryLocale}) using **saved keyword research** + full ASO field optimization.
+  prompt += `Optimize the PRIMARY locale (${primaryLocale}) using **manual CSV priority keywords first**, then saved keyword research + full ASO field optimization.
 
 `;
-  prompt += `## Step 1: Use Saved Keyword Research (${primaryLocale})
+  prompt += `## Step 1: Use Keyword Sources (${primaryLocale})
 
 `;
   const researchSections = keywordResearchByLocale[primaryLocale] || [];
   const researchDir = keywordResearchDirByLocale[primaryLocale];
   if (researchSections.length > 0) {
-    prompt += `**CRITICAL: Use ONLY the saved keyword research below. Do NOT invent or research new keywords.**
+    prompt += `**CRITICAL: Use ONLY the keyword sources below. Do NOT invent or research new keywords.**
+
+`;
+    prompt += `**Source priority:** If a "Manual Priority Keywords CSV" section exists, apply those keywords before generated keyword research. If the CSV section says it is using US fallback rows, translate/localize those US keywords into ${primaryLocale} before applying them. Still review the saved locale keyword research alongside the CSV to validate relevance and fill remaining relevant opportunities.
 
 `;
     prompt += `The research data includes:
+`;
+    prompt += `- **Manual Priority Keywords CSV:** Human-curated product-level keyword list. Check target country rows first; if missing, use US rows as a translation source. Apply before saved research, while still considering saved research.
 `;
     prompt += `- **Tier 1 (Core):** Use these in title and subtitle - highest traffic, best opportunity
 `;
@@ -1541,7 +1554,7 @@ function generatePrimaryOptimizationPrompt(args) {
     prompt += `- **User Language Patterns:** Phrases real users use in reviews - incorporate naturally
 
 `;
-    prompt += `Saved research:
+    prompt += `Keyword sources:
 ${researchSections.join("\n")}
 
 `;
@@ -1560,6 +1573,18 @@ ${researchSections.join("\n")}
 `;
   prompt += `**Apply keywords strategically based on tier priority:**
 
+`;
+  prompt += `**Assignment rule:** Tag tracked keywords by relevance and current rank: best keyword that fits the 30-character title limit as \`title\`, next best keyword that fits the 30-character subtitle limit as \`subtitle\`, and remaining high-value keywords that fit the 100-character keyword field as \`keyword field\`.
+`;
+  prompt += `**Ordering rule:** Place the strongest important terms on the left in every field. A word used in \`aso.title\`, \`aso.subtitle\`, or \`aso.keywords\` must not appear in either of the other two fields.
+`;
+  prompt += `**Phrase rule:** Do not split multi-word keywords across fields. Keep the complete phrase together in one field.
+`;
+  prompt += `**Cleanup rule:** Use singular forms, remove Apple-ignored stop words (a/and/the/for/with/app/to/etc.), and exclude the company/app name plus inherited category keywords such as "Health & Fitness".
+
+`;
+  prompt += `**US Store suggestion rule:** For US Store keyword suggestions, find suggestions for this app and only add keywords with popularity >25 and difficulty <75.
+
 `;
   prompt += `### Tier 1 Keywords (Core) \u2192 Title & Subtitle
 `;
@@ -1620,10 +1645,16 @@ ${researchSections.join("\n")}
   prompt += `Check all limits using ${FIELD_LIMITS_DOC_PATH}: title \u226430, subtitle \u226430, shortDescription \u226480, keywords \u2264100, intro \u2264300, outro \u2264200
 `;
   prompt += `- Apply ${ASO_OVERVIEW_DOC_PATH}: keyword popularity \u226520 where available, achievable difficulty, relevance, likely user intent, singular forms, important keywords first
+`;
+  prompt += `- Confirm title/subtitle/keywords priority placement: title gets the most important fitting keyword, subtitle gets the next important fitting non-overlapping keyword, keywords gets remaining non-overlapping terms
+`;
+  prompt += `- Confirm multi-word keywords are not split across fields and stop words/category/company terms were excluded
+`;
+  prompt += `- For US Store keyword suggestions, confirm every added suggestion has popularity >25 and difficulty <75
 `;
   prompt += `- Maximize keyword field utilization: target 90-100/100 chars when enough relevant keywords exist; explain any lower count
 `;
-  prompt += `- Remove keyword duplicates (unique list; avoid repeating title/subtitle terms verbatim; no spaces after commas)
+  prompt += `- Remove keyword duplicates across all metadata fields: no duplicate terms inside keywords and no overlap between title, subtitle, and keywords; no spaces after commas
 `;
   prompt += `- Ensure App Store/Play Store rules from ${FIELD_LIMITS_DOC_PATH} are satisfied (no disallowed characters/formatting)
 
@@ -1637,11 +1668,15 @@ ${researchSections.join("\n")}
   prompt += `## Output Format
 
 `;
-  prompt += `**1. Keyword Research (from saved data)**
+  prompt += `**1. Keyword Research (from provided sources)**
 `;
   prompt += `   - Cite file(s) used and list the selected top 10 keywords (no new research)
 `;
-  prompt += `   - Rationale: why these 10 were chosen from saved research
+  prompt += `   - If a Manual Priority Keywords CSV was provided, cite it first, state whether target-country or US fallback rows were used, and explain how those keywords were placed before generated research keywords
+`;
+  prompt += `   - Tag each selected tracked keyword as \`title\`, \`subtitle\`, or \`keyword field\` according to relevance/current rank and field limits
+`;
+  prompt += `   - Rationale: why these 10 were chosen from the provided sources
 
 `;
   prompt += `**2. Optimized JSON** (complete ${primaryLocale} locale structure)
@@ -1669,7 +1704,9 @@ ${researchSections.join("\n")}
 `;
   prompt += `   - shortDescription: X/80 \u2713/\u2717
 `;
-  prompt += `   - keywords: X/100 \u2713/\u2717 (target 90-100 when possible; deduped \u2713/\u2717)
+  prompt += `   - keywords: X/100 \u2713/\u2717 (target 90-100 when possible; deduped \u2713/\u2717; no title/subtitle/keywords overlap \u2713/\u2717)
+`;
+  prompt += `   - phrase integrity / singular / stop-word / category-name checks: \u2713/\u2717
 `;
   prompt += `   - intro: X/300 \u2713/\u2717
 `;
@@ -1784,7 +1821,7 @@ ${optimizedPrimary}
   prompt += `## Keyword Research (Per Locale)
 
 `;
-  prompt += `**Priority:** Use each locale's own keyword research. English fallback is ONLY used when locale-specific research is missing.
+  prompt += `**Priority:** Use product-level Manual Priority Keywords CSV first when present: check target-country Store Domain rows first; if missing, translate/localize US CSV rows for the target locale. Then review each locale's own keyword research alongside the CSV. English fallback research is ONLY used when locale-specific research is missing.
 `;
   prompt += `When both iOS and Android research exist for a locale, treat iOS keywords as primary; use Android keywords only if space remains after fitting iOS keywords within character limits.
 
@@ -1852,6 +1889,18 @@ ${optimizedPrimary}
 
 `;
   prompt += `For EACH locale:
+`;
+  prompt += `- Source priority: Manual Priority Keywords CSV first (target-country rows, or translated/localized US rows if target-country rows are missing), locale saved keyword research second, translated fallback research third.
+`;
+  prompt += `- Even when CSV exists, still review the locale saved keyword research and use it to validate choices and fill remaining relevant capacity.
+`;
+  prompt += `- Metadata placement priority: best fitting keyword by relevance/current rank to title, next best fitting keyword to subtitle, remaining high-value keywords to keyword field.
+`;
+  prompt += `- Do not repeat the same word across title, subtitle, and keywords. Do not split multi-word keywords across fields.
+`;
+  prompt += `- Use singular forms, remove Apple-ignored stop words, and exclude company/app/category names.
+`;
+  prompt += `- For US Store keyword suggestions, find suggestions for this app and only add keywords with popularity >25 and difficulty <75.
 `;
   prompt += `- Priority: Keep iOS-sourced keywords first; add Android keywords only if there is remaining space after iOS keywords fit within field limits.
 `;
@@ -1873,7 +1922,13 @@ ${optimizedPrimary}
 `;
   prompt += `   - **Only replace the keyword part** - keep the app name and format structure unchanged
 `;
-  prompt += `4. Deduplicate keywords: final \`aso.keywords\` must be unique, comma-only without spaces, as close to 100 chars as possible, and should not repeat title/subtitle terms verbatim
+  prompt += `4. Deduplicate keywords: final \`aso.keywords\` must be unique, comma-only without spaces, as close to 100 chars as possible, and must not repeat any title/subtitle keyword terms
+`;
+  prompt += `   - Do not split multi-word keywords between title/subtitle/keywords; assign the full phrase to a single field
+`;
+  prompt += `   - Use singular forms only; remove stop words such as a/and/the/for/with/app/to; exclude app/company/category names
+`;
+  prompt += `   - For US Store keyword suggestions, only add suggestions with popularity >25 and difficulty <75
 `;
   prompt += `5. **Replace keywords in existing sentences** - swap ONLY the keywords, keep everything else:
 `;
@@ -1938,7 +1993,7 @@ ${optimizedPrimary}
 `;
   prompt += `Process EACH locale in this batch sequentially:
 `;
-  prompt += `1. Use saved keyword research (in target language) OR **TRANSLATE English keywords from primary locale** if missing (see fallback strategy above - MUST translate, not use English directly)
+  prompt += `1. Use Manual Priority Keywords CSV first when present. If target-country CSV rows are missing and US CSV rows are shown, **TRANSLATE/LOCALIZE those US CSV keywords** to the target locale before applying them. Then use saved keyword research (in target language), OR **TRANSLATE English fallback research from primary locale** if missing (see fallback strategy above - MUST translate, not use English directly)
 `;
   prompt += `2. **Replace keywords ONLY** in ALL fields (keep existing content structure unchanged):
 `;
@@ -1960,7 +2015,9 @@ ${optimizedPrimary}
 `;
   prompt += `3. **CRITICAL**: Ensure ALL landing fields are translated (not English)
 `;
-  prompt += `4. After swapping keywords, validate ASO basics (${ASO_OVERVIEW_DOC_PATH}) + limits/store rules (${FIELD_LIMITS_DOC_PATH}) + keyword utilization (target 90-100/100 when enough relevant keywords exist) + keyword duplication (unique list; avoid repeating title/subtitle terms verbatim; no spaces after commas)
+  prompt += `4. After swapping keywords, validate ASO basics (${ASO_OVERVIEW_DOC_PATH}) + limits/store rules (${FIELD_LIMITS_DOC_PATH}) + keyword utilization (target 90-100/100 when enough relevant keywords exist) + keyword duplication (unique list; no overlap between title/subtitle/keywords; no spaces after commas)
+`;
+  prompt += `   - Also validate no multi-word keyword was split across fields, singular forms are used, stop words are removed, and company/app/category names are excluded
 `;
   prompt += `5. **SAVE the updated JSON to file** using save-locale-file tool
 `;
@@ -2001,10 +2058,14 @@ ${optimizedPrimary}
 
 `;
   prompt += `**1. Keyword Source**
+`;
+  prompt += `   - If Manual Priority Keywords CSV exists: Cite it first; state whether target-country rows or translated US fallback rows were used; list selected CSV keywords and where they were placed
 `;
   prompt += `   - If saved research exists: Cite file(s) used; list selected top 10 keywords (in target language)
 `;
   prompt += `   - If using fallback: List **TRANSLATED** keywords from primary locale (English \u2192 target language) with translation rationale
+`;
+  prompt += `   - Tag each selected tracked keyword as \`title\`, \`subtitle\`, or \`keyword field\` according to relevance/current rank and field limits
 `;
   prompt += `   - Show final 10 keywords **IN TARGET LANGUAGE** with tier assignments - DO NOT show English keywords
 
@@ -2040,7 +2101,9 @@ ${optimizedPrimary}
 `;
   prompt += `   - shortDescription: X/80 \u2713/\u2717
 `;
-  prompt += `   - keywords: X/100 \u2713/\u2717 (target 90-100 when possible; deduped \u2713/\u2717; comma-only/no spaces \u2713/\u2717; not repeating title/subtitle)
+  prompt += `   - keywords: X/100 \u2713/\u2717 (target 90-100 when possible; deduped \u2713/\u2717; comma-only/no spaces \u2713/\u2717; no title/subtitle/keywords overlap \u2713/\u2717)
+`;
+  prompt += `   - phrase integrity / singular / stop-word / category-name checks: \u2713/\u2717
 `;
   prompt += `   - intro: X/300 \u2713/\u2717
 `;
@@ -2094,6 +2157,168 @@ validate-aso(slug="${slug}")
 // src/tools/aso/utils/improve/load-keyword-research.util.ts
 import fs6 from "fs";
 import path6 from "path";
+var LOCALE_STORE_DOMAIN_OVERRIDES = {
+  ar: "sa",
+  en: "us",
+  "en-US": "us",
+  "zh-Hans": "cn",
+  "zh-Hant": "tw"
+};
+function parseCsvLine(line) {
+  const values = [];
+  let current = "";
+  let isQuoted = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    const nextChar = line[index + 1];
+    if (char === '"' && isQuoted && nextChar === '"') {
+      current += '"';
+      index += 1;
+      continue;
+    }
+    if (char === '"') {
+      isQuoted = !isQuoted;
+      continue;
+    }
+    if (char === "," && !isQuoted) {
+      values.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  values.push(current);
+  return values;
+}
+function getLocaleStoreDomain(locale) {
+  const override = LOCALE_STORE_DOMAIN_OVERRIDES[locale];
+  if (override) {
+    return override;
+  }
+  const localeParts = locale.split("-");
+  return (localeParts[1] || localeParts[0] || "").toLowerCase();
+}
+function loadManualKeywordCsvRowsForStoreDomain(slug, storeDomain) {
+  const productResearchDir = path6.join(getKeywordResearchDir(), "products", slug);
+  if (!fs6.existsSync(productResearchDir)) {
+    return [];
+  }
+  const csvFiles = fs6.readdirSync(productResearchDir).filter((file) => file.endsWith(".csv")).sort();
+  if (csvFiles.length === 0) {
+    return [];
+  }
+  const rows = [];
+  for (const file of csvFiles) {
+    const filePath = path6.join(productResearchDir, file);
+    const raw = fs6.readFileSync(filePath, "utf-8").trim();
+    if (!raw) {
+      continue;
+    }
+    const [headerLine, ...dataLines] = raw.split(/\r?\n/);
+    if (!headerLine) {
+      continue;
+    }
+    const headers = parseCsvLine(headerLine).map((header) => header.trim());
+    const getValue = (values, header) => {
+      const index = headers.indexOf(header);
+      return index >= 0 ? values[index]?.trim() || "" : "";
+    };
+    for (const line of dataLines) {
+      if (!line.trim()) {
+        continue;
+      }
+      const values = parseCsvLine(line);
+      const rowStoreDomain = getValue(values, "Store Domain").toLowerCase();
+      if (rowStoreDomain !== storeDomain) {
+        continue;
+      }
+      const keyword = getValue(values, "Keyword");
+      if (!keyword) {
+        continue;
+      }
+      rows.push({
+        filePath,
+        keyword,
+        platform: getValue(values, "Platform"),
+        storeDomain: rowStoreDomain,
+        store: getValue(values, "Store"),
+        ranking: getValue(values, "Ranking"),
+        popularity: getValue(values, "Popularity"),
+        difficulty: getValue(values, "Difficulty"),
+        lastUpdate: getValue(values, "Last Update")
+      });
+    }
+  }
+  const seenKeywords = /* @__PURE__ */ new Set();
+  return rows.filter((row) => {
+    const normalized = row.keyword.toLowerCase();
+    if (seenKeywords.has(normalized)) {
+      return false;
+    }
+    seenKeywords.add(normalized);
+    return true;
+  });
+}
+function loadManualKeywordCsv(slug, locale) {
+  const targetStoreDomain = getLocaleStoreDomain(locale);
+  const localeRows = loadManualKeywordCsvRowsForStoreDomain(
+    slug,
+    targetStoreDomain
+  );
+  if (localeRows.length > 0) {
+    return {
+      rows: localeRows,
+      isFallback: false,
+      sourceStoreDomain: targetStoreDomain,
+      targetStoreDomain
+    };
+  }
+  const usRows = targetStoreDomain === "us" ? [] : loadManualKeywordCsvRowsForStoreDomain(slug, "us");
+  return {
+    rows: usRows,
+    isFallback: usRows.length > 0,
+    sourceStoreDomain: "us",
+    targetStoreDomain
+  };
+}
+function formatManualKeywordCsvRows(result, locale) {
+  const { rows, isFallback, sourceStoreDomain, targetStoreDomain } = result;
+  const sourceFiles = [...new Set(rows.map((row) => row.filePath))];
+  const lines = [];
+  lines.push(
+    `### Manual Priority Keywords CSV (${locale} / ${targetStoreDomain})`
+  );
+  lines.push(`Source: ${sourceFiles.join(", ")}`);
+  if (isFallback) {
+    lines.push(
+      `Fallback: No CSV rows found for Store Domain "${targetStoreDomain}". Using "${sourceStoreDomain}" CSV keywords as translation source for ${locale}.`
+    );
+    lines.push(
+      "Translation rule: translate/localize these US keywords into the target locale before placing them in title, subtitle, keywords, or landing copy."
+    );
+  }
+  lines.push(
+    "Priority: Apply these CSV keywords before saved keyword research, but still use locale saved research alongside them to validate relevance and fill remaining opportunities."
+  );
+  lines.push(
+    "Placement rule: put the strongest terms in title first, then subtitle, then the keywords field. Do not duplicate the same keyword across title, subtitle, and keywords."
+  );
+  lines.push("");
+  lines.push("**CSV Priority Keywords:**");
+  rows.slice(0, 30).forEach((row, index) => {
+    const metrics = [
+      row.platform ? `platform: ${row.platform}` : "",
+      row.store ? `store: ${row.store}` : "",
+      row.ranking ? `rank: ${row.ranking}` : "",
+      row.popularity ? `popularity: ${row.popularity}` : "",
+      row.difficulty ? `difficulty: ${row.difficulty}` : "",
+      row.lastUpdate ? `updated: ${row.lastUpdate}` : ""
+    ].filter(Boolean);
+    lines.push(`${index + 1}. **${row.keyword}**${metrics.length > 0 ? ` (${metrics.join(", ")})` : ""}`);
+  });
+  lines.push("\n----");
+  return lines.join("\n");
+}
 function extractRecommended(data) {
   const summary = data?.summary || data?.data?.summary;
   const recommended = summary?.recommendedKeywords;
@@ -2387,9 +2612,15 @@ function loadKeywordResearchForLocale(slug, locale) {
     "locales",
     locale
   );
+  const manualKeywordCsv = loadManualKeywordCsv(slug, locale);
+  const manualKeywordSections = manualKeywordCsv.rows.length > 0 ? [formatManualKeywordCsvRows(manualKeywordCsv, locale)] : [];
   const result = loadKeywordResearchForLocaleInternal(slug, locale);
   if (result) {
-    return { ...result, isFallback: false };
+    return {
+      ...result,
+      sections: [...manualKeywordSections, ...result.sections],
+      isFallback: false
+    };
   }
   for (const fallbackLocale of FALLBACK_LOCALES) {
     if (fallbackLocale === locale) continue;
@@ -2405,14 +2636,19 @@ function loadKeywordResearchForLocale(slug, locale) {
       );
       return {
         entries: fallbackResult.entries,
-        sections: sectionsWithNotice,
+        sections: [...manualKeywordSections, ...sectionsWithNotice],
         researchDir: fallbackResult.researchDir,
         isFallback: true,
         fallbackLocale
       };
     }
   }
-  return { entries: [], sections: [], researchDir, isFallback: false };
+  return {
+    entries: [],
+    sections: manualKeywordSections,
+    researchDir,
+    isFallback: false
+  };
 }
 
 // src/tools/aso/improve-public.ts
@@ -2444,6 +2680,7 @@ var improvePublicTool = {
 
 ## HOW THIS TOOL WORKS
 This tool returns a PROMPT containing:
+- Product-level manual CSV keyword data from .aso/keywordResearch/products/[slug]/*.csv when present
 - Saved keyword research data (Tier 1/2/3 keywords with traffic/difficulty scores)
 - Current locale data
 - Optimization instructions
@@ -2465,9 +2702,11 @@ This tool returns a PROMPT containing:
 - **Stage 2:** Localize to other languages - **each locale uses its OWN keyword research**
 
 ## KEYWORD SOURCES (Per Locale)
-- **Priority 1:** Uses each locale's SAVED keyword research from .aso/keywordResearch/products/[slug]/locales/[locale]/
-- **Priority 2 (Fallback):** If locale-specific research is missing, falls back to en-US/en keywords and TRANSLATES them
+- **Priority 1:** Uses product-level manual CSV keywords from .aso/keywordResearch/products/[slug]/*.csv. It checks the target locale's country Store Domain first; if missing, it uses US CSV keywords as a translation/localization source.
+- **Priority 2:** Uses each locale's SAVED keyword research from .aso/keywordResearch/products/[slug]/locales/[locale]/ alongside the CSV to validate relevance and fill remaining opportunities.
+- **Priority 3 (Fallback):** If locale-specific saved research is missing, falls back to en-US/en saved research and TRANSLATES it
 - iOS and Android research are automatically combined per locale (iOS prioritized)
+- Title, subtitle, and keywords must be filled in that importance order, with no repeated keyword terms across the three fields
 
 **CRITICAL:** Only processes existing locale files. Does NOT create new files.`,
   inputSchema: inputSchema3

package/package.json

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