reunion_get_commune_population

Instructions

Implementation Reference

• src/modules/territory.ts:66-103 (handler)

  The tool 'reunion_get_commune_population' is registered as an MCP tool on lines 66-103. The handler (async function on line 74) queries the 'population-francaise-communespublic' dataset with optional filters for commune name and census year, then returns structured population data including INSEE code, commune name, census year, use year, municipal/counted-apart/total populations, area, and EPCI information.

  server.tool(
    'reunion_get_commune_population',
    'INSEE official millésimé population counts for La Réunion communes. INSEE provides three population figures: municipal (people legally living in the commune), counted apart (e.g. students living elsewhere but counted at parents\' home), and total (sum). Each row is one commune × one census year. Returns INSEE code, commune name, census year (the year the data was collected), use year (the year the figures officially apply), municipal/counted-apart/total populations, surface area, EPCI. Sorted by census year descending then total population descending.',
    {
      commune: z.string().optional().describe('Commune name prefix match (e.g. "Saint-Denis")'),
      year: z.number().int().optional().describe('Census reference year (4 digits, INSEE publishes a "millésime" each year)'),
      limit: z.number().int().min(1).max(500).default(100).describe('Max rows to return (1-500, default 100)'),
    },
    async ({ commune, year, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_POPULATION, {
          where: buildWhere([
            commune ? `nom_de_la_commune LIKE ${quote(`${commune}%`)}` : undefined,
            year !== undefined ? `annee_recensement = ${year}` : undefined,
          ]),
          order_by: 'annee_recensement DESC, population_totale DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          populations: data.results.map((row) => ({
            insee_code: pickString(row, ['code_insee']),
            commune: pickString(row, ['nom_de_la_commune']),
            census_year: pickNumber(row, ['annee_recensement']),
            use_year: pickNumber(row, ['annee_utilisation']),
            municipal_population: pickNumber(row, ['population_municipale']),
            counted_apart: pickNumber(row, ['population_comptee_a_part']),
            total_population: pickNumber(row, ['population_totale']),
            area: pickNumber(row, ['superficie']),
            epci: pickString(row, ['libepci']),
            epci_code: pickString(row, ['code_epci']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to fetch population');
      }
    }
  );

• src/modules/territory.ts:69-73 (schema)

  Input schema for 'reunion_get_commune_population' defines three optional parameters: 'commune' (string, name prefix match), 'year' (integer, census reference year), and 'limit' (integer, 1-500, default 100).

  {
    commune: z.string().optional().describe('Commune name prefix match (e.g. "Saint-Denis")'),
    year: z.number().int().optional().describe('Census reference year (4 digits, INSEE publishes a "millésime" each year)'),
    limit: z.number().int().min(1).max(500).default(100).describe('Max rows to return (1-500, default 100)'),
  },

• src/modules/territory.ts:66-103 (registration)

  The tool is registered via server.tool('reunion_get_commune_population', ...) inside registerTerritoryTools(), which is called from registerAllTools() in src/modules/index.ts (line 51).

  server.tool(
    'reunion_get_commune_population',
    'INSEE official millésimé population counts for La Réunion communes. INSEE provides three population figures: municipal (people legally living in the commune), counted apart (e.g. students living elsewhere but counted at parents\' home), and total (sum). Each row is one commune × one census year. Returns INSEE code, commune name, census year (the year the data was collected), use year (the year the figures officially apply), municipal/counted-apart/total populations, surface area, EPCI. Sorted by census year descending then total population descending.',
    {
      commune: z.string().optional().describe('Commune name prefix match (e.g. "Saint-Denis")'),
      year: z.number().int().optional().describe('Census reference year (4 digits, INSEE publishes a "millésime" each year)'),
      limit: z.number().int().min(1).max(500).default(100).describe('Max rows to return (1-500, default 100)'),
    },
    async ({ commune, year, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_POPULATION, {
          where: buildWhere([
            commune ? `nom_de_la_commune LIKE ${quote(`${commune}%`)}` : undefined,
            year !== undefined ? `annee_recensement = ${year}` : undefined,
          ]),
          order_by: 'annee_recensement DESC, population_totale DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          populations: data.results.map((row) => ({
            insee_code: pickString(row, ['code_insee']),
            commune: pickString(row, ['nom_de_la_commune']),
            census_year: pickNumber(row, ['annee_recensement']),
            use_year: pickNumber(row, ['annee_utilisation']),
            municipal_population: pickNumber(row, ['population_municipale']),
            counted_apart: pickNumber(row, ['population_comptee_a_part']),
            total_population: pickNumber(row, ['population_totale']),
            area: pickNumber(row, ['superficie']),
            epci: pickString(row, ['libepci']),
            epci_code: pickString(row, ['code_epci']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to fetch population');
      }
    }
  );

• src/utils/helpers.ts:36-41 (helper)

  The buildWhere helper function is used to construct the ODSQL WHERE clause from optional filter conditions. It joins non-empty conditions with ' AND '.

  export function buildWhere(
    conditions: Array<string | undefined | null | false>
  ): string | undefined {
    const valid = conditions.filter((condition): condition is string => Boolean(condition));
    return valid.length > 0 ? valid.join(' AND ') : undefined;
  }