reunion_search_health_professionals

Instructions

Implementation Reference

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

  The tool is registered via registerAllTools() which calls registerHealthTools(server) at line 44, registering all health tools including 'reunion_search_health_professionals'.

  export function registerAllTools(server: McpServer): void {
    registerAdministrationTools(server);
    registerCatalogTools(server);
    registerCommuneTools(server);
    registerCultureTools(server);
    registerEconomyTools(server);
    registerEducationTools(server);
    registerEmploymentTools(server);
    registerEnvironmentTools(server);
    registerFacilityTools(server);
    registerGeographyTools(server);
    registerHealthTools(server);
    registerHospitalityTools(server);
    registerHousingTools(server);
    registerNationalElectionsTools(server);
    registerPossessionTools(server);
    registerSocialTools(server);
    registerTelecomTools(server);
    registerTerritoryTools(server);
    registerTourismTools(server);
    registerTransportTools(server);
    registerUrbanismTools(server);
    registerWeatherTools(server);
  }

• src/modules/health.ts:16-58 (handler)

  The main implementation: registerHealthTools registers the 'reunion_search_health_professionals' tool with schema (profession, commune, postal_code, limit) and handler that queries the CNAM Annuaire Santé dataset via data.regionreunion.com API.

  export function registerHealthTools(server: McpServer): void {
    server.tool(
      'reunion_search_health_professionals',
      'Search the CNAM Annuaire Santé directory of registered health professionals practicing in La Réunion. Returns name, profession, full address, postal code, phone, mode of practice, convention status (secteur 1/2), and SESAM-Vitale acceptance. Source: CNAM via data.regionreunion.com. Use this to find doctors, nurses, dentists, pharmacists, midwives, etc. by profession or location. For posted fees per act in La Possession specifically, use reunion_search_possession_health_pros.',
      {
        profession: z.string().optional().describe('Profession label, prefix match. Examples: "Médecin", "Médecin généraliste", "Chirurgien-dentiste", "Infirmier", "Masseur-Kinésithérapeute", "Sage-femme", "Pharmacien"'),
        commune: z.string().optional().describe('Commune name to match against the address (substring search). Example: "Saint-Denis", "Saint-Pierre"'),
        postal_code: z.string().optional().describe('Réunion postal code (exact match), e.g. "97400" for Saint-Denis, "97410" for Saint-Pierre'),
        limit: z.number().int().min(1).max(200).default(50).describe('Max results to return (1-200, default 50)'),
      },
      async ({ profession, commune, postal_code, limit }) => {
        try {
          const data = await client.getRecords<RecordObject>(DATASET_HEALTH_PROS, {
            where: buildWhere([
              `reg_name = ${quote('La Réunion')}`,
              profession ? `libelle_profession LIKE ${quote(`${profession}%`)}` : undefined,
              commune ? `search(${quote(commune)})` : undefined,
              postal_code ? `code_postal = ${quote(postal_code)}` : undefined,
            ]),
            limit,
          });
          return jsonResult({
            total_professionals: data.total_count,
            professionals: data.results.map((row) => ({
              name: pickString(row, ['nom']),
              title: pickString(row, ['civilite']),
              profession: pickString(row, ['libelle_profession']),
              address: [pickString(row, ['adresse3']), pickString(row, ['adresse4'])]
                .filter(Boolean)
                .join(' '),
              postal_code: pickString(row, ['code_postal']),
              phone: pickString(row, ['telephone']),
              practice: pickString(row, ['exercice_particulier']),
              nature: pickString(row, ['nature_exercice']),
              convention: pickString(row, ['convention']),
              sesam_vitale: pickString(row, ['sesam_vitale']),
            })),
          });
        } catch (error) {
          return errorResult(error instanceof Error ? error.message : 'Failed to search health professionals');
        }
      }
    );

• src/modules/health.ts:20-25 (schema)

  Zod schema definitions for the tool's input parameters: profession (optional string), commune (optional string), postal_code (optional string), limit (number, 1-200, default 50).

  {
    profession: z.string().optional().describe('Profession label, prefix match. Examples: "Médecin", "Médecin généraliste", "Chirurgien-dentiste", "Infirmier", "Masseur-Kinésithérapeute", "Sage-femme", "Pharmacien"'),
    commune: z.string().optional().describe('Commune name to match against the address (substring search). Example: "Saint-Denis", "Saint-Pierre"'),
    postal_code: z.string().optional().describe('Réunion postal code (exact match), e.g. "97400" for Saint-Denis, "97410" for Saint-Pierre'),
    limit: z.number().int().min(1).max(200).default(50).describe('Max results to return (1-200, default 50)'),
  },

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

  ReunionClient class used by the handler to fetch records from the OpenDataSoft API (data.regionreunion.com). The handler calls client.getRecords(DATASET_HEALTH_PROS, ...) at line 28.

  export class ReunionClient {
    private readonly baseUrl = 'https://data.regionreunion.com/api/explore/v2.1/';
    private readonly timeout = 30000;
    private readonly maxRetries = 2;
    private readonly metadataCache = new Map<string, Promise<DatasetMetadata | undefined>>();
    private readonly recordsCache = new Map<string, { value: unknown; expiresAt: number }>();
  
    /**
     * Fetch records from a dataset
     */
    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();

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

  The buildWhere helper used by the handler to construct the ODSQL WHERE clause from optional filter 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;
  }