reunion_get_jobseekers_by_age_sex

Instructions

Implementation Reference

• src/modules/employment.ts:12-51 (handler)

  Registration and handler for the 'reunion_get_jobseekers_by_age_sex' tool. The function registerEmploymentTools calls server.tool() with the tool name, description, Zod schema for inputs (from, to, limit), and an async handler that queries the OpenDataSoft API for jobseeker data broken down by age and sex, then maps results to structured JSON.

  export function registerEmploymentTools(server: McpServer): void {
    server.tool(
      'reunion_get_jobseekers_by_age_sex',
      'Monthly counts of Pôle emploi (now France Travail) jobseekers in La Réunion, broken down by sex and age group. Each row is one month. Returns total, total men, total women, then 6 sub-categories (men/women × <25 / 25-49 / ≥50). Sorted by month descending. Useful for labor-market monitoring, demographic analysis of unemployment, gender-gap studies.',
      {
        from: z.string().optional().describe('Inclusive lower bound on month, ISO format YYYY-MM-DD (use first of month, e.g. "2022-01-01")'),
        to: z.string().optional().describe('Inclusive upper bound on month, ISO format YYYY-MM-DD'),
        limit: z.number().int().min(1).max(500).default(24).describe('Max months to return (1-500, default 24 = 2 years)'),
      },
      async ({ from, to, limit }) => {
        try {
          const data = await client.getRecords<RecordObject>(DATASET_BY_AGE_SEX, {
            where: buildWhere([
              from ? `mois >= date${quote(from)}` : undefined,
              to ? `mois <= date${quote(to)}` : undefined,
            ]),
            order_by: 'mois DESC',
            limit,
          });
  
          return jsonResult({
            total_months: data.total_count,
            series: data.results.map((row) => ({
              month: pickString(row, ['mois']),
              total: pickNumber(row, ['total']),
              men_total: pickNumber(row, ['total_hommes']),
              women_total: pickNumber(row, ['total_femmes']),
              men_under_25: pickNumber(row, ['hommes_moins_de_25_ans']),
              men_25_49: pickNumber(row, ['hommes_de_25_a_49_ans']),
              men_50_plus: pickNumber(row, ['hommes_50_ans_ou_plus']),
              women_under_25: pickNumber(row, ['femmes_moins_de_25_ans']),
              women_25_49: pickNumber(row, ['femmes_de_25_a_49_ans']),
              women_50_plus: pickNumber(row, ['femmes_50_ans_ou_plus']),
            })),
          });
        } catch (error) {
          return errorResult(error instanceof Error ? error.message : 'Failed to fetch jobseeker stats');
        }
      }
    );

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

  Registration call: registerEmploymentTools(server) is invoked in registerAllTools(), which cascades from the main entry point (src/index.ts).

  registerEmploymentTools(server);

• src/modules/employment.ts:16-20 (schema)

  Input schema for the tool: 'from' (optional ISO date string), 'to' (optional ISO date string), and 'limit' (integer 1-500, default 24). Validated with Zod.

  {
    from: z.string().optional().describe('Inclusive lower bound on month, ISO format YYYY-MM-DD (use first of month, e.g. "2022-01-01")'),
    to: z.string().optional().describe('Inclusive upper bound on month, ISO format YYYY-MM-DD'),
    limit: z.number().int().min(1).max(500).default(24).describe('Max months to return (1-500, default 24 = 2 years)'),
  },

• src/modules/employment.ts:9-41 (helper)

  Dataset constant DATASET_BY_AGE_SEX = 'demandeurs-d-emploi-inscrits-a-pole-emploi-par-age-et-sexe-a-la-reunion' identifying the OpenDataSoft dataset used by the handler.

  const DATASET_BY_AGE_SEX = 'demandeurs-d-emploi-inscrits-a-pole-emploi-par-age-et-sexe-a-la-reunion';
  const DATASET_BY_COMMUNE = 'demandeurs-d-emploi-inscrits-a-pole-emploi-par-commune-a-la-reunion';
  
  export function registerEmploymentTools(server: McpServer): void {
    server.tool(
      'reunion_get_jobseekers_by_age_sex',
      'Monthly counts of Pôle emploi (now France Travail) jobseekers in La Réunion, broken down by sex and age group. Each row is one month. Returns total, total men, total women, then 6 sub-categories (men/women × <25 / 25-49 / ≥50). Sorted by month descending. Useful for labor-market monitoring, demographic analysis of unemployment, gender-gap studies.',
      {
        from: z.string().optional().describe('Inclusive lower bound on month, ISO format YYYY-MM-DD (use first of month, e.g. "2022-01-01")'),
        to: z.string().optional().describe('Inclusive upper bound on month, ISO format YYYY-MM-DD'),
        limit: z.number().int().min(1).max(500).default(24).describe('Max months to return (1-500, default 24 = 2 years)'),
      },
      async ({ from, to, limit }) => {
        try {
          const data = await client.getRecords<RecordObject>(DATASET_BY_AGE_SEX, {
            where: buildWhere([
              from ? `mois >= date${quote(from)}` : undefined,
              to ? `mois <= date${quote(to)}` : undefined,
            ]),
            order_by: 'mois DESC',
            limit,
          });
  
          return jsonResult({
            total_months: data.total_count,
            series: data.results.map((row) => ({
              month: pickString(row, ['mois']),
              total: pickNumber(row, ['total']),
              men_total: pickNumber(row, ['total_hommes']),
              women_total: pickNumber(row, ['total_femmes']),
              men_under_25: pickNumber(row, ['hommes_moins_de_25_ans']),
              men_25_49: pickNumber(row, ['hommes_de_25_a_49_ans']),
              men_50_plus: pickNumber(row, ['hommes_50_ans_ou_plus']),

• src/client.ts:43-261 (helper)

  The ReunionClient.getRecords() method used by the handler to fetch data from the OpenDataSoft API.

    async getRecords<T extends RecordObject = RecordObject>(
      datasetId: string,
      params: ODSQueryParams = {}
    ): Promise<ODSResponse<T>> {
      const url = this.buildUrl(`/catalog/datasets/${datasetId}/records`, params);
  
      if (REFERENTIAL_DATASETS.has(datasetId)) {
        const now = Date.now();
        const cached = this.recordsCache.get(url);
        if (cached && cached.expiresAt > now) {
          return cached.value as ODSResponse<T>;
        }
        const value = await this.fetchJson<ODSResponse<T>>(url);
        this.recordsCache.set(url, { value, expiresAt: now + REFERENTIAL_TTL_MS });
        return value;
      }
  
      return this.fetchJson<ODSResponse<T>>(url);
    }
  
    /**
     * Clear the in-memory caches. Intended for tests.
     */
    clearCaches(): void {
      this.metadataCache.clear();
      this.recordsCache.clear();
    }
  
    /**
     * Fetch aggregated data from a dataset
     */
    async getAggregates<T extends RecordObject = RecordObject>(
      datasetId: string,
      select: string,
      options: {
        where?: string;
        groupBy?: string;
        orderBy?: string;
        limit?: number;
      } = {}
    ): Promise<ODSResponse<T>> {
      const params: Record<string, string | number | undefined> = { select };
      if (options.where) params.where = options.where;
      if (options.groupBy) params.group_by = options.groupBy;
      if (options.orderBy) params.order_by = options.orderBy;
      if (options.limit !== undefined) params.limit = options.limit;
  
      const url = this.buildUrl(`/catalog/datasets/${datasetId}/aggregates`, params);
      return this.fetchJson<ODSResponse<T>>(url);
    }
  
    /**
     * Search across all datasets
     */
    async searchDatasets(query: string): Promise<CatalogResponse> {
      const url = this.buildUrl('/catalog/datasets', {
        where: `search(${quote(query)})`,
        limit: 20,
      });
      return this.fetchJson<CatalogResponse>(url);
    }
  
    /**
     * List datasets with an optional raw ODSQL where clause.
     */
    async listDatasets(
      options: { where?: string; limit?: number; offset?: number } = {}
    ): Promise<CatalogResponse> {
      const url = this.buildUrl('/catalog/datasets', {
        where: options.where,
        limit: options.limit ?? 20,
        offset: options.offset,
      });
      return this.fetchJson<CatalogResponse>(url);
    }
  
    /**
     * Fetch dataset metadata from the catalog
     */
    async getDatasetMetadata(datasetId: string): Promise<DatasetMetadata | undefined> {
      if (!this.metadataCache.has(datasetId)) {
        const promise = this.fetchJson<CatalogResponse>(
          this.buildUrl('/catalog/datasets', {
            where: `dataset_id = ${quote(datasetId)}`,
            limit: 1,
          })
        ).then((data) => data.results[0]);
  
        this.metadataCache.set(datasetId, promise);
      }
  
      return this.metadataCache.get(datasetId);
    }
  
    /**
     * Check whether a dataset currently exists in the public catalog
     */
    async datasetExists(datasetId: string): Promise<boolean> {
      return Boolean(await this.getDatasetMetadata(datasetId));
    }
  
    /**
     * Resolve the first matching field name for a dataset
     */
    async resolveField(
      datasetId: string,
      candidates: string[]
    ): Promise<string | undefined> {
      const metadata = await this.getDatasetMetadata(datasetId);
      const fields = metadata?.fields ?? [];
  
      if (fields.length === 0) {
        return candidates[0];
      }
  
      const byNormalizedName = new Map(
        fields.map((field) => [normalizeText(field.name), field.name] as const)
      );
  
      for (const candidate of candidates) {
        const direct = byNormalizedName.get(normalizeText(candidate));
        if (direct) {
          return direct;
        }
      }
  
      const fieldNames = fields.map((field) => field.name);
      for (const candidate of candidates) {
        const normalizedCandidate = normalizeText(candidate);
        const partial = fieldNames.find((fieldName) =>
          normalizeText(fieldName).includes(normalizedCandidate)
        );
        if (partial) {
          return partial;
        }
      }
  
      return candidates[0];
    }
  
    /**
     * Build URL with query parameters
     */
    private buildUrl(
      path: string,
      params: Record<string, string | number | undefined>
    ): string {
      const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
      const url = new URL(normalizedPath, this.baseUrl);
  
      for (const [key, value] of Object.entries(params)) {
        if (value !== undefined && value !== null && value !== '') {
          url.searchParams.set(key, String(value));
        }
      }
  
      return url.toString();
    }
  
    /**
     * Execute HTTP request with retries and timeout handling
     */
    private async fetchJson<T>(url: string, remainingRetries = this.maxRetries): Promise<T> {
      const controller = new AbortController();
      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
  
      try {
        const response = await fetch(url, {
          method: 'GET',
          headers: {
            Accept: 'application/json',
            'User-Agent': 'mcp-reunion/1.0',
          },
          signal: controller.signal,
        });
  
        if (!response.ok) {
          const errorText = await response.text();
          if (response.status >= 500 && remainingRetries > 0) {
            await this.delay(250);
            return this.fetchJson<T>(url, remainingRetries - 1);
          }
          throw new Error(
            `API error ${response.status}: ${response.statusText}. ${errorText}`
          );
        }
  
        return (await response.json()) as T;
      } catch (error) {
        if (error instanceof Error) {
          if (error.name === 'AbortError') {
            throw new Error(`Request timeout after ${this.timeout}ms`);
          }
  
          if (remainingRetries > 0 && this.isRetryableError(error)) {
            await this.delay(250);
            return this.fetchJson<T>(url, remainingRetries - 1);
          }
  
          throw error;
        }
        throw new Error('Unknown error occurred');
      } finally {
        clearTimeout(timeoutId);
      }
    }
  
    private isRetryableError(error: Error): boolean {
      return /fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/i.test(error.message);
    }
  
    private async delay(ms: number): Promise<void> {
      await new Promise((resolve) => setTimeout(resolve, ms));
    }
  }
  
  // Singleton instance
  export const client = new ReunionClient();