reunion_list_znieff

Instructions

Implementation Reference

• src/modules/environment.ts:140-165 (handler)

  The tool handler for 'reunion_list_znieff'. It accepts an optional 'query' string for free-text search and an optional 'limit' (1-100, default 50). Calls client.getRecords on the ZNIEFF dataset, builds an ODSQL where clause from the query using search(), and maps results to mnhn_id, org_id, name, and generation fields.

  server.tool(
    'reunion_list_znieff',
    'List Zones Naturelles d\'Intérêt Écologique, Faunistique et Floristique (ZNIEFF) in La Réunion — official inventory of areas of high ecological value, used for biodiversity protection and as a reference in land-use decisions. Réunion has type-1 (small precise zones with rare species) and type-2 (large functional ecosystems). Returns MNHN ID, organization ID, zone name, generation. Source: MNHN / DEAL via data.regionreunion.com.',
    {
      query: z.string().optional().describe('Free-text search on zone name (e.g. "Piton", "Mafate", "Volcan")'),
      limit: z.number().int().min(1).max(100).default(50).describe('Max zones to return (1-100, default 50)'),
    },
    async ({ query, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_ZNIEFF, {
          where: buildWhere([query ? `search(${quote(query)})` : undefined]),
          limit,
        });
        return jsonResult({
          total_zones: data.total_count,
          zones: data.results.map((row) => ({
            mnhn_id: pickString(row, ['id_mnhn']),
            org_id: pickString(row, ['id_org']),
            name: pickString(row, ['nom']),
            generation: pickString(row, ['generation']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to list ZNIEFF zones');
      }
    }

• src/modules/environment.ts:143-146 (schema)

  Zod schema for the tool's input parameters: 'query' (optional string) for free-text search on zone name, and 'limit' (optional integer, 1-100, default 50) to control result count.

  {
    query: z.string().optional().describe('Free-text search on zone name (e.g. "Piton", "Mafate", "Volcan")'),
    limit: z.number().int().min(1).max(100).default(50).describe('Max zones to return (1-100, default 50)'),
  },

• src/modules/environment.ts:17-17 (registration)

  The function registerEnvironmentTools is exported and called from src/modules/index.ts (line 41) to register all environment tools including 'reunion_list_znieff' on the MCP server.

  export function registerEnvironmentTools(server: McpServer): void {

• src/modules/environment.ts:12-12 (helper)

  Constant DATASET_ZNIEFF defining the OpenDataSoft dataset ID used by the handler: 'zones-naturelles-d-interet-ecologique-faunistique-et-floristique-a-la-reunion'.

  const DATASET_ZNIEFF = 'zones-naturelles-d-interet-ecologique-faunistique-et-floristique-a-la-reunion';

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

  The getRecords method on ReunionClient, used by the handler to fetch records from the OpenDataSoft API. Handles caching for referential datasets, builds the URL, and calls fetchJson with retries.

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