app

Instructions

Implementation Reference

• src/server.js:77-122 (handler)

  The main handler function that implements the core logic of the 'app' MCP tool. It builds the App Store lookup URL, fetches the data, parses it, and returns formatted JSON.

  /**
   * App tool - Get detailed information about an app
   */
  async function handleApp(args) {
    try {
      const { id, appId, country = 'us' } = args;
      
      if (!id && !appId) {
        throw new Error('Either id or appId must be provided');
      }
  
      const url = buildAppUrl({ 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),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(app, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: error.message }, null, 2),
          },
        ],
        isError: true,
      };
    }
  }

• src/server.js:942-962 (schema)

  The input schema definition for the 'app' tool, defining parameters like id, appId, and country.

    name: 'app',
    description: 'Get detailed information about an app by ID or bundleId',
    inputSchema: {
      type: 'object',
      properties: {
        id: {
          type: 'number',
          description: 'iTunes trackId of the app (e.g., 553834731)',
        },
        appId: {
          type: 'string',
          description: 'Bundle ID of the app (e.g., com.midasplayer.apps.candycrushsaga)',
        },
        country: {
          type: 'string',
          description: 'Two-letter country code (default: us)',
          default: 'us',
        },
      },
    },
  },

• src/server.js:1445-1446 (registration)

  The switch case that registers and routes calls to the 'app' tool handler in the CallToolRequestSchema.

  case 'app':
    return await handleApp(args);

• src/parsers/appStore/app.js:10-67 (helper)

  The parseApp helper function that normalizes raw iTunes API response into a structured app object used by the handler.

  export function parseApp(data) {
    if (!data || !data.results || data.results.length === 0) {
      return null;
    }
  
    const app = data.results[0];
  
    return {
      id: app.trackId || null,
      appId: app.bundleId || null,
      title: app.trackName || null,
      url: app.trackViewUrl || null,
      description: app.description || null,
      releaseNotes: app.releaseNotes || null,
      version: app.version || null,
      releaseDate: app.releaseDate || null,
      currentVersionReleaseDate: app.currentVersionReleaseDate || null,
      price: app.price || 0,
      currency: app.currency || null,
      free: app.price === 0,
      developer: {
        id: app.artistId || null,
        name: app.artistName || null,
        url: app.artistViewUrl || null,
      },
      category: {
        id: app.primaryGenreId || null,
        name: app.primaryGenreName || null,
        genres: app.genres || [],
      },
      rating: {
        average: app.averageUserRating || null,
        count: app.userRatingCount || 0,
      },
      contentAdvisoryRating: app.contentAdvisoryRating || null,
      screenshotUrls: app.screenshotUrls || [],
      ipadScreenshotUrls: app.ipadScreenshotUrls || [],
      appletvScreenshotUrls: app.appletvScreenshotUrls || [],
      artwork: {
        icon: app.artworkUrl512 || app.artworkUrl100 || app.artworkUrl60 || null,
        icon60: app.artworkUrl60 || null,
        icon100: app.artworkUrl100 || null,
        icon512: app.artworkUrl512 || null,
      },
      supportedDevices: app.supportedDevices || [],
      minimumOsVersion: app.minimumOsVersion || null,
      languageCodesISO2A: app.languageCodesISO2A || [],
      fileSizeBytes: app.fileSizeBytes || null,
      sellerName: app.sellerName || null,
      formattedPrice: app.formattedPrice || null,
      isGameCenterEnabled: app.isGameCenterEnabled || false,
      features: app.features || [],
      advisories: app.advisories || [],
      kind: app.kind || null,
      averageUserRatingForCurrentVersion: app.averageUserRatingForCurrentVersion || null,
      userRatingCountForCurrentVersion: app.userRatingCountForCurrentVersion || 0,
    };
  }

• src/endpoints/appStore.js:42-55 (helper)

  The buildAppUrl helper that constructs the correct iTunes lookup URL based on id or appId parameters.

  export function buildAppUrl(params) {
    const { id, appId, country = 'us' } = params;
    
    if (id) {
      return `${ITUNES_BASE}/lookup?id=${id}&country=${country}`;
    }
    
    if (appId) {
      // First lookup by bundleId to get trackId
      return `${ITUNES_BASE}/lookup?bundleId=${appId}&country=${country}`;
    }
    
    throw new Error('Either id or appId must be provided');
  }