appstore-mcp 1.0.0

package/src/mcp/resources/index.ts

@@ -0,0 +1,117 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { COUNTRIES } from './countries';
+import { APP_STORE_CATEGORIES, PLATFORMS, PRICING_TYPES } from '../../types';
+
+export function registerAllResources(server: McpServer) {
+    server.registerResource(
+        'countries',
+        'appstore://countries',
+        {
+            description: 'List of all available App Store country codes',
+            mimeType: 'application/json',
+        },
+        async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(
+                        {
+                            count: COUNTRIES.length,
+                            countries: COUNTRIES.map((country) => ({
+                                code: country.code,
+                                name: country.name,
+                            })),
+                        },
+                        null,
+                        2
+                    ),
+                },
+            ],
+        })
+    );
+
+    server.registerResource(
+        'categories',
+        'appstore://categories',
+        {
+            description: 'List of all App Store categories with their IDs',
+            mimeType: 'application/json',
+        },
+        async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(
+                        {
+                            categories: APP_STORE_CATEGORIES.map((category) => ({
+                                id: category.id,
+                                name: category.name,
+                                emoji: category.emoji,
+                            })),
+                        },
+                        null,
+                        2
+                    ),
+                },
+            ],
+        })
+    );
+
+    server.registerResource(
+        'platforms',
+        'appstore://platforms',
+        {
+            description: 'List of supported App Store platforms',
+            mimeType: 'application/json',
+        },
+        async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(
+                        {
+                            platforms: PLATFORMS.map((platform) => ({
+                                value: platform.value,
+                                label: platform.label,
+                                emoji: platform.emoji,
+                            })),
+                        },
+                        null,
+                        2
+                    ),
+                },
+            ],
+        })
+    );
+
+    server.registerResource(
+        'pricing-types',
+        'appstore://pricing-types',
+        {
+            description: 'List of App Store pricing types (free, paid, grossing)',
+            mimeType: 'application/json',
+        },
+        async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(
+                        {
+                            pricingTypes: PRICING_TYPES.map((pricing) => ({
+                                value: pricing.value,
+                                label: pricing.label,
+                                emoji: pricing.emoji,
+                            })),
+                        },
+                        null,
+                        2
+                    ),
+                },
+            ],
+        })
+    );
+}

package/src/mcp/tools/get-app-info.ts

