ratings
Retrieve app ratings distribution data from app stores to analyze user feedback patterns and performance metrics.
Instructions
Get app ratings distribution
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | iTunes trackId of the app | |
| appId | No | Bundle ID of the app | |
| country | No | Two-letter country code (default: us) | us |
Implementation Reference
- src/server.js:256-303 (handler)The handler function that executes the 'ratings' tool logic: fetches app data via App Store API, parses it, extracts ratings using parseRatings helper, and returns JSON response.
/** * Ratings tool - Get app ratings distribution */ async function handleRatings(args) { try { const { id, appId, country = 'us' } = args; if (!id && !appId) { throw new Error('Either id or appId must be provided'); } const url = buildRatingsUrl({ id, appId, country }); const data = await fetchJSON(url); const app = parseApp(data); if (!app) { return { content: [ { type: 'text', text: JSON.stringify({ error: 'App not found' }, null, 2), }, ], }; } const ratings = parseRatings(app); return { content: [ { type: 'text', text: JSON.stringify(ratings, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.message }, null, 2), }, ], isError: true, }; } } - src/server.js:1061-1081 (schema)Input schema definition for the 'ratings' tool, defining parameters: id (number), appId (string), country (string, default 'us'). Provided in ListTools response.
name: 'ratings', description: 'Get app ratings distribution', inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'iTunes trackId of the app', }, appId: { type: 'string', description: 'Bundle ID of the app', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, }, }, }, - src/server.js:1453-1454 (registration)Registration of the 'ratings' tool handler in the CallToolRequestSchema switch statement, mapping tool name to handleRatings function.
case 'ratings': return await handleRatings(args); - Helper function to parse ratings data from app object, extracting count and average (histogram unavailable from API, defaults to zeros).
export function parseRatings(appData) { if (!appData || !appData.rating) { return { ratings: 0, histogram: { '1': 0, '2': 0, '3': 0, '4': 0, '5': 0, }, }; } // iTunes API doesn't provide histogram directly // We can only return the average and count // For histogram, we'd need to scrape the web page, which is more complex // For now, return what we have return { ratings: appData.rating.count || 0, average: appData.rating.average || null, histogram: { '1': 0, // Not available from API '2': 0, '3': 0, '4': 0, '5': 0, }, }; } - src/endpoints/appStore.js:98-100 (helper)Helper function to build the API URL for ratings data (reuses the app detail endpoint).
export function buildRatingsUrl(params) { return buildAppUrl(params); }