list

Instructions

Implementation Reference

• src/server.js:166-208 (handler)

  Core handler function for the 'list' MCP tool. Fetches App Store ranking data via RSS/JSON endpoints and parses into structured app results.

  /**
   * List tool - Get app rankings (top free, paid, grossing)
   */
  async function handleList(args) {
    try {
      const {
        chart = 'topfreeapplications',
        category = 'all',
        country = 'us',
        genre = 'all',
        limit = 200,
      } = args;
  
      const url = buildListUrl({ chart, category, country, genre, limit });
      const data = await fetchJSON(url);
      // Use parseList for RSS feed format, fallback to parseApps for JSON format
      const apps = data.feed ? parseList(data) : parseApps(data);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              chart,
              country,
              results: apps,
              count: apps.length,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: error.message }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/server.js:1000-1025 (schema)

  Input schema for the 'list' tool, defining parameters for chart type, country, genre, and limit with types, descriptions, defaults, and enums.

  inputSchema: {
    type: 'object',
    properties: {
      chart: {
        type: 'string',
        description: 'Chart type: topfreeapplications, toppaidapplications, or topgrossingapplications',
        default: 'topfreeapplications',
        enum: ['topfreeapplications', 'toppaidapplications', 'topgrossingapplications'],
      },
      country: {
        type: 'string',
        description: 'Two-letter country code (default: us)',
        default: 'us',
      },
      genre: {
        type: 'string',
        description: 'Genre ID or "all" (default: all)',
        default: 'all',
      },
      limit: {
        type: 'number',
        description: 'Number of results (default: 200)',
        default: 200,
      },
    },
  },

• src/server.js:998-1026 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name 'list', description, and input schema for MCP tool discovery.

    name: 'list',
    description: 'Get app rankings (top free, paid, or grossing)',
    inputSchema: {
      type: 'object',
      properties: {
        chart: {
          type: 'string',
          description: 'Chart type: topfreeapplications, toppaidapplications, or topgrossingapplications',
          default: 'topfreeapplications',
          enum: ['topfreeapplications', 'toppaidapplications', 'topgrossingapplications'],
        },
        country: {
          type: 'string',
          description: 'Two-letter country code (default: us)',
          default: 'us',
        },
        genre: {
          type: 'string',
          description: 'Genre ID or "all" (default: all)',
          default: 'all',
        },
        limit: {
          type: 'number',
          description: 'Number of results (default: 200)',
          default: 200,
        },
      },
    },
  },

• src/server.js:1449-1450 (registration)

  Dispatch registration in CallToolRequestSchema handler's switch statement, routing 'list' tool invocations to the handleList function.

  case 'list':
    return await handleList(args);

• src/parsers/appStore/list.js:12-56 (helper)

  Helper function parseList that processes the raw RSS/JSON data from App Store rankings into an array of normalized app objects.

  export function parseList(data) {
    if (!data || !data.feed) {
      return [];
    }
  
    const apps = [];
  
    try {
      // RSS feed format has entries in feed.entry
      if (data.feed.entry && Array.isArray(data.feed.entry)) {
        for (const entry of data.feed.entry) {
          // Convert RSS entry to app format
          const app = {
            trackId: extractId(entry),
            bundleId: extractBundleId(entry),
            trackName: extractTitle(entry),
            artistName: extractArtist(entry),
            artistId: extractArtistId(entry),
            description: extractDescription(entry),
            price: extractPrice(entry),
            currency: 'USD',
            averageUserRating: extractRating(entry),
            userRatingCount: extractRatingCount(entry),
            artworkUrl100: extractIcon(entry),
            artworkUrl512: extractIcon(entry),
            screenshotUrls: extractScreenshots(entry),
            primaryGenreName: extractCategory(entry),
            releaseDate: extractReleaseDate(entry),
            kind: 'software',
          };
  
          // Use parseApp to normalize
          const lookupData = { results: [app] };
          const normalizedApp = parseApp(lookupData);
          if (normalizedApp) {
            apps.push(normalizedApp);
          }
        }
      }
    } catch (error) {
      console.error('Error parsing App Store list:', error);
    }
  
    return apps;
  }