reunion_inspect_dataset

Instructions

Implementation Reference

• src/modules/catalog.ts:53-82 (handler)

  The reunion_inspect_dataset tool handler. Takes a dataset_id, fetches metadata from the OpenDataSoft API via client.getDatasetMetadata(), and returns the dataset's schema (fields with name/type/label), title, description, records_count, and has_records flag.

  server.tool(
    'reunion_inspect_dataset',
    'Inspect one dataset: return its schema (fields + types), title, description, record count, and features. Use this before calling reunion_query_dataset so you know which fields you can filter on.',
    {
      dataset_id: z.string().describe('Dataset identifier as returned by reunion_search_catalog'),
    },
    async ({ dataset_id }) => {
      try {
        const meta = await client.getDatasetMetadata(dataset_id);
        if (!meta) {
          return jsonResult({ found: false, dataset_id });
        }
        const metas = meta.metas?.default ?? {};
        return jsonResult({
          found: true,
          dataset_id: meta.dataset_id,
          title: metas.title,
          description:
            typeof metas.description === 'string'
              ? metas.description.replace(/<[^>]+>/g, '').slice(0, 1000)
              : undefined,
          records_count: metas.records_count,
          has_records: meta.has_records,
          fields: meta.fields.map((f) => ({ name: f.name, type: f.type, label: f.label })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to inspect dataset');
      }
    }
  );

• src/modules/catalog.ts:56-58 (schema)

  Input schema for reunion_inspect_dataset: requires a dataset_id string describing the dataset identifier as returned by reunion_search_catalog.

  {
    dataset_id: z.string().describe('Dataset identifier as returned by reunion_search_catalog'),
  },

• src/modules/catalog.ts:53-82 (registration)

  The tool is registered via server.tool('reunion_inspect_dataset', ...) inside registerCatalogTools(), which is called from registerAllTools() in src/modules/index.ts, which is called from main() in src/index.ts.

  server.tool(
    'reunion_inspect_dataset',
    'Inspect one dataset: return its schema (fields + types), title, description, record count, and features. Use this before calling reunion_query_dataset so you know which fields you can filter on.',
    {
      dataset_id: z.string().describe('Dataset identifier as returned by reunion_search_catalog'),
    },
    async ({ dataset_id }) => {
      try {
        const meta = await client.getDatasetMetadata(dataset_id);
        if (!meta) {
          return jsonResult({ found: false, dataset_id });
        }
        const metas = meta.metas?.default ?? {};
        return jsonResult({
          found: true,
          dataset_id: meta.dataset_id,
          title: metas.title,
          description:
            typeof metas.description === 'string'
              ? metas.description.replace(/<[^>]+>/g, '').slice(0, 1000)
              : undefined,
          records_count: metas.records_count,
          has_records: meta.has_records,
          fields: meta.fields.map((f) => ({ name: f.name, type: f.type, label: f.label })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to inspect dataset');
      }
    }
  );

• src/client.ts:122-135 (helper)

  The getDatasetMetadata() method used by the handler to fetch dataset metadata from data.regionreunion.com API, with caching.

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

• src/utils/helpers.ts:8-17 (helper)

  The jsonResult() and errorResult() helper functions used to format the tool's response.

  export function jsonResult(data: unknown): ToolResult {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2),
        },
      ],
    };
  }