aso-pull
Fetch ASO data from App Store and Google Play to save locally for analysis, supporting both stores with configurable options.
Instructions
Fetch ASO data from App Store/Google Play and save to local cache.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Registered app slug (app registered via apps-init) | |
| packageName | No | Google Play package name | |
| bundleId | No | App Store bundle ID | |
| store | No | Target store (default: both) | |
| dryRun | No | If true, only outputs result without actually saving |
Implementation Reference
- src/tools/aso/pull.ts:175-377 (handler)Main handler function that resolves the app, fetches ASO data from App Store/Google Play using services, optionally downloads screenshots, updates registered apps locales, and saves to local cache or returns dry-run preview.
export async function handleAsoPull(options: AsoPullOptions) { const { app, store, dryRun = false } = options; let { packageName, bundleId } = options; const { store: targetStore, includeAppStore, includeGooglePlay, } = getStoreTargets(store); const resolved = appResolutionService.resolve({ slug: app, packageName, bundleId, }); if (!resolved.success) { return { content: [ { type: "text" as const, text: resolved.error.message, }, ], }; } const { slug, bundleId: resolvedBundleId, packageName: resolvedPackageName, hasAppStore, hasGooglePlay, } = resolved.data; bundleId = resolvedBundleId; packageName = resolvedPackageName; console.error(`[MCP] 📥 Pulling ASO data`); console.error(`[MCP] Store: ${targetStore}`); console.error(`[MCP] App: ${slug}`); if (packageName) console.error(`[MCP] Package Name: ${packageName}`); if (bundleId) console.error(`[MCP] Bundle ID: ${bundleId}`); console.error(`[MCP] Mode: ${dryRun ? "Dry run" : "Actual fetch"}`); let config; try { config = loadConfig(); } catch (error) { const message = error instanceof Error ? error.message : String(error); return { content: [ { type: "text" as const, text: `❌ Failed to load config: ${message}` }, ], isError: true, }; } const syncedData: AsoData = {}; const pullDir = getAsoPullDir(); if (includeGooglePlay) { if (!hasGooglePlay) { console.error( `[MCP] ⏭️ Skipping Google Play (not registered for Google Play)` ); } else if (!config.playStore) { console.error( `[MCP] ⏭️ Skipping Google Play (not configured in ~/.config/pabal-mcp/config.json)` ); } else if (!packageName) { console.error( `[MCP] ⏭️ Skipping Google Play (no packageName provided)` ); } else { const clientResult = googlePlayService.createClient(packageName); if (!clientResult.success) { console.error( `[MCP] ❌ Failed to create Google Play client: ${clientResult.error.message}` ); } else { try { console.error(`[MCP] 📥 Fetching from Google Play...`); const data = await clientResult.data.pullAllLanguagesAsoData(); syncedData.googlePlay = data; console.error(`[MCP] ✅ Google Play data fetched`); // Update registered-apps.json with pulled locales if (data.locales && Object.keys(data.locales).length > 0) { const locales = Object.keys(data.locales); try { const updated = updateAppSupportedLocales({ identifier: packageName, store: "googlePlay", locales, }); if (updated) { console.error( `[MCP] ✅ Updated registered-apps.json with ${locales.length} Google Play locales` ); } } catch (updateError) { console.error( `[MCP] ⚠️ Failed to update registered-apps.json: ${ updateError instanceof Error ? updateError.message : String(updateError) }` ); } } } catch (error) { console.error(`[MCP] ❌ Google Play fetch failed:`, error); } } } } if (includeAppStore) { if (!hasAppStore) { console.error( `[MCP] ⏭️ Skipping App Store (not registered for App Store)` ); } else if (!config.appStore) { console.error( `[MCP] ⏭️ Skipping App Store (not configured in ~/.config/pabal-mcp/config.json)` ); } else if (!bundleId) { console.error(`[MCP] ⏭️ Skipping App Store (no bundleId provided)`); } else { const clientResult = appStoreService.createClient(bundleId); if (!clientResult.success) { console.error( `[MCP] ❌ Failed to create App Store client: ${clientResult.error.message}` ); } else { try { console.error(`[MCP] 📥 Fetching from App Store...`); const data = await clientResult.data.pullAllLocalesAsoData(); syncedData.appStore = data; console.error(`[MCP] ✅ App Store data fetched`); // Update registered-apps.json with pulled locales if (data.locales && Object.keys(data.locales).length > 0) { const locales = Object.keys(data.locales); try { const updated = updateAppSupportedLocales({ identifier: bundleId, store: "appStore", locales, }); if (updated) { console.error( `[MCP] ✅ Updated registered-apps.json with ${locales.length} App Store locales` ); } } catch (updateError) { console.error( `[MCP] ⚠️ Failed to update registered-apps.json: ${ updateError instanceof Error ? updateError.message : String(updateError) }` ); } } } catch (error) { console.error(`[MCP] ❌ App Store fetch failed:`, error); } } } } if (dryRun) { return { content: [ { type: "text" as const, text: `📋 Dry run - Data that would be saved:\n${JSON.stringify( syncedData, null, 2 )}`, }, ], }; } saveAsoData(slug, syncedData, { asoDir: pullDir }); await downloadScreenshotsToAso(slug, syncedData, pullDir); return { content: [ { type: "text" as const, text: `✅ ASO data pulled\n` + ` Google Play: ${syncedData.googlePlay ? "✓" : "✗"}\n` + ` App Store: ${syncedData.appStore ? "✓" : "✗"}`, }, ], }; } - src/index.ts:234-255 (registration)Tool registration call that associates the 'aso-pull' name with its description, Zod input schema, the handleAsoPull handler function, and category.
registerToolWithInfo( "aso-pull", { description: "Fetch ASO data from App Store/Google Play and save to local cache.", inputSchema: z.object({ app: z .string() .optional() .describe("Registered app slug (app registered via apps-init)"), packageName: z.string().optional().describe("Google Play package name"), bundleId: z.string().optional().describe("App Store bundle ID"), store: storeSchema.describe("Target store (default: both)"), dryRun: z .boolean() .optional() .describe("If true, only outputs result without actually saving"), }), }, handleAsoPull, "ASO Data Sync" ); - src/index.ts:239-251 (schema)Zod schema defining the input parameters for the aso-pull tool, including optional app slug, packageName, bundleId, store filter, and dryRun flag.
inputSchema: z.object({ app: z .string() .optional() .describe("Registered app slug (app registered via apps-init)"), packageName: z.string().optional().describe("Google Play package name"), bundleId: z.string().optional().describe("App Store bundle ID"), store: storeSchema.describe("Target store (default: both)"), dryRun: z .boolean() .optional() .describe("If true, only outputs result without actually saving"), }), - src/tools/aso/pull.ts:27-33 (schema)TypeScript type interface for the handler input options, matching the Zod schema.
interface AsoPullOptions { app?: string; // Registered app slug packageName?: string; // For Google Play bundleId?: string; // For App Store store?: StoreType; dryRun?: boolean; } - src/tools/aso/pull.ts:35-173 (helper)Helper function called by the handler to download screenshots from fetched ASO data to local ASO directories for both stores.
async function downloadScreenshotsToAso( slug: string, asoData: AsoData, asoDir: string ): Promise<void> { const productStoreRoot = getPullProductAsoDir(slug, asoDir); if (asoData.googlePlay) { const googlePlayData = isGooglePlayMultilingual(asoData.googlePlay) ? asoData.googlePlay : convertToMultilingual( asoData.googlePlay, asoData.googlePlay.defaultLanguage ); const languages = Object.keys(googlePlayData.locales); const defaultLanguage = googlePlayData.defaultLocale; const targetLanguage = (defaultLanguage && googlePlayData.locales[defaultLanguage] ? defaultLanguage : languages[0]) || null; if (targetLanguage) { const localeData = googlePlayData.locales[targetLanguage]; const screenshotDir = getScreenshotDir( productStoreRoot, "google-play", targetLanguage ); if (localeData.screenshots.phone?.length > 0) { console.error( `[MCP] 📥 Downloading ${localeData.screenshots.phone.length} Google Play phone screenshots...` ); for (let i = 0; i < localeData.screenshots.phone.length; i++) { const url = localeData.screenshots.phone[i]; const outputPath = getScreenshotFilePath( screenshotDir, `phone-${i + 1}.png` ); try { if (isLocalAssetPath(url)) { copyLocalAssetToAso(url, outputPath); } else { await downloadImage(url, outputPath); } console.error(`[MCP] ✅ phone-${i + 1}.png`); } catch (error) { console.error( `[MCP] ❌ Failed to handle screenshot ${url}: ${ error instanceof Error ? error.message : String(error) }` ); } } } if (localeData.featureGraphic) { console.error(`[MCP] 📥 Downloading Feature Graphic...`); const outputPath = getScreenshotFilePath( screenshotDir, "feature-graphic.png" ); try { if (isLocalAssetPath(localeData.featureGraphic)) { copyLocalAssetToAso(localeData.featureGraphic, outputPath); } else { await downloadImage(localeData.featureGraphic, outputPath); } console.error(`[MCP] ✅ feature-graphic.png`); } catch (error) { console.error( `[MCP] ❌ Failed to handle feature graphic ${localeData.featureGraphic}: ${ error instanceof Error ? error.message : String(error) }` ); } } } } if (asoData.appStore) { const appStoreData = isAppStoreMultilingual(asoData.appStore) ? asoData.appStore : convertToMultilingual(asoData.appStore, asoData.appStore.locale); const locales = Object.keys(appStoreData.locales); const defaultLocale = appStoreData.defaultLocale; const targetLocale = (defaultLocale && appStoreData.locales[defaultLocale] ? defaultLocale : locales[0]) || null; if (targetLocale) { const localeData = appStoreData.locales[targetLocale]; const screenshotDir = getScreenshotDir( productStoreRoot, "app-store", targetLocale ); const screenshotTypes = ["iphone65", "iphone61", "ipadPro129"] as const; for (const type of screenshotTypes) { const screenshots = localeData.screenshots[type]; if (screenshots && screenshots.length > 0) { console.error( `[MCP] 📥 Downloading ${screenshots.length} App Store ${type} screenshots...` ); for (let i = 0; i < screenshots.length; i++) { let url = screenshots[i]; const outputPath = getScreenshotFilePath( screenshotDir, `${type}-${i + 1}.png` ); if (isLocalAssetPath(url)) { copyLocalAssetToAso(url, outputPath); } else { if (url.includes("{w}") || url.includes("{h}")) { url = resolveAppStoreImageUrl(url); } try { await downloadImage(url, outputPath); } catch (error) { console.error( `[MCP] ❌ Failed to handle screenshot ${url}: ${ error instanceof Error ? error.message : String(error) }` ); } } console.error(`[MCP] ✅ ${type}-${i + 1}.png`); } } } } } }