@@ -0,0 +1,183 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { AppStoreService } from '../../services/app-store-service';
+
+type InfoType = 'basic' | 'full' | 'release' | 'screenshots';
+
+function formatDate(dateString?: string): string | null {
+    if (!dateString) return null;
+    const date = new Date(dateString);
+    return date.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    });
+}
+
+export function registerGetAppInfo(server: McpServer) {
+    server.registerTool(
+        'get_app_info',
+        {
+            description:
+                'Get information about a specific app by its App Store ID. Use the "include" parameter to specify what data to return.',
+            inputSchema: {
+                appId: z
+                    .string()
+                    .describe('The App Store ID of the app (numeric ID from the App Store URL)'),
+                country: z
+                    .string()
+                    .optional()
+                    .describe('Country code for the App Store (e.g., US, GB, JP). Defaults to US'),
+                include: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'What info to include: "basic" (name, artist, icon, price, rating), "full" (all details including description), "release" (release dates and version), "screenshots" (screenshot URLs). Defaults to "basic"'
+                    ),
+            },
+        },
+        async ({ appId, country, include }) => {
+            const countryCode = country || 'US';
+            const infoType = (include || 'basic') as InfoType;
+
+            try {
+                const app = await AppStoreService.getAppDetails(appId, countryCode);
+
+                if (!app) {
+                    return {
+                        content: [
+                            {
+                                type: 'text' as const,
+                                text: JSON.stringify(
+                                    {
+                                        success: false,
+                                        error: `App with ID ${appId} not found`,
+                                    },
+                                    null,
+                                    2
+                                ),
+                            },
+                        ],
+                    };
+                }
+
+                let result: Record<string, unknown> = {
+                    success: true,
+                    appId: app.id,
+                    country: countryCode,
+                    include: infoType,
+                };
+
+                switch (infoType) {
+                    case 'basic':
+                        result.app = {
+                            id: app.id,
+                            name: app.name,
+                            artistName: app.artistName,
+                            url: app.url,
+                            iconUrl: app.iconUrl,
+                            formattedPrice: app.formattedPrice || 'Free',
+                            rating: app.averageUserRating?.toFixed(1) || 'N/A',
+                            ratingCount: app.userRatingCount || 0,
+                            primaryGenre: app.primaryGenreName,
+                        };
+                        break;
+
+                    case 'full':
+                        result.app = {
+                            id: app.id,
+                            name: app.name,
+                            artistName: app.artistName,
+                            bundleId: app.bundleId,
+                            url: app.url,
+                            iconUrl: app.iconUrl,
+                            description: app.description,
+                            version: app.version,
+                            price: app.price,
+                            formattedPrice: app.formattedPrice || 'Free',
+                            primaryGenre: app.primaryGenreName,
+                            genres: app.genres,
+                            rating: app.averageUserRating?.toFixed(1) || 'N/A',
+                            ratingCount: app.userRatingCount || 0,
+                            releaseDate: app.releaseDate,
+                            releaseDateFormatted: formatDate(app.releaseDate),
+                            currentVersionReleaseDate: app.currentVersionReleaseDate,
+                            currentVersionReleaseDateFormatted: formatDate(
+                                app.currentVersionReleaseDate
+                            ),
+                            minimumOsVersion: app.minimumOsVersion,
+                            fileSizeBytes: app.fileSizeBytes,
+                            contentAdvisoryRating: app.contentAdvisoryRating,
+                            screenshotCount: app.screenshotUrls?.length || 0,
+                            ipadScreenshotCount: app.ipadScreenshotUrls?.length || 0,
+                        };
+                        break;
+
+                    case 'release':
+                        result.release = {
+                            currentVersion: app.version,
+                            originalReleaseDate: app.releaseDate,
+                            originalReleaseDateFormatted: formatDate(app.releaseDate),
+                            currentVersionReleaseDate: app.currentVersionReleaseDate,
+                            currentVersionReleaseDateFormatted: formatDate(
+                                app.currentVersionReleaseDate
+                            ),
+                        };
+                        break;
+
+                    case 'screenshots':
+                        result.screenshots = {
+                            iphone: {
+                                count: app.screenshotUrls?.length || 0,
+                                urls: app.screenshotUrls || [],
+                            },
+                            ipad: {
+                                count: app.ipadScreenshotUrls?.length || 0,
+                                urls: app.ipadScreenshotUrls || [],
+                            },
+                        };
+                        break;
+
+                    default:
+                        result.app = {
+                            id: app.id,
+                            name: app.name,
+                            artistName: app.artistName,
+                            url: app.url,
+                            iconUrl: app.iconUrl,
+                            formattedPrice: app.formattedPrice || 'Free',
+                            rating: app.averageUserRating?.toFixed(1) || 'N/A',
+                            ratingCount: app.userRatingCount || 0,
+                            primaryGenre: app.primaryGenreName,
+                        };
+                }
+
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(
+                                {
+                                    success: false,
+                                    error: errorMessage,
+                                },
+                                null,
+                                2
+                            ),
+                        },
+                    ],
+                };
+            }
+        }
+    );
+}

package/src/mcp/tools/get-trending-apps.ts

