list
Retrieve app rankings from app stores, including top free, paid, and grossing charts by country and genre.
Instructions
Get app rankings (top free, paid, or grossing)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chart | No | Chart type: topfreeapplications, toppaidapplications, or topgrossingapplications | topfreeapplications |
| country | No | Two-letter country code (default: us) | us |
| genre | No | Genre ID or "all" (default: all) | all |
| limit | No | Number of results (default: 200) |
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; }