reunion_search_baby_names

Instructions

Implementation Reference

• src/modules/administration.ts:257-291 (registration)

  Registration of the 'reunion_search_baby_names' tool via server.tool() — also includes the schema and handler inline.

  server.tool(
    'reunion_search_baby_names',
    'Search first names given to babies born in La Réunion (department 974) by year, since 2000. Each row gives: usual first name (uppercase), year of birth, department, sex code, and number of children given that name that year. Sorted by count descending. Source: INSEE Fichier des prénoms via data.regionreunion.com. Useful for naming trend analysis, demographic studies.',
    {
      name: z.string().optional().describe('First name prefix match (case-insensitive — auto-uppercased). Example: "marie" matches "MARIE", "MARIE-CLAIRE", "MARIETTE"'),
      year: z.number().int().optional().describe('Birth year filter (4 digits, 2000-present), e.g. 2020'),
      sex: z.enum(['1', '2']).optional().describe('Sex code: "1" for boys, "2" for girls'),
      limit: z.number().int().min(1).max(500).default(100).describe('Max rows to return (1-500, default 100)'),
    },
    async ({ name, year, sex, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_NAMES, {
          where: buildWhere([
            name ? `preusuel LIKE ${quote(`${name.toUpperCase()}%`)}` : undefined,
            year !== undefined ? `annais = ${quote(String(year))}` : undefined,
            sex ? `sexe = ${quote(sex)}` : undefined,
          ]),
          order_by: 'nombre DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          names: data.results.map((row) => ({
            sex: pickString(row, ['sexe']),
            first_name: pickString(row, ['preusuel']),
            year: pickString(row, ['annais']),
            department: pickString(row, ['dpt']),
            count: pickNumber(row, ['nombre']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to search baby names');
      }
    }
  );

• src/modules/administration.ts:260-265 (schema)

  Zod schema defining input parameters: optional name (prefix string), year (int), sex (enum '1'/'2'), and limit (int 1-500, default 100).

  {
    name: z.string().optional().describe('First name prefix match (case-insensitive — auto-uppercased). Example: "marie" matches "MARIE", "MARIE-CLAIRE", "MARIETTE"'),
    year: z.number().int().optional().describe('Birth year filter (4 digits, 2000-present), e.g. 2020'),
    sex: z.enum(['1', '2']).optional().describe('Sex code: "1" for boys, "2" for girls'),
    limit: z.number().int().min(1).max(500).default(100).describe('Max rows to return (1-500, default 100)'),
  },

• src/modules/administration.ts:266-291 (handler)

  Handler function that queries the 'prenomsdpt974depuis2000' dataset on data.regionreunion.com, filters by name prefix, year, sex, sorts by count descending, and returns mapped results with sex, first_name, year, department, and count.

    async ({ name, year, sex, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_NAMES, {
          where: buildWhere([
            name ? `preusuel LIKE ${quote(`${name.toUpperCase()}%`)}` : undefined,
            year !== undefined ? `annais = ${quote(String(year))}` : undefined,
            sex ? `sexe = ${quote(sex)}` : undefined,
          ]),
          order_by: 'nombre DESC',
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          names: data.results.map((row) => ({
            sex: pickString(row, ['sexe']),
            first_name: pickString(row, ['preusuel']),
            year: pickString(row, ['annais']),
            department: pickString(row, ['dpt']),
            count: pickNumber(row, ['nombre']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to search baby names');
      }
    }
  );

• src/modules/administration.ts:19-19 (helper)

  Dataset ID constant 'prenomsdpt974depuis2000' used by the tool to query the OpenDataSoft API.

  const DATASET_NAMES = 'prenomsdpt974depuis2000';

• src/modules/administration.ts:33-47 (registration)

  registerAdministrationTools is called from registerAllTools to wire up all administration tools including reunion_search_baby_names.

      voters: pickNumber(row, ['votants']),
      blank: pickNumber(row, ['blancs']),
      null_votes: pickNumber(row, ['nuls']),
      expressed: pickNumber(row, ['exprimes']),
      panel_num: pickNumber(row, ['ndegpanneau']),
      candidate_last_name: pickString(row, ['nom']),
      candidate_first_name: pickString(row, ['prenom']),
      candidate_sex: pickString(row, ['sexe']),
      political_label: pickString(row, ['nuance']),
      votes: pickNumber(row, ['voix']),
      votes_pct_expressed: pickNumber(row, ['voix_exp']),
    };
  }
  
  export function registerAdministrationTools(server: McpServer): void {