reunion_get_lycee_ips

Instructions

Implementation Reference

• src/modules/index.ts:33-39 (registration)

  registerAllTools function calls registerEducationTools, which registers reunion_get_lycee_ips among other education tools

  export function registerAllTools(server: McpServer): void {
    registerAdministrationTools(server);
    registerCatalogTools(server);
    registerCommuneTools(server);
    registerCultureTools(server);
    registerEconomyTools(server);
    registerEducationTools(server);

• src/modules/education.ts:181-220 (handler)

  Main implementation: server.tool('reunion_get_lycee_ips', ...) with Zod schema and async handler that queries the OpenDataSoft dataset 'indices-de-position-sociale-dans-les-lycees-a-la-reunion' and returns IPS data for lycées

  server.tool(
    'reunion_get_lycee_ips',
    'DEPP Indice de Position Sociale (IPS) for high schools (lycées) in La Réunion, by school year and pathway. Unlike colleges, lycées have separate IPS for the general/technological track (voie GT) and the vocational track (voie pro), plus a combined IPS. Returns school year, UAI, name, commune, sector, lycée type, three IPS values + standard deviations for GT and pro. Higher IPS = more privileged students.',
    {
      school: z.string().optional().describe('School name prefix match'),
      school_year: z.string().optional().describe('School year (rentrée), format YYYY-YYYY (e.g. "2022-2023")'),
      commune: z.string().optional().describe('Commune name prefix match'),
      limit: z.number().int().min(1).max(200).default(50).describe('Max rows to return (1-200, default 50)'),
    },
    async ({ school, school_year, commune, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_IPS_LYCEES, {
          where: buildWhere([
            school ? `nom_de_l_etablissment LIKE ${quote(`${school}%`)}` : undefined,
            school_year ? `rentree_scolaire = ${quote(school_year)}` : undefined,
            commune ? `nom_de_la_commune LIKE ${quote(`${commune}%`)}` : undefined,
          ]),
          limit,
        });
        return jsonResult({
          total_rows: data.total_count,
          schools: data.results.map((row) => ({
            school_year: pickString(row, ['rentree_scolaire']),
            uai: pickString(row, ['uai']),
            name: pickString(row, ['nom_de_l_etablissment']),
            commune: pickString(row, ['nom_de_la_commune']),
            sector: pickString(row, ['secteur']),
            lycee_type: pickString(row, ['type_de_lycee']),
            ips_general_technological: pickNumber(row, ['ips_voie_gt']),
            ips_vocational: pickNumber(row, ['ips_voie_pro']),
            ips_combined: pickNumber(row, ['ips_ensemble_gt_pro']),
            stddev_gt: pickNumber(row, ['ecart_type_de_l_ips_voie_gt']),
            stddev_pro: pickNumber(row, ['ecart_type_de_l_ips_voie_pro']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to fetch lycée IPS');
      }
    }
  );

• src/modules/education.ts:184-189 (schema)

  Input schema using Zod: school (optional), school_year (optional), commune (optional), limit (default 50, max 200)

  {
    school: z.string().optional().describe('School name prefix match'),
    school_year: z.string().optional().describe('School year (rentrée), format YYYY-YYYY (e.g. "2022-2023")'),
    commune: z.string().optional().describe('Commune name prefix match'),
    limit: z.number().int().min(1).max(200).default(50).describe('Max rows to return (1-200, default 50)'),
  },

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

  buildWhere helper used to construct ODSQL WHERE clause from optional conditions

  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;
  }

• src/utils/helpers.ts:125-138 (helper)

  pickNumber helper used to extract numeric IPS values from API response records

  export function pickNumber(
    record: RecordObject,
    candidates: string[]
  ): number | undefined {
    const value = pickValue(record, candidates);
    if (typeof value === 'number' && Number.isFinite(value)) {
      return value;
    }
    if (typeof value === 'string' && value.trim() !== '') {
      const parsed = Number(value);
      return Number.isFinite(parsed) ? parsed : undefined;
    }
    return undefined;
  }