find_cities_near_city

Instructions

Implementation Reference

• src/server.ts:216-227 (handler)

  The async handler function that executes the 'find_cities_near_city' tool logic: resolves a city by UUID, gets its coordinates, and queries nearby cities ordered by distance (closest) or population (largest).

  async ({ id, mode, preferredLanguages }) => {
    const city = await client.cities.get(id);
    if (city.latitude == null || city.longitude == null) {
      return { content: [{ type: 'text', text: `City "${city.name}" has no coordinates on record.` }] };
    }
    const params = { lat: city.latitude, lon: city.longitude, preferredLanguages };
    const nearby = mode === 'largest'
      ? await client.cities.byCoordinatesLargest(params)
      : await client.cities.byCoordinatesClosest(params);
    const result = { reference: { id: city.id, name: city.name }, nearby };
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  },

• src/server.ts:208-215 (schema)

  Zod schema definitions for the tool's input parameters: id (string UUID), mode (enum 'closest'|'largest', default 'closest'), and optional preferredLanguages.

  {
    id: z.string().describe('UUID of the reference city'),
    mode: z
      .enum(['closest', 'largest'])
      .default('closest')
      .describe('"closest" orders by distance, "largest" orders by population'),
    preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
  },

• src/server.ts:205-228 (registration)

  Registration of the 'find_cities_near_city' tool using server.tool() with its name, description, input schema, and handler.

  server.tool(
    'find_cities_near_city',
    'Find cities near a given city. Resolves the city\'s coordinates and returns nearby cities ordered by distance or population.',
    {
      id: z.string().describe('UUID of the reference city'),
      mode: z
        .enum(['closest', 'largest'])
        .default('closest')
        .describe('"closest" orders by distance, "largest" orders by population'),
      preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
    },
    async ({ id, mode, preferredLanguages }) => {
      const city = await client.cities.get(id);
      if (city.latitude == null || city.longitude == null) {
        return { content: [{ type: 'text', text: `City "${city.name}" has no coordinates on record.` }] };
      }
      const params = { lat: city.latitude, lon: city.longitude, preferredLanguages };
      const nearby = mode === 'largest'
        ? await client.cities.byCoordinatesLargest(params)
        : await client.cities.byCoordinatesClosest(params);
      const result = { reference: { id: city.id, name: city.name }, nearby };
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    },
  );