reviews

Instructions

Implementation Reference

• src/server.js:213-254 (handler)

  Main execution handler for the 'reviews' tool. Builds reviews URL, fetches JSON RSS feed, parses reviews, and returns structured JSON response with pagination.

  async function handleReviews(args) {
    try {
      const {
        id,
        appId,
        country = 'us',
        page = 1,
        sort = 'mostRecent',
      } = args;
  
      if (!id && !appId) {
        throw new Error('Either id or appId must be provided');
      }
  
      const url = buildReviewsUrl({ id, appId, country, page, sort });
      const data = await fetchJSON(url);
      const reviews = parseReviews(data);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              page,
              reviews,
              count: reviews.length,
            }, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: error.message }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/server.js:1028-1059 (schema)

  Tool schema definition including name, description, and input schema for validation in ListTools response.

    name: 'reviews',
    description: 'Get app reviews with pagination',
    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',
        },
        page: {
          type: 'number',
          description: 'Page number (1-10, default: 1)',
          default: 1,
        },
        sort: {
          type: 'string',
          description: 'Sort order: mostRecent or mostHelpful',
          default: 'mostRecent',
          enum: ['mostRecent', 'mostHelpful'],
        },
      },
    },
  },

• src/server.js:1451-1452 (registration)

  Registration of the 'reviews' tool handler in the CallToolRequestSchema switch dispatcher.

  case 'reviews':
    return await handleReviews(args);

• src/parsers/appStore/reviews.js:10-53 (helper)

  Helper parser that normalizes iTunes RSS feed reviews into a structured array of review objects.

  export function parseReviews(data) {
    if (!data || !data.feed || !data.feed.entry) {
      return [];
    }
  
    // First entry is app metadata, skip it
    const reviews = Array.isArray(data.feed.entry) 
      ? data.feed.entry.slice(1) 
      : [];
  
    return reviews.map(entry => {
      const author = entry.author?.[0] || entry.author || {};
      const rating = entry['im:rating']?.label || entry['im:rating'] || '0';
      const version = entry['im:version']?.label || entry['im:version'] || null;
      const title = entry.title?.label || entry.title || null;
      const content = entry.content?.label || entry.content?.[0]?.label || entry.content || null;
      const updated = entry.updated?.label || entry.updated || null;
      const id = entry.id?.label || entry.id || null;
  
      // Extract user ID from author URI if available
      let userId = null;
      let userUrl = null;
      if (author.uri?.label || author.uri) {
        const uri = author.uri.label || author.uri;
        const match = uri.match(/\/id(\d+)/);
        if (match) {
          userId = match[1];
          userUrl = uri;
        }
      }
  
      return {
        id: id || null,
        userName: author.name?.label || author.name || 'Anonymous',
        userUrl: userUrl || null,
        version: version,
        score: parseInt(rating, 10) || 0,
        title: title,
        text: content,
        updated: updated,
        url: entry.link?.[0]?.attributes?.href || entry.link?.attributes?.href || null,
      };
    });
  }

• src/endpoints/appStore.js:79-91 (helper)

  Helper function to construct the App Store reviews RSS feed URL with pagination and sorting.

  export function buildReviewsUrl(params) {
    const { id, appId, country = 'us', page = 1, sort = 'mostRecent' } = params;
    
    if (!id && !appId) {
      throw new Error('Either id or appId must be provided');
    }
    
    const appIdParam = id || appId;
    const pageNum = Math.min(page, 10); // Max 10 pages
    const sortParam = sort === 'mostHelpful' ? 'mostHelpful' : 'mostRecent';
    
    return `${ITUNES_BASE}/${country}/rss/customerreviews/page=${pageNum}/id=${appIdParam}/sortby=${sortParam}/json`;
  }