search
Find mobile apps across App Store and Google Play Store by entering search terms, filtering by country and language, and specifying 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:127-163 (handler)Main handler function for the 'search' tool. Builds the iTunes search URL, fetches JSON data, parses it using parseSearch, and returns formatted results or error.
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)Schema definition for the 'search' tool, including input parameters, defaults, and required fields, registered in ListToolsRequestSchema.
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:1448-1448 (registration)Tool dispatch registration in CallToolRequestSchema handler's switch statement, mapping 'search' tool name to handleSearch function.
return await handleSearch(args); - src/endpoints/appStore.js:14-35 (helper)Helper function to construct the iTunes Search API URL with pagination and limits, used by the search handler.
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:12-20 (helper)Helper function to parse raw iTunes search API response into structured results, reusing parseApps, used by the search handler.
export function parseSearch(data) { const apps = parseApps(data); return { results: apps, count: apps.length, total: data.resultCount || apps.length, }; }