search
Find mobile apps in the App Store by entering search terms, filtering by country and language, and controlling result quantity.
Instructions
Search for apps in the App Store
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term | |
| country | No | Two-letter country code (default: us) | us |
| lang | No | Language code (default: en) | en |
| num | No | Number of results (default: 50, max: 200) | |
| page | No | Page number (default: 1) |
Implementation Reference
- src/server.js:124-164 (handler)The core handler function for the 'search' MCP tool. It validates input parameters, constructs the App Store search URL using buildSearchUrl, fetches and parses the JSON response using parseSearch, and returns the results as MCP content or an error./** * Search tool - Search for apps */ async function handleSearch(args) { try { const { term, country = 'us', lang = 'en', num = 50, page = 1, } = args; if (!term) { throw new Error('term is required'); } const url = buildSearchUrl({ term, country, lang, num, page }); const data = await fetchJSON(url); const result = parseSearch(data); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.message }, null, 2), }, ], isError: true, }; } }
- src/server.js:964-996 (schema)The input schema and metadata for the 'search' tool, defined in the ListToolsRequestSchema handler. Specifies parameters like term (required), country, lang, num, and page with types, descriptions, and defaults.name: 'search', description: 'Search for apps in the App Store', inputSchema: { type: 'object', properties: { term: { type: 'string', description: 'Search term', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, lang: { type: 'string', description: 'Language code (default: en)', default: 'en', }, num: { type: 'number', description: 'Number of results (default: 50, max: 200)', default: 50, }, page: { type: 'number', description: 'Page number (default: 1)', default: 1, }, }, required: ['term'], }, },
- src/server.js:1440-1489 (registration)Registration of the 'search' tool in the CallToolRequestSchema handler via switch-case mapping to handleSearch function.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; switch (name) { // App Store tools case 'app': return await handleApp(args); case 'search': return await handleSearch(args); case 'list': return await handleList(args); case 'reviews': return await handleReviews(args); case 'ratings': return await handleRatings(args); case 'developer': return await handleDeveloper(args); case 'similar': return await handleSimilar(args); case 'privacy': return await handlePrivacy(args); case 'versionHistory': return await handleVersionHistory(args); case 'suggest': return await handleSuggest(args); // Google Play tools case 'gp_app': return await handleGPApp(args); case 'gp_search': return await handleGPSearch(args); case 'gp_list': return await handleGPList(args); case 'gp_reviews': return await handleGPReviews(args); case 'gp_developer': return await handleGPDeveloper(args); case 'gp_similar': return await handleGPSimilar(args); case 'gp_permissions': return await handleGPPermissions(args); case 'gp_datasafety': return await handleGPDataSafety(args); case 'gp_categories': return await handleGPCategories(args); case 'gp_suggest': return await handleGPSuggest(args); default: throw new Error(`Unknown tool: ${name}`); } });
- src/endpoints/appStore.js:10-35 (helper)Helper function buildSearchUrl constructs the iTunes Search API URL with pagination (offset/limit), country, language, and entity filters. Used by the search handler.* Builds a search URL * @param {Object} params - Search parameters * @returns {string} */ export function buildSearchUrl(params) { const { term, country = 'us', lang = 'en', num = 50, page = 1, entity = 'software', } = params; const offset = (page - 1) * num; const queryParams = new URLSearchParams({ term: term, country: country, lang: lang, limit: Math.min(num, 200).toString(), offset: offset.toString(), entity: entity, }); return `${ITUNES_BASE}/search?${queryParams.toString()}`; }
- src/parsers/appStore/search.js:7-20 (helper)Helper function parseSearch processes the raw JSON response from iTunes Search API, extracts apps using parseApps, and formats with count and total./** * Parses search results from iTunes Search API * @param {Object} data - Raw iTunes API response * @returns {Object} */ export function parseSearch(data) { const apps = parseApps(data); return { results: apps, count: apps.length, total: data.resultCount || apps.length, }; }