reunion_query_dataset

Instructions

Implementation Reference

• src/modules/catalog.ts:84-107 (handler)

  MCP tool handler for 'reunion_query_dataset' - fetches records from any data.regionreunion.com dataset with a raw ODSQL where clause via the ReunionClient.getRecords() method. Returns total_count + results as JSON.

  server.tool(
    'reunion_query_dataset',
    'Generic escape hatch: fetch records from ANY data.regionreunion.com dataset with a raw ODSQL where clause. Call reunion_inspect_dataset first to know the fields. ODSQL supports operators like =, !=, >, <, LIKE, AND, OR, and the search() function.',
    {
      dataset_id: z.string().describe('Dataset identifier'),
      where: z.string().optional().describe('ODSQL where clause, e.g. "commune = \'Saint-Denis\' AND annee > 2020"'),
      select: z.string().optional().describe('Comma-separated list of fields to return (defaults to all)'),
      order_by: z.string().optional().describe('ODSQL order_by clause, e.g. "date DESC"'),
      limit: z.number().int().min(1).max(100).default(20),
    },
    async ({ dataset_id, where, select, order_by, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(dataset_id, {
          where,
          select,
          order_by,
          limit,
        });
        return jsonResult({ total_count: data.total_count, results: data.results });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to query dataset');
      }
    }
  );

• src/modules/catalog.ts:87-93 (schema)

  Zod schema for 'reunion_query_dataset' inputs: dataset_id (required string), where (optional ODSQL string), select (optional field list), order_by (optional ODSQL order), limit (1-100, default 20).

  {
    dataset_id: z.string().describe('Dataset identifier'),
    where: z.string().optional().describe('ODSQL where clause, e.g. "commune = \'Saint-Denis\' AND annee > 2020"'),
    select: z.string().optional().describe('Comma-separated list of fields to return (defaults to all)'),
    order_by: z.string().optional().describe('ODSQL order_by clause, e.g. "date DESC"'),
    limit: z.number().int().min(1).max(100).default(20),
  },

• src/modules/catalog.ts:84-107 (registration)

  Registered via server.tool('reunion_query_dataset', ...) inside registerCatalogTools() at line 9-108 of src/modules/catalog.ts. registerCatalogTools is called from src/modules/index.ts line 35.

  server.tool(
    'reunion_query_dataset',
    'Generic escape hatch: fetch records from ANY data.regionreunion.com dataset with a raw ODSQL where clause. Call reunion_inspect_dataset first to know the fields. ODSQL supports operators like =, !=, >, <, LIKE, AND, OR, and the search() function.',
    {
      dataset_id: z.string().describe('Dataset identifier'),
      where: z.string().optional().describe('ODSQL where clause, e.g. "commune = \'Saint-Denis\' AND annee > 2020"'),
      select: z.string().optional().describe('Comma-separated list of fields to return (defaults to all)'),
      order_by: z.string().optional().describe('ODSQL order_by clause, e.g. "date DESC"'),
      limit: z.number().int().min(1).max(100).default(20),
    },
    async ({ dataset_id, where, select, order_by, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(dataset_id, {
          where,
          select,
          order_by,
          limit,
        });
        return jsonResult({ total_count: data.total_count, results: data.results });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to query dataset');
      }
    }
  );

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

  ReunionClient.getRecords() - the HTTP method invoked by the handler to fetch dataset records from the OpenDataSoft API (data.regionreunion.com). Handles caching for referential datasets.

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

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

  buildWhere() helper used by the handler to construct ODSQL WHERE clauses; jsonResult/errorResult helpers for formatting tool responses.

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