analyze_top_keywords

Analyze top-ranking apps for a keyword to understand competitive positioning and market trends on iOS or Android app stores.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`keyword`	Yes	The keyword or search term to analyze (e.g., 'meditation app', 'puzzle games').
`platform`	Yes	The platform (app store) to analyze ('ios' for Apple App Store, 'android' for Google Play Store).
`num`	No	Number of top apps ranking for the keyword to analyze (1-50, default 10). These apps will be fetched with full details to provide comprehensive analysis.
`country`	No	Two-letter country code for store localization. Default 'us'.	us
`lang`	No	Language code for results. Default 'en'.	en

Implementation Reference

server.js:272-432 (registration)

Registration of the 'analyze_top_keywords' tool using McpServer.tool(), including schema and handler callback.

server.tool(
  "analyze_top_keywords",
  {
    keyword: z.string().describe("The keyword or search term to analyze (e.g., 'meditation app', 'puzzle games')."),
    platform: z.enum(["ios", "android"]).describe("The platform (app store) to analyze ('ios' for Apple App Store, 'android' for Google Play Store)."),
    num: z.number().optional().default(10).describe("Number of top apps ranking for the keyword to analyze (1-50, default 10). These apps will be fetched with full details to provide comprehensive analysis."),
    country: z.string().length(2).optional().default("us").describe("Two-letter country code for store localization. Default 'us'."),
    lang: z.string().optional().default("en").describe("Language code for results. Default 'en'.")
  },
  async ({ keyword, platform, num, country, lang }) => {
    try {
      let results = [];
      
      if (platform === "android") {
        // Get search results from Google Play Store
        results = await memoizedGplay.search({
          term: keyword,
          num,
          country,
          lang,
          fullDetail: true
        });
      } else {
        // Get search results from Apple App Store
        results = await memoizedAppStore.search({
          term: keyword,
          num,
          country,
          lang
        });
        
        // For Apple, we need to fetch full details for each app
        const fullDetailsPromises = results.map(app => {
          try {
            return memoizedAppStore.app({ id: app.id, country, lang, ratings: true });
          } catch (err) {
            console.error(`Error fetching details for app ${app.id}:`, err);
            return app; // Return original data if full details fetch fails
          }
        });
        
        // Wait for all detail requests to complete
        results = await Promise.all(fullDetailsPromises);
      }
      
      // Normalize and extract key metrics
      const normalizedApps = results.map(app => {
        if (platform === "android") {
          return {
            appId: app.appId,
            title: app.title,
            developer: app.developer,
            developerId: app.developerId,
            installs: app.installs,
            minInstalls: app.minInstalls,
            score: app.score,
            ratings: app.ratings,
            free: app.free,
            price: app.price,
            currency: app.currency,
            category: app.genre,
            url: app.url,
            icon: app.icon
          };
        } else {
          return {
            appId: app.appId,
            title: app.title,
            developer: app.developer,
            developerId: app.developerId,
            score: app.score,
            ratings: app.ratings || 0,
            free: app.free,
            price: app.price,
            currency: app.currency,
            category: app.primaryGenre,
            url: app.url,
            icon: app.icon
          };
        }
      });
      
      // Calculate brand presence metrics
      const developerCounts = {};
      normalizedApps.forEach(app => {
        developerCounts[app.developer] = (developerCounts[app.developer] || 0) + 1;
      });
      
      // Sort developers by number of apps in results
      const sortedDevelopers = Object.entries(developerCounts)
        .sort((a, b) => b[1] - a[1])
        .map(entry => entry[0]);
      
      // Calculate average ratings and other metrics
      const totalApps = normalizedApps.length;
      const avgRating = normalizedApps.reduce((sum, app) => sum + (app.score || 0), 0) / totalApps;
      const paidApps = normalizedApps.filter(app => !app.free);
      const paidPercentage = (paidApps.length / totalApps) * 100;
      
      // Check for big brand presence (simplified algorithm)
      // Here we're assuming the top 2 developers with most apps are "big brands"
      const topBrands = sortedDevelopers.slice(0, 2);
      const topBrandAppsCount = topBrands.reduce((count, brand) => 
        count + developerCounts[brand], 0);
      const brandDominance = topBrandAppsCount / totalApps;
      
      // Determine competition level
      let competitionLevel;
      if (brandDominance > 0.7) {
        competitionLevel = "Low - dominated by major brands";
      } else if (brandDominance > 0.4) {
        competitionLevel = "Medium - mix of major brands and independents";
      } else {
        competitionLevel = "High - diverse set of developers";
      }
      
      // Create category distribution
      const categoryDistribution = {};
      normalizedApps.forEach(app => {
        const category = app.category;
        if (category) {
          categoryDistribution[category] = (categoryDistribution[category] || 0) + 1;
        }
      });
      
      return {
        content: [{ 
          type: "text", 
          text: JSON.stringify({
            keyword,
            platform,
            topApps: normalizedApps,
            brandPresence: {
              topBrands,
              brandDominance: parseFloat(brandDominance.toFixed(2)),
              competitionLevel
            },
            metrics: {
              totalApps,
              averageRating: parseFloat(avgRating.toFixed(2)),
              paidAppsPercentage: parseFloat(paidPercentage.toFixed(2)),
              categoryDistribution
            }
          }, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{ 
          type: "text", 
          text: JSON.stringify({
            error: error.message,
            keyword,
            platform
          }, null, 2)
        }],
        isError: true
      };
    }
  }
);

server.js:274-280 (schema)

Zod input schema defining parameters: keyword (string), platform (ios/android), num (number, optional), country (string, optional), lang (string, optional). Used for validation in MCP tool calls.

{
  keyword: z.string().describe("The keyword or search term to analyze (e.g., 'meditation app', 'puzzle games')."),
  platform: z.enum(["ios", "android"]).describe("The platform (app store) to analyze ('ios' for Apple App Store, 'android' for Google Play Store)."),
  num: z.number().optional().default(10).describe("Number of top apps ranking for the keyword to analyze (1-50, default 10). These apps will be fetched with full details to provide comprehensive analysis."),
  country: z.string().length(2).optional().default("us").describe("Two-letter country code for store localization. Default 'us'."),
  lang: z.string().optional().default("en").describe("Language code for results. Default 'en'.")
},

server.js:281-431 (handler)

Handler function performs keyword search on specified platform using memoized scrapers (gplay/appStore), fetches top apps, normalizes data, computes brand presence/dominance, competition level, average ratings, paid app percentage, category distribution, and returns structured JSON analysis.

async ({ keyword, platform, num, country, lang }) => {
  try {
    let results = [];
    
    if (platform === "android") {
      // Get search results from Google Play Store
      results = await memoizedGplay.search({
        term: keyword,
        num,
        country,
        lang,
        fullDetail: true
      });
    } else {
      // Get search results from Apple App Store
      results = await memoizedAppStore.search({
        term: keyword,
        num,
        country,
        lang
      });
      
      // For Apple, we need to fetch full details for each app
      const fullDetailsPromises = results.map(app => {
        try {
          return memoizedAppStore.app({ id: app.id, country, lang, ratings: true });
        } catch (err) {
          console.error(`Error fetching details for app ${app.id}:`, err);
          return app; // Return original data if full details fetch fails
        }
      });
      
      // Wait for all detail requests to complete
      results = await Promise.all(fullDetailsPromises);
    }
    
    // Normalize and extract key metrics
    const normalizedApps = results.map(app => {
      if (platform === "android") {
        return {
          appId: app.appId,
          title: app.title,
          developer: app.developer,
          developerId: app.developerId,
          installs: app.installs,
          minInstalls: app.minInstalls,
          score: app.score,
          ratings: app.ratings,
          free: app.free,
          price: app.price,
          currency: app.currency,
          category: app.genre,
          url: app.url,
          icon: app.icon
        };
      } else {
        return {
          appId: app.appId,
          title: app.title,
          developer: app.developer,
          developerId: app.developerId,
          score: app.score,
          ratings: app.ratings || 0,
          free: app.free,
          price: app.price,
          currency: app.currency,
          category: app.primaryGenre,
          url: app.url,
          icon: app.icon
        };
      }
    });
    
    // Calculate brand presence metrics
    const developerCounts = {};
    normalizedApps.forEach(app => {
      developerCounts[app.developer] = (developerCounts[app.developer] || 0) + 1;
    });
    
    // Sort developers by number of apps in results
    const sortedDevelopers = Object.entries(developerCounts)
      .sort((a, b) => b[1] - a[1])
      .map(entry => entry[0]);
    
    // Calculate average ratings and other metrics
    const totalApps = normalizedApps.length;
    const avgRating = normalizedApps.reduce((sum, app) => sum + (app.score || 0), 0) / totalApps;
    const paidApps = normalizedApps.filter(app => !app.free);
    const paidPercentage = (paidApps.length / totalApps) * 100;
    
    // Check for big brand presence (simplified algorithm)
    // Here we're assuming the top 2 developers with most apps are "big brands"
    const topBrands = sortedDevelopers.slice(0, 2);
    const topBrandAppsCount = topBrands.reduce((count, brand) => 
      count + developerCounts[brand], 0);
    const brandDominance = topBrandAppsCount / totalApps;
    
    // Determine competition level
    let competitionLevel;
    if (brandDominance > 0.7) {
      competitionLevel = "Low - dominated by major brands";
    } else if (brandDominance > 0.4) {
      competitionLevel = "Medium - mix of major brands and independents";
    } else {
      competitionLevel = "High - diverse set of developers";
    }
    
    // Create category distribution
    const categoryDistribution = {};
    normalizedApps.forEach(app => {
      const category = app.category;
      if (category) {
        categoryDistribution[category] = (categoryDistribution[category] || 0) + 1;
      }
    });
    
    return {
      content: [{ 
        type: "text", 
        text: JSON.stringify({
          keyword,
          platform,
          topApps: normalizedApps,
          brandPresence: {
            topBrands,
            brandDominance: parseFloat(brandDominance.toFixed(2)),
            competitionLevel
          },
          metrics: {
            totalApps,
            averageRating: parseFloat(avgRating.toFixed(2)),
            paidAppsPercentage: parseFloat(paidPercentage.toFixed(2)),
            categoryDistribution
          }
        }, null, 2)
      }]
    };
  } catch (error) {
    return {
      content: [{ 
        type: "text", 
        text: JSON.stringify({
          error: error.message,
          keyword,
          platform
        }, null, 2)
      }],
      isError: true
    };
  }
}

mcp-appstore