keyword-research
Plan and save keyword research data for app store optimization across multiple locales and platforms, ensuring structured execution and data persistence.
Instructions
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.
CRITICAL: Multi-Locale Execution Plan
MANDATORY WORKFLOW - Complete each locale fully before moving to next:
For EACH locale+platform combination, execute this cycle:
Plan: Call keyword-research(slug, locale, platform) with writeTemplate=false → get research plan
Research: Execute COMPLETE mcp-appstore workflow (all 16 steps) for that locale
Save: Call keyword-research again with researchData or researchDataPath → persist actual data
Next: Move to next locale+platform and repeat steps 1-3
IMPORTANT: Research → Save → 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:
❌ Using writeTemplate=true as final output
❌ Skipping secondary locales
❌ Researching multiple locales then saving all at once at the end
❌ Stopping before all locale+platform combinations are done
REQUIRED:
✅ Research locale → Save locale → Move to next (one at a time)
✅ Run for EVERY platform (ios AND android separately)
✅ Use researchData or researchDataPath to save (NOT writeTemplate)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Product slug | |
| locale | Yes | Locale code (e.g., en-US, ko-KR). Used for storage under .aso/keywordResearch/products/[slug]/locales/. | |
| platform | No | Store to target ('ios' or 'android'). Run separately per platform. | ios |
| country | No | Two-letter store country code. If omitted, derived from locale region (e.g., ko-KR -> kr), else 'us'. | |
| seedKeywords | No | Seed keywords to start from. | |
| competitorApps | No | Known competitor apps to probe. | |
| filename | No | Override output filename. Defaults to keyword-research-[platform]-[country].json | |
| writeTemplate | No | If true, write a JSON template at the output path. | |
| researchData | No | Optional JSON string with research results (e.g., from mcp-appstore tools). If provided, saves it to the output path. | |
| researchDataPath | No | Optional path to a JSON file containing research results. If set, file content is saved to the output path (preferred to avoid escape errors). |