suggest
Generate search suggestions and autocomplete results for app store queries to refine searches before retrieving detailed data.
Instructions
Get search suggestions/autocomplete for a search term
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term to get suggestions for | |
| country | No | Two-letter country code (default: us) | us |
Implementation Reference
- src/server.js:477-515 (handler)The main handler function for the 'suggest' tool. It validates input parameters (term required, country optional), constructs the App Store suggest API URL using buildSuggestUrl, fetches JSON data, parses suggestions with parseSuggest, and returns a formatted text content response with the suggestions list and count, or an error response.
/** * Suggest tool - Get search suggestions */ async function handleSuggest(args) { try { const { term, country = 'us' } = args; if (!term) { throw new Error('term is required'); } const url = buildSuggestUrl({ term, country }); const data = await fetchJSON(url); const suggestions = parseSuggest(data); return { content: [ { type: 'text', text: JSON.stringify({ term, suggestions, count: suggestions.length, }, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: JSON.stringify({ error: error.message }, null, 2), }, ], isError: true, }; } } - src/server.js:1463-1464 (registration)The dispatch case in the CallToolRequestSchema handler that routes calls to the 'suggest' tool to the handleSuggest function.
case 'suggest': return await handleSuggest(args); - src/server.js:1161-1179 (schema)The tool specification in the ListTools response, defining the name, description, and input schema (JSON Schema) for the 'suggest' tool.
{ name: 'suggest', description: 'Get search suggestions/autocomplete for a search term', inputSchema: { type: 'object', properties: { term: { type: 'string', description: 'Search term to get suggestions for', }, country: { type: 'string', description: 'Two-letter country code (default: us)', default: 'us', }, }, required: ['term'], }, }, - src/parsers/appStore/suggest.js:1-21 (helper)The parseSuggest helper function exported from the parser module, used by the handler to extract, normalize, and sort suggestion terms by priority from the raw App Store API response.
/** * Parser for search suggestions/autocomplete */ /** * Normalizes suggestion data from iTunes Search Hints API * @param {Object} data - Raw suggestion API response * @returns {Array<Object>} */ export function parseSuggest(data) { if (!data || !data.hints || !Array.isArray(data.hints)) { return []; } return data.hints.map(hint => ({ term: hint.term || null, priority: hint.priority || 0, })).sort((a, b) => (b.priority || 0) - (a.priority || 0)); } - src/endpoints/appStore.js:180-184 (helper)The buildSuggestUrl helper function that constructs the App Store search suggestions API URL based on term and country parameters.
export function buildSuggestUrl(params) { const { term, country = 'us' } = params; // App Store uses a different endpoint for suggestions return `https://search.itunes.apple.com/WebObjects/MZSearchHints.woa/wa/hints?term=${encodeURIComponent(term)}&country=${country}`;