ASO to SEO Data

Converts ASO data from pullData to public/products/[slug]/ structure.

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.

This tool:

1. Loads ASO data from .aso/pullData/products/[slug]/store/ (path from ~/.config/pabal-mcp/config.json dataDir)
2. Generates per-locale conversion prompts to map fullDescription into structured locale JSON (template intro/outro + landing features/screenshots captions)
3. Next steps (manual): paste converted JSON into public/products/[slug]/locales/[locale].json and copy screenshots from .aso/pullData if needed

The conversion from unstructured to structured format is performed by Claude based on the conversion prompt.

Generate HTML blog posts under public/blogs/<appSlug>/<slug>/<locale>.html with a BLOG_META block.

CRITICAL: WRITING STYLE CONSISTENCY Before generating content, you MUST:

1. Read existing blog posts from public/blogs/<appSlug>/*/<locale>.html (use findExistingBlogPosts utility or read files directly)
2. Analyze the writing style, tone, and format from 2 existing posts in the same locale
3. Match that exact writing style when generating the new blog post content and description
4. Maintain consistency in: paragraph structure, heading usage, tone, formality level, and overall format

IMPORTANT REQUIREMENTS:

1. The 'locale' parameter is REQUIRED. If the user does not provide a locale, you MUST ask them to specify which language/locale they want to write the blog in (e.g., 'en-US', 'ko-KR', 'ja-JP', etc.).
2. The 'content' parameter is REQUIRED. You (the LLM) must generate the HTML content based on the 'topic' and 'locale' provided by the user. The content should be written in the language corresponding to the locale AND match the writing style of existing blog posts for that locale.
3. The 'description' parameter is REQUIRED. You (the LLM) must generate this based on the topic, locale, AND the writing style of existing blog posts.
4. The 'appSlug' parameter:

• If the user requests personal/daily/journal developer content, set appSlug to "developer-journal".
• If the user requests technical/engineering/devlog content, set appSlug to "developer-tech".
• If the user mentions a specific app/product, use that app's slug.
• If not specified, defaults to "developer".

Slug rules:

• slug = slugify(English title, kebab-case ASCII)
• path: public/blogs/<appSlug>/<slug>/<locale>.html
• appSlug: Use "developer-journal" for personal/journal posts, "developer-tech" for technical posts. Defaults to "developer" if not specified.
• coverImage default: /products/<appSlug>/og-image.png (relative paths are rewritten under /blogs/<app>/<slug>/, developer slugs default to /og-image.png)
• status defaults to published when omitted. Set status="draft" only when the user explicitly asks for a draft.
• overwrite defaults to false (throws when file exists)

HTML Structure (follows public/en-US.html pattern):

• BLOG_META block at the top with JSON metadata
• HTML body content: paragraphs (<p>), headings (<h2>, <h3>), images (<img>), lists (<ul>, <li>), horizontal rules (<hr>), etc.
• You must generate the HTML content based on the topic, making it relevant and engaging for the target locale's language, while maintaining consistency with existing blog posts.

Supports multiple locales when locales[] is provided. Each locale gets its own HTML file. For each locale, you must:

1. Read existing posts in that locale to understand the writing style
2. Generate appropriate content in that locale's language
3. Match the writing style and format of existing posts

Generate app icons in various platform-specific formats from a base icon.

INPUT: Reads base icon from: {slug}/icons/icon.png or {slug}/icons/{styleFolder}/icon.png OUTPUT: Generates platform-specific icons in: {slug}/icons/ or {slug}/icons/{styleFolder}/

Generated Icons:

1. ios-light.png (1024x1024): iOS app icon, logo fits within 890px circle
2. adaptive-icon.png (1024x1024): Android adaptive icon, logo fits within 475px circle
3. splash-icon-light.png (1024x1024): Splash screen icon, logo fits within 614px circle
4. android-notification-icon.png (500x500): White logo on transparent background

Key Features:

• Automatic Padding Removal: Extracts actual logo from icon.png (removes surrounding padding)
• Smart Safe Zone Positioning: Logo automatically fits within platform-specific circles
• Flexible Alignment: Position logo center/left/right/top/bottom relative to safe zone
• White Masking: Threshold-based (default) or alpha-based (preserves exact shape)
• Custom Background: Only applies to ios-light.png. Others (adaptive-icon, splash, notification) are transparent
• Style Variants: Generate themed icons (christmas, halloween, etc.) with style-specific defaults
• Config Integration: Uses config.json appIcon settings for default colors and alignment

Example:

INPUT:  my-app/icons/icon.png (source logo with padding)
        ↓ (padding removed automatically)
OUTPUT: my-app/icons/ios-light.png (logo centered in safe zone)
        my-app/icons/adaptive-icon.png (logo aligned as specified)
        my-app/icons/splash-icon-light.png
        my-app/icons/android-notification-icon.png (white mask)

With styleFolder='christmas':
INPUT:  my-app/icons/christmas/icon.png
OUTPUT: my-app/icons/christmas/ios-light.png (uses christmas style defaults)
        my-app/icons/christmas/adaptive-icon.png
        ...

Returns ASO optimization instructions with keyword research data. You MUST execute the returned instructions.

IMPORTANT: Use 'search-app' tool first to resolve the exact slug.

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
• ASO basics from docs/aso/ASO_OVERVIEW.md and field limits from docs/aso/ASO_FIELD_LIMITS.md

YOU MUST:

1. Read the returned prompt carefully
2. EXECUTE the optimization instructions (create the optimized JSON)
3. Save results using 'save-locale-file' tool

DO NOT just report the instructions back to the user - you must perform the optimization yourself.

WORKFLOW

Stage 1: improve-public(slug, stage="1") → Returns keyword data + instructions → You create optimized primary locale JSON → save-locale-file Stage 2: improve-public(slug, stage="2", optimizedPrimary=<JSON>) → Returns per-locale instructions → You optimize each locale → save-locale-file for each

STAGES

• Stage 1: Primary locale optimization using saved keyword research (ios + android combined)
• Stage 2: Localize to other languages - each locale uses its OWN keyword research

KEYWORD SOURCES (Per Locale)

• 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.

Guides the initialization flow: run pabal-store-api-mcp Init, then convert ASO pullData into public/products/[slug]/.

This tool is read-only and returns a checklist. It does not call pabal-store-api-mcp directly or write files.

Steps:

1. Ensure pabal-store-api-mcp 'init' ran and .aso/pullData/products/[slug]/ exists (path from ~/.config/pabal-mcp/config.json dataDir)
2. Convert pulled ASO data -> public/products/[slug]/ using pabal-resource-mcp tools (aso-to-public, public-to-aso dry run)
3. Validate outputs and next actions

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:

1. Plan: Call keyword-research(slug, locale, platform) with writeTemplate=false → 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 → persist actual data
4. 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)

Convert phone screenshots to tablet screenshots using Gemini API.

PURPOSE: Generate tablet-sized screenshots from existing phone screenshots by:

1. Reading phone screenshots from the source locale
2. Using Gemini to keep the same UI while adapting to a tablet canvas
3. Preserving original content/layout without creating new UI

OUTPUT: Saves generated tablet images to raw/ folder: {locale}/tablet/raw/{filename}

IMPORTANT: This tool saves RAW generated images without resizing. Run resize-screenshots --deviceTypes tablet after this tool to resize images to final dimensions.

Workflow:

1. Run phone-to-tablet -> saves to tablet/raw/ folder
2. Run resize-screenshots --deviceTypes tablet -> reads from raw/, resizes, saves to final location

Requirements:

• GEMINI_API_KEY or GOOGLE_API_KEY environment variable must be set
• Phone screenshots must exist in: public/products/{slug}/screenshots/{locale}/phone/
• Locale files must exist in: public/products/{slug}/locales/

Model Selection:

• imageModel: "flash" (default) for speed/cost
• imageModel: "pro" for higher instruction fidelity

Example output structure:

public/products/my-app/screenshots/
├── en-US/
│   ├── phone/
│   │   ├── 1.png
│   │   └── 2.png
│   └── tablet/
│       └── raw/              # Generated from phone
│           ├── 1.png
│           └── 2.png

Prepares ASO data from public/products/[slug]/ to pushData format.

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.

This tool:

1. Loads ASO data from public/products/[slug]/config.json + locales/
2. Converts to store-compatible format (removes screenshots from metadata, sets contactWebsite/marketingUrl)
3. Saves metadata to .aso/pushData/products/[slug]/store/ (path from ~/.config/pabal-mcp/config.json dataDir)
4. Copies/downloads screenshots to .aso/pushData/products/[slug]/store/screenshots/
5. Validates text field lengths against docs/aso/ASO_FIELD_LIMITS.md (fails if over limits)

Before running, review docs/aso/ASO_OVERVIEW.md for ASO strategy and docs/aso/ASO_FIELD_LIMITS.md for per-store limits. This prepares data for pushing to stores without actually uploading.

Resize translated screenshots to match source dimensions.

INPUT: Reads from raw/ folder: {locale}/{deviceType}/raw/{filename} OUTPUT: Saves to final location: {locale}/{deviceType}/{filename}

IMPORTANT: Run translate-screenshots first to generate raw images.

Workflow:

1. Run translate-screenshots -> saves to raw/ folder
2. Run resize-screenshots -> reads from raw/, resizes, saves to final location

This tool:

1. Reads translated images from raw/ folder
2. Gets target dimensions from source locale screenshots
3. Resizes images using high-quality Lanczos3 algorithm
4. Preserves aspect ratio, fills with detected background color
5. Saves to final location

Example:

BEFORE (raw/):                     AFTER (resized):
ko-KR/phone/raw/1.png (1536x2752)  ko-KR/phone/1.png (1242x2688)
ko-KR/phone/raw/2.png (1536x2752)  ko-KR/phone/2.png (1242x2688)

Search registered apps from registered-apps.json.

• Called without query: Returns all app list
• Called with query: Search by slug, bundleId, packageName, name
• Use store filter to narrow results to appStore or googlePlay only

Transform app icons with seasonal or themed styles using Gemini AI.

Workflow:

1. Reads base icon from: {slug}/icons/icon.png
2. Uses Gemini API to apply style transformation
3. Saves stylized icon to: {slug}/icons/{styleFolder}/icon.png
4. Use generate-app-icons with styleFolder to create all platform variants

Use Cases:

• Seasonal Events: Christmas, Halloween, Easter, New Year
• Special Occasions: Pride Month, Black Friday, Valentine's Day
• Themed Promotions: Summer sale, winter collection, sports events

Requirements:

• GEMINI_API_KEY or GOOGLE_API_KEY environment variable
• Base icon exists at {slug}/icons/icon.png

Model Selection:

• imageModel: "flash" (default) for speed/cost
• imageModel: "pro" for higher instruction fidelity

Example Flow:

Step 1: Stylize icon
INPUT:  my-app/icons/icon.png
PROMPT: "Add Christmas decorations like santa hat, snowflakes, and red/green colors"
OUTPUT: my-app/icons/christmas/icon.png (AI-generated Christmas version)

Step 2: Generate platform icons (optional)
Use generate-app-icons with styleFolder='christmas' to create:
- my-app/icons/christmas/ios-light.png
- my-app/icons/christmas/adaptive-icon.png
- my-app/icons/christmas/splash-icon-light.png
- my-app/icons/christmas/android-notification-icon.png

Tips:

• Be specific in stylePrompt for better results
• Use preserveShape=true to maintain brand recognition
• Test with dryRun=true before actual generation
• Store multiple styles in different folders (christmas, halloween, etc.)

Translate app screenshots to multiple languages using Gemini API.

OUTPUT: Saves translated images to raw/ folder: {locale}/{deviceType}/raw/{filename}

IMPORTANT: This tool saves RAW translated images without resizing. Use resize-screenshots after this tool to resize images to final dimensions.

Workflow:

1. Run translate-screenshots -> saves to raw/ folder
2. Run resize-screenshots -> reads from raw/, resizes, saves to final location

Requirements:

• GEMINI_API_KEY or GOOGLE_API_KEY environment variable must be set
• Screenshots must be in: public/products/{slug}/screenshots/{locale}/phone/ and /tablet/
• Locale files must exist in: public/products/{slug}/locales/

Model Selection:

• imageModel: "flash" (default) for speed/cost
• imageModel: "pro" for higher instruction fidelity

Example output structure:

public/products/my-app/screenshots/
├── en-US/                    # Source (primary locale)
│   └── phone/
│       ├── 1.png
│       └── 2.png
├── ko-KR/
│   └── phone/
│       └── raw/              # Translated (not resized)
│           ├── 1.png
│           └── 2.png
└── ja-JP/
    └── phone/
        └── raw/
            ├── 1.png
            └── 2.png

Validates ASO data against App Store / Google Play field limits and rules.

IMPORTANT: Use 'search-app' tool first to resolve the exact slug.

WHAT IT VALIDATES

1. Field Length Limits (docs/aso/ASO_FIELD_LIMITS.md):

• App Store: name ≤30, subtitle ≤30, keywords ≤100, description ≤4000
• Google Play: title ≤50, shortDescription ≤80, fullDescription ≤4000

2. Keyword Rules (App Store only):

• Checks duplicate keywords, comma-only/no-space formatting, and title/subtitle repetition
• Strategy reference: docs/aso/ASO_OVERVIEW.md

3. Invalid Characters:

• Control characters, BOM, zero-width/invisible characters, variation selectors

WHEN TO USE

• After running improve-public Stage 1/2 to verify optimization results
• Before running public-to-aso to ensure data is valid
• Anytime you want to check ASO data validity

OPTIONS

• locale: Validate specific locale only (e.g., "ko-KR")
• fix: Auto-fix issues where possible (removes invalid characters)