pabal-web-mcp 1.3.3 → 1.3.5

package/dist/bin/mcp-server.js

@@ -2488,14 +2488,16 @@ function buildTemplate({
     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 competitors.",
-        "Discover competitors: search_app(term=seed keyword), get_similar_apps(appId=known competitor).",
-        "Collect candidates: suggest_keywords_by_seeds/by_category/by_similarity/by_competition/by_search + suggest_keywords_by_apps(apps=[top competitors]).",
+        "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 and fetch_reviews 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."
+        "Context check: analyze_reviews (num=100\u2013200) and fetch_reviews (num=50\u2013100) on top apps for language/tone cues.",
+        "If keywordSuggestions/similar/reviews are sparse, rerun calls (add more competitors/seeds) until you have 10\u201315 strong keywords.",
+        "For any recommended keyword without scores, rerun get_keyword_scores to fill traffic/difficulty.",
+        "Keep rationale/nextActions in English by default unless you intentionally localize them."
       ],
-      note: "Run per platform/country. Save raw tool outputs plus curated top keywords (target 10\u201315 per locale: 2\u20133 high-traffic core, 4\u20136 mid-competition, 4\u20136 longtail)."
+      note: "Run per platform/country. Save raw tool outputs plus curated top keywords (target 10\u201315 per locale: 2\u20133 high-traffic core, 4\u20136 mid-competition, 4\u20136 longtail). Minimum checklist before saving: search_app results present, keywordSuggestions.* NOT empty, keywordScores >= 10 items, recommendedKeywords 10\u201315 items."
     },
     data: {
       raw: {
@@ -2698,16 +2700,16 @@ Context around ${pos}: ${context}`
     `2) Confirm IDs/locales: get_app_details(appId from config/registered-apps) to lock locale/country and competitor list.`
   );
   lines.push(
-    `3) Discover apps: search_app(term=seed, platform=${platform}, country=${resolvedCountry}); get_similar_apps(appId=known competitor).`
+    `3) Discover apps: search_app(term=seed, num=10-20, platform=${platform}, country=${resolvedCountry}); get_similar_apps(appId=top competitor, num=10).`
   );
   lines.push(
-    `4) Expand keywords: suggest_keywords_by_seeds/by_category/by_similarity/by_competition/by_search + suggest_keywords_by_apps(apps=[top competitors]).`
+    `4) Expand keywords (num=20-30 each): suggest_keywords_by_seeds/by_category/by_similarity/by_competition/by_search + suggest_keywords_by_apps(apps=[top competitors]).`
   );
   lines.push(
     `5) Score shortlist: get_keyword_scores for 15\u201330 candidates (note: scores are heuristic per README).`
   );
   lines.push(
-    `6) Context check: analyze_reviews and fetch_reviews on top apps to harvest native phrasing; keep snippets for improve-public.`
+    `6) Context check: analyze_reviews (num=100-200) and fetch_reviews (num=50-100) on top apps to harvest native phrasing; keep snippets for improve-public.`
   );
   lines.push(
     `7) Save all raw responses + your final 10\u201315 keywords (mix of core/high-traffic, mid, longtail) to: ${outputPath} (structure mirrors .aso/pullData/.aso/pushData under products/<slug>/locales/<locale>)`
@@ -2715,6 +2717,12 @@ Context around ${pos}: ${context}`
   lines.push(
     `8) If keywordSuggestions/similarApps/reviews are still empty or <10 solid candidates, add more competitors/seeds and rerun the calls above until you reach 10\u201315 strong keywords.`
   );
