TomTom MCP Server

Implementation Reference

• src/handlers/searchHandler.ts:87-102 (handler)

  MCP tool handler factory for 'tomtom-poi-search'. Handles input parameters, calls the POI search service, logs activity, formats response as JSON text, and manages errors.
  export function createPoiSearchHandler() { return async (params: any) => { logger.info(`🏪 POI search: "${params.query}"`); try { const result = await poiSearch(params.query, params); logger.info(`✅ POI search completed`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ POI search failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
• src/schemas/search/searchSchema.ts:57-106 (schema)

  Zod schema defining input parameters for the tomtom-poi-search tool, including query, location bias, filters, radius, and POI-specific options.
  export const tomtomPOISearchSchema = { query: z .string() .describe( "Name of the POI to search for. If the intended query is a POI category like 'restaurant', provide an empty string for this param and use the category filter parameter to apply the desired category filter." ), ...baseSearchParams, ...locationBiasParams, ...boundingBoxParams, ...poiFilterParams, radius: z .number() .optional() .describe( "Search radius in meters. Essential for focused local results. Examples: 1000 (walking), 5000 (driving), 20000 (wide area)." ), lat: z .number() .optional() .describe("Latitude for location context. STRONGLY recommended for relevant local results."), lon: z .number() .optional() .describe("Longitude for location context. Must be used with lat parameter."), typeahead: z .boolean() .optional() .describe("Autocomplete mode for partial queries. Use for search interfaces."), entityTypeSet: z.string().optional() .describe(`Filter results by geographic entity types. Valid values: PostalCodeArea, CountryTertiarySubdivision, CountrySecondarySubdivision, MunicipalitySubdivision, MunicipalitySecondarySubdivision, Country, CountrySubdivision, Neighbourhood, Municipality. Note: This parameter is for geographic entities only, not POIs. For POI filtering, use categorySet instead` ), chargingAvailability: z .boolean() .optional() .describe("Include charging availability information for EV stations"), parkingAvailability: z.boolean().optional().describe("Include parking availability information"), fuelAvailability: z .boolean() .optional() .describe("Include fuel availability information for gas stations"), minFuzzyLevel: z.number().optional().describe("Minimum fuzzy matching level (1-4)"), maxFuzzyLevel: z.number().optional().describe("Maximum fuzzy matching level (1-4)"), ofs: z.number().optional().describe("Offset for pagination of results"), relatedPois: z.string().optional().describe("Include related points of interest"), ext: z.string().optional().describe("Extended parameters for the search"), };
• src/tools/searchTools.ts:66-74 (registration)

  Registers the 'tomtom-poi-search' tool on the MCP server with title, description, input schema, and handler factory.
  server.registerTool( "tomtom-poi-search", { title: "TomTom POI Search", description: "Find specific business categories", inputSchema: schemas.tomtomPOISearchSchema, }, createPoiSearchHandler() );
• src/services/search/searchService.ts:223-237 (helper)

  Core POI search function that constructs API parameters and calls the TomTom POI Search API endpoint.
  export async function poiSearch( query: string, options?: ExtendedSearchOptions ): Promise<SearchResult> { const params = buildSearchParams(options, { limit: 10, language: "en-US", }); return makeApiCall( `/search/${API_VERSION.SEARCH}/poiSearch/${encodeURIComponent(query)}.json`, params, `POI searching for: "${query}"` ); }