search_cities_in_country

Instructions

Implementation Reference

• src/server.ts:300-326 (registration)

  Registration of the 'search_cities_in_country' tool via server.tool() call, defining its name, description, input schema, and handler.

  server.tool(
    'search_cities_in_country',
    'Search cities using a country name instead of an ISO code. Resolves the country first, then searches cities within it.',
    {
      countryName: z.string().describe('Country name prefix (e.g. "France", "United States")'),
      name: z.string().optional().describe('City name prefix to filter by'),
      minPopulation: z.number().int().optional().describe('Minimum population'),
      maxPopulation: z.number().int().optional().describe('Maximum population'),
      sort: z
        .enum(['population_desc', 'population_asc', 'name_asc', 'name_desc'])
        .optional()
        .describe('Sort order'),
      preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
      limit: z.number().int().min(1).max(100).optional().describe('Max results (default 20)'),
      offset: z.number().int().min(0).optional().describe('Pagination offset'),
    },
    async ({ countryName, ...cityParams }) => {
      const matches = await client.countries.list({ name: countryName, limit: 1 });
      if (!matches.length) {
        return { content: [{ type: 'text', text: `No country found matching "${countryName}".` }] };
      }
      const country = matches[0];
      const cities = await client.cities.search({ ...cityParams, countryCode: country.isoCode });
      const result = { country: { id: country.id, name: country.name, isoCode: country.isoCode }, cities };
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    },
  );

• src/server.ts:303-315 (schema)

  Input schema for the tool using Zod: countryName (required), name, minPopulation, maxPopulation, sort, preferredLanguages, limit, offset.

  {
    countryName: z.string().describe('Country name prefix (e.g. "France", "United States")'),
    name: z.string().optional().describe('City name prefix to filter by'),
    minPopulation: z.number().int().optional().describe('Minimum population'),
    maxPopulation: z.number().int().optional().describe('Maximum population'),
    sort: z
      .enum(['population_desc', 'population_asc', 'name_asc', 'name_desc'])
      .optional()
      .describe('Sort order'),
    preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
    limit: z.number().int().min(1).max(100).optional().describe('Max results (default 20)'),
    offset: z.number().int().min(0).optional().describe('Pagination offset'),
  },

• src/server.ts:316-325 (handler)

  Handler function that resolves the country by name using client.countries.list(), then searches cities within that country using client.cities.search() with the resolved countryCode.

  async ({ countryName, ...cityParams }) => {
    const matches = await client.countries.list({ name: countryName, limit: 1 });
    if (!matches.length) {
      return { content: [{ type: 'text', text: `No country found matching "${countryName}".` }] };
    }
    const country = matches[0];
    const cities = await client.cities.search({ ...cityParams, countryCode: country.isoCode });
    const result = { country: { id: country.id, name: country.name, isoCode: country.isoCode }, cities };
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  },