country_overview

Instructions

Implementation Reference

• src/server.ts:248-279 (registration)

  Registration of the 'country_overview' tool via server.tool() with name, description, schema, and handler.

  server.tool(
    'country_overview',
    'Get a country\'s details, all its regions, and its most populous cities in one call. Accepts either a country UUID or a name prefix.',
    {
      id: z.string().optional().describe('Country UUID (takes priority over name)'),
      name: z.string().optional().describe('Country name prefix to resolve (e.g. "Germany")'),
      preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
      citiesLimit: z.number().int().min(1).max(50).default(10).describe('Number of top cities to include (default 10)'),
    },
    async ({ id, name, preferredLanguages, citiesLimit }) => {
      let countryId = id;
      if (!countryId) {
        if (!name) {
          return { content: [{ type: 'text', text: 'Provide either id or name.' }] };
        }
        const matches = await client.countries.list({ name, limit: 1, preferredLanguages });
        if (!matches.length) {
          return { content: [{ type: 'text', text: `No country found matching "${name}".` }] };
        }
        countryId = matches[0].id;
      }
      const country = await client.countries.get(countryId);
      const topCities = await client.cities.search({
        countryCode: country.isoCode,
        sort: 'population_desc',
        limit: citiesLimit,
        preferredLanguages,
      });
      const result = { country, regions: country.regions, topCities };
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    },
  );

• src/server.ts:251-256 (schema)

  Input schema for country_overview: id (optional UUID), name (optional prefix), preferredLanguages (optional), citiesLimit (default 10, max 50).

  {
    id: z.string().optional().describe('Country UUID (takes priority over name)'),
    name: z.string().optional().describe('Country name prefix to resolve (e.g. "Germany")'),
    preferredLanguages: z.string().optional().describe('Comma-separated BCP 47 language tags'),
    citiesLimit: z.number().int().min(1).max(50).default(10).describe('Number of top cities to include (default 10)'),
  },

• src/server.ts:257-278 (handler)

  Handler function for country_overview: resolves country by id or name, fetches country details, regions, and top cities by population, returns JSON result.

  async ({ id, name, preferredLanguages, citiesLimit }) => {
    let countryId = id;
    if (!countryId) {
      if (!name) {
        return { content: [{ type: 'text', text: 'Provide either id or name.' }] };
      }
      const matches = await client.countries.list({ name, limit: 1, preferredLanguages });
      if (!matches.length) {
        return { content: [{ type: 'text', text: `No country found matching "${name}".` }] };
      }
      countryId = matches[0].id;
    }
    const country = await client.countries.get(countryId);
    const topCities = await client.cities.search({
      countryCode: country.isoCode,
      sort: 'population_desc',
      limit: citiesLimit,
      preferredLanguages,
    });
    const result = { country, regions: country.regions, topCities };
    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
  },