@@ -0,0 +1,108 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { AppStoreService } from '../../services/app-store-service';
+import { APP_STORE_CATEGORIES, Platform, PricingType } from '../../types';
+
+export function registerGetTrendingApps(server: McpServer) {
+    server.registerTool(
+        'get_trending_apps',
+        {
+            description: 'Get top/trending apps from the App Store by category, platform, and pricing type',
+            inputSchema: {
+                platform: z
+                    .string()
+                    .optional()
+                    .describe('Platform to get apps for: iphone, ipad, mac, or tv. Defaults to iphone'),
+                pricingType: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Pricing type: free (top free apps), paid (top paid apps), or grossing (top grossing apps). Defaults to free'
+                    ),
+                country: z
+                    .string()
+                    .optional()
+                    .describe('Country code for the App Store (e.g., US, GB, JP). Defaults to US'),
+                categoryId: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Optional category ID to filter by (e.g., 6014 for Games, 6007 for Productivity)'
+                    ),
+                limit: z
+                    .number()
+                    .optional()
+                    .describe('Maximum number of results to return (1-100). Defaults to 25'),
+            },
+        },
+        async ({ platform, pricingType, country, categoryId, limit }) => {
+            const platformValue = (platform || 'iphone') as Platform;
+            const pricingValue = (pricingType || 'free') as PricingType;
+            const countryCode = country || 'US';
+            const resultLimit = limit || 25;
+
+            try {
+                const apps = await AppStoreService.getTrendingApps(
+                    platformValue,
+                    pricingValue,
+                    countryCode,
+                    categoryId,
+                    resultLimit
+                );
+
+                const categoryInfo = categoryId
+                    ? APP_STORE_CATEGORIES.find((c) => c.id === categoryId)
+                    : null;
+
+                const result = {
+                    success: true,
+                    count: apps.length,
+                    filters: {
+                        platform: platformValue,
+                        pricingType: pricingValue,
+                        country: countryCode,
+                        category: categoryInfo
+                            ? { id: categoryInfo.id, name: categoryInfo.name }
+                            : 'All Categories',
+                    },
+                    apps: apps.map((app, index) => ({
+                        rank: index + 1,
+                        id: app.id,
+                        name: app.name,
+                        artistName: app.artistName,
+                        url: app.url,
+                        iconUrl: app.iconUrl,
+                        price: app.formattedPrice || 'Free',
+                        primaryGenre: app.primaryGenreName,
+                    })),
+                };
+
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(
+                                {
+                                    success: false,
+                                    error: errorMessage,
+                                },
+                                null,
+                                2
+                            ),
+                        },
+                    ],
+                };
+            }
+        }
+    );
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerSearchApps } from './search-apps';
+import { registerGetAppInfo } from './get-app-info';
+import { registerGetTrendingApps } from './get-trending-apps';
+
+export function registerAllTools(server: McpServer) {
+    registerSearchApps(server);
+    registerGetAppInfo(server);
+    registerGetTrendingApps(server);
+}

package/src/mcp/tools/search-apps.ts

@@ -0,0 +1,74 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { AppStoreService } from '../../services/app-store-service';
+
+export function registerSearchApps(server: McpServer) {
+    server.registerTool(
+        'search_apps',
+        {
+            description: 'Search for apps on the App Store by name or keyword',
+            inputSchema: {
+                query: z.string().describe('The search term to find apps'),
+                country: z
+                    .string()
+                    .optional()
+                    .describe('Country code for the App Store (e.g., US, GB, JP). Defaults to US'),
+                limit: z
+                    .number()
+                    .optional()
+                    .describe('Maximum number of results to return (1-200). Defaults to 25'),
+            },
+        },
+        async ({ query, country, limit }) => {
+            const countryCode = country || 'US';
+            const resultLimit = limit || 25;
+            try {
+                const apps = await AppStoreService.searchApps(query, countryCode, resultLimit);
+
+                const result = {
+                    success: true,
+                    count: apps.length,
+                    country: countryCode,
+                    query: query,
+                    apps: apps.map((app) => ({
+                        id: app.id,
+                        name: app.name,
+                        artistName: app.artistName,
+                        url: app.url,
+                        iconUrl: app.iconUrl,
+                        price: app.formattedPrice || 'Free',
+                        rating: app.averageUserRating?.toFixed(1) || 'N/A',
+                        ratingCount: app.userRatingCount || 0,
+                        primaryGenre: app.primaryGenreName,
+                    })),
+                };
+
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            } catch (error) {
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                return {
+                    content: [
+                        {
+                            type: 'text' as const,
+                            text: JSON.stringify(
+                                {
+                                    success: false,
+                                    error: errorMessage,
+                                },
+                                null,
+                                2
+                            ),
+                        },
+                    ],
+                };
+            }
+        }
+    );
+}