gp_similar

Instructions

Implementation Reference

• src/server.js:741-775 (handler)

  Main handler function that executes the gp_similar tool: validates args, builds URL, fetches HTML, parses similar apps, and returns JSON response.

  async function handleGPSimilar(args) {
    try {
      const { appId, lang = 'en', country = 'us' } = args;
  
      if (!appId) {
        throw new Error('appId is required');
      }
  
      const url = buildGPSimilarUrl({ appId, lang, country });
      const html = await fetchText(url);
      const similarApps = parseGPSimilar(html);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              similarApps,
              count: similarApps.length,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: error.message }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/server.js:1332-1355 (schema)

  Input schema definition and tool registration in the list of tools returned by ListToolsRequest.

  {
    name: 'gp_similar',
    description: '[Google Play] Get apps similar to the specified app',
    inputSchema: {
      type: 'object',
      properties: {
        appId: {
          type: 'string',
          description: 'Google Play app ID',
        },
        lang: {
          type: 'string',
          description: 'Language code (default: en)',
          default: 'en',
        },
        country: {
          type: 'string',
          description: 'Two-letter country code (default: us)',
          default: 'us',
        },
      },
      required: ['appId'],
    },
  },

• src/server.js:1476-1477 (registration)

  Dispatch registration in the CallToolRequest switch statement that routes to the handler.

  case 'gp_similar':
    return await handleGPSimilar(args);

• src/parsers/googlePlay/similar.js:10-99 (helper)

  Parser function that extracts similar apps data from the Google Play app page HTML using regex on sections and scripts.

  export function parseSimilar(html) {
    if (!html || typeof html !== 'string') {
      return [];
    }
  
    const similarApps = [];
  
    try {
      // Google Play similar apps are in a "You might also like" section
      // Look for similar apps section
      const similarSection = html.match(/<div[^>]*class=["'][^"']*similar["'][^>]*>([\s\S]*?)<\/div>/i) ||
                             html.match(/<section[^>]*class=["'][^"']*you-might-also-like["'][^>]*>([\s\S]*?)<\/section>/i);
  
      if (similarSection) {
        const sectionHtml = similarSection[1];
        
        // Extract app links
        const appLinkMatches = sectionHtml.matchAll(/<a[^>]*href=["']\/store\/apps\/details\?id=([^&"']+)["'][^>]*>/gi);
        
        for (const match of appLinkMatches) {
          const appId = match[1];
          
          // Try to extract title and other info from surrounding HTML
          const linkStart = sectionHtml.indexOf(match[0]);
          const contextHtml = sectionHtml.substring(Math.max(0, linkStart - 500), linkStart + 500);
          
          const titleMatch = contextHtml.match(/<span[^>]*title=["']([^"']+)["']/i) ||
                            contextHtml.match(/<div[^>]*class=["'][^"']*title["'][^>]*>([^<]+)<\/div>/i);
          const title = titleMatch ? titleMatch[1].trim() : null;
  
          const iconMatch = contextHtml.match(/<img[^>]*src=["']([^"']+)["'][^>]*>/i);
          const icon = iconMatch ? iconMatch[1] : null;
  
          const scoreMatch = contextHtml.match(/(\d+\.?\d*)\s*stars?/i);
          const score = scoreMatch ? parseFloat(scoreMatch[1]) : null;
  
          if (appId && !similarApps.find(a => a.appId === appId)) {
            similarApps.push({
              appId: appId,
              url: `https://play.google.com/store/apps/details?id=${appId}`,
              title: title,
              icon: icon,
              score: score,
              scoreText: score ? score.toFixed(1) : null,
              priceText: null,
              free: null,
              summary: null,
              developer: null,
              developerId: null,
            });
          }
        }
      }
  
      // Also try extracting from script tags
      const scriptMatches = html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/gi);
      
      for (const match of scriptMatches) {
        const scriptContent = match[1];
        
        if (scriptContent.includes('similar') || scriptContent.includes('recommended')) {
          try {
            // Try to find similar apps in JSON structures
            const similarMatch = scriptContent.match(/similarApps["']?\s*:\s*\[([\s\S]*?)\]/i);
            if (similarMatch) {
              const similarData = similarMatch[1];
              const appIdMatches = similarData.matchAll(/id["']?\s*:\s*["']([^"']+)["']/gi);
              
              for (const idMatch of appIdMatches) {
                const appId = idMatch[1];
                if (appId && !similarApps.find(a => a.appId === appId)) {
                  similarApps.push({
                    appId: appId,
                    url: `https://play.google.com/store/apps/details?id=${appId}`,
                  });
                }
              }
            }
          } catch (e) {
            // Continue
          }
        }
      }
  
      return similarApps;
    } catch (error) {
      console.error('Error parsing Google Play similar apps:', error);
      return [];
    }
  }

• src/endpoints/googlePlay.js:136-144 (helper)

  URL builder for the Google Play app details page (where similar apps are listed).

  export function buildSimilarUrl(params) {
    const { appId, lang = 'en', country = 'us' } = params;
    
    if (!appId) {
      throw new Error('appId is required');
    }
  
    return `${GOOGLE_PLAY_BASE}/store/apps/details?id=${appId}&gl=${country}&hl=${lang}`;
  }