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}"`
    );
  }