+  lines.push(
+    `9) If any recommended keywords lack scores, rerun get_keyword_scores for those items. Keep rationale/nextActions in English by default unless you explicitly want them localized.`
+  );
+  lines.push(
+    `10) Do not finalize until: search_app has results, keywordSuggestions.* have entries, keywordScores >=10 items, recommendedKeywords 10\u201315 items. If missing, rerun the relevant calls.`
+  );
   if (fileAction) {
     lines.push(`File: ${fileAction} at ${outputPath}`);
   } else {
@@ -2737,6 +2745,324 @@ Context around ${pos}: ${context}`
   };
 }
 
+// src/tools/keyword-research-runner.ts
+import fs12 from "fs";
+import path12 from "path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { z as z7 } from "zod";
+import { zodToJsonSchema as zodToJsonSchema7 } from "zod-to-json-schema";
+var TOOL_NAME2 = "keyword-research-runner";
+var keywordResearchRunnerInputSchema = z7.object({
+  slug: z7.string().trim().describe("Product slug"),
+  locale: z7.string().trim().describe("Locale code (e.g., en-US, ko-KR)"),
+  platform: z7.enum(["ios", "android"]).default("ios"),
+  country: z7.string().length(2).optional().describe("Store country (default derived from locale region or 'us')"),
+  seedKeywords: z7.array(z7.string().trim()).default([]),
+  competitorApps: z7.array(
+    z7.object({
+      appId: z7.string().trim(),
+      platform: z7.enum(["ios", "android"])
+    })
+  ).default([]),
+  serverCwd: z7.string().trim().optional().describe("Path to mcp-appstore cwd (default: external-tools/mcp-appstore)"),
+  serverCommand: z7.array(z7.string()).optional().describe(
+    "Command + args to start mcp-appstore (default: ['node','server.js'])"
+  ),
+  numSuggestions: z7.number().int().positive().max(50).default(20).describe("Number of keyword suggestions per strategy (default: 20)")
+});
+var jsonSchema7 = zodToJsonSchema7(keywordResearchRunnerInputSchema, {
+  name: "KeywordResearchRunnerInput",
+  $refStrategy: "none"
+});
+var inputSchema7 = jsonSchema7.definitions?.KeywordResearchRunnerInput || jsonSchema7;
+var keywordResearchRunnerTool = {
+  name: TOOL_NAME2,
+  description: "Automatically call mcp-appstore tools to collect 10\u201315 keywords per locale and save to .aso/keywordResearch/...",
+  inputSchema: inputSchema7
+};
+function normalizeKeywords2(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) {
+    return raw.map((k) => k.trim()).filter(Boolean);
+  }
+  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;
+  }
+}
+function ensureDir(dir) {
+  fs12.mkdirSync(dir, { recursive: true });
+}
+async function handleKeywordResearchRunner(input) {
+  const {
+    slug,
+    locale,
+    platform = "ios",
+    country,
+    seedKeywords = [],
+    competitorApps = [],
+    serverCwd,
+    serverCommand,
+    numSuggestions = 20
+  } = input;
+  const { config, locales } = loadProductLocales(slug);
+  const primaryLocale = resolvePrimaryLocale(config, locales);
+  const { app: registeredApp } = findRegisteredApp(slug);
+  const resolvedCountry = country || (locale.includes("-") ? locale.split("-")[1].toLowerCase() : "us");
+  const autoSeeds = [];
+  const primaryLocaleData = locales[primaryLocale];
+  if (primaryLocaleData?.aso?.title) autoSeeds.push(primaryLocaleData.aso.title);
+  const parsedKeywords = normalizeKeywords2(primaryLocaleData?.aso?.keywords);
+  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 (platform === "ios") {
+    if (config?.appStoreAppId) {
+      autoCompetitors.push({ appId: String(config.appStoreAppId), platform });
+    } else if (config?.bundleId) {
+      autoCompetitors.push({ appId: config.bundleId, platform });
+    } else if (registeredApp?.appStore?.appId) {
+      autoCompetitors.push({ appId: String(registeredApp.appStore.appId), platform });
+    } else if (registeredApp?.appStore?.bundleId) {
+      autoCompetitors.push({ appId: registeredApp.appStore.bundleId, platform });
+    }
+  } else {
+    if (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 || path12.resolve(process.cwd(), "external-tools", "mcp-appstore");
+  const cmd = serverCommand?.[0] || "node";
+  const args = serverCommand?.length ? serverCommand.slice(1) : ["server.js"];
+  const transport = new StdioClientTransport({ command: cmd, args, cwd });
+  const client = new Client(
+    { name: "keyword-research-runner", version: "1.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  await client.connect(transport);
+  const raw = {
+    searchApp: [],
+    getAppDetails: [],
+    similarApps: [],
+    keywordSuggestions: {
+      bySeeds: [],
+      byCategory: [],
+      bySimilarity: [],
+      byCompetition: [],
+      bySearchHints: [],
+      byApps: []
+    },
+    keywordScores: [],
+    reviewsAnalysis: [],
+    reviewsRaw: []
+  };
+  for (const term of seeds.slice(0, 3)) {
+    const res = await callToolJSON(client, "search_app", {
+      term,
+      platform,
+      num: 20,
+      country: resolvedCountry
+    });
+    raw.searchApp.push({ query: term, platform, country: resolvedCountry, results: res?.results ?? res });
+  }
+  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 (competitors.length > 0) {
+    const first = competitors[0];
+    const res = await callToolJSON(client, "get_similar_apps", {
+      appId: first.appId,
+      platform,
+      num: 10,
+      country: resolvedCountry
+    });
+    raw.similarApps = res?.similarApps || res || [];
+  }
+  const firstComp = competitors[0]?.appId;
+  const appsList = competitors.map((c) => c.appId);
+  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);
+  }
+  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);
+      });
+    }
+  };
+  seeds.forEach((s) => candidateSet.add(s));
+  Object.values(raw.keywordSuggestions).forEach((arr) => addCandidates(arr));
+  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 summary = {
+    recommendedKeywords: recommended.map((r) => ({
+      keyword: r.keyword,
+      trafficScore: r.trafficScore,
+      difficultyScore: r.difficultyScore
+    })),
+    rationale: "Sorted by traffic score (desc). Blend of core/high-traffic and mid/longtail technical terms.",
+    nextActions: "Feed top 10\u201315 into improve-public Stage 1. If any sections are empty (suggestions/reviews), add more competitors/seeds and rerun."
+  };
+  const researchDir = path12.join(
+    getKeywordResearchDir(),
+    "products",
+    slug,
+    "locales",
+    locale
+  );
+  ensureDir(researchDir);
+  const fileName = `keyword-research-${platform}-${resolvedCountry}.json`;
+  const outputPath = path12.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 by keyword-research-runner"
+    },
+    data: { raw, summary }
+  };
+  fs12.writeFileSync(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+  await client.close();
+  const lines = [];
+  lines.push(`# keyword-research-runner`);
+  lines.push(`Saved to ${outputPath}`);
+  lines.push(
+    `Candidates scored: ${scored.length}, Recommended: ${summary.recommendedKeywords.length}`
+  );
+  lines.push(
+    `Warnings: rerun if keywordSuggestions are empty or recommended < 10.`
+  );
+  return {
+    content: [{ type: "text", text: lines.join("\n") }]
+  };
+}
+
 // src/tools/index.ts
 var tools = [
   {
@@ -2786,6 +3112,13 @@ var tools = [
     zodSchema: keywordResearchInputSchema,
     handler: handleKeywordResearch,
     category: "ASO Research"
+  },
+  {
+    name: keywordResearchRunnerTool.name,
+    description: keywordResearchRunnerTool.description,
+    inputSchema: keywordResearchRunnerTool.inputSchema,
+    handler: handleKeywordResearchRunner,
+    category: "ASO Research"
   }
 ];
 function getToolDefinitions() {
@@ -2795,6 +3128,7 @@ function getToolDefinitions() {
     improvePublicTool,
     initProjectTool,
     createBlogHtmlTool,
+    keywordResearchRunnerTool,
     keywordResearchTool
   ];
 }

package/package.json

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