reunion_search_joconde_collections

Instructions

Implementation Reference

• src/modules/culture.ts:15-86 (registration)

  The registerCultureTools function registers the 'reunion_search_joconde_collections' tool with the MCP server (line 44-86), along with the server.tool() call, schema definitions, and handler logic.

  export function registerCultureTools(server: McpServer): void {
    server.tool(
      'reunion_list_museums',
      'List museums in La Réunion holding the official "Musée de France" designation (granted by the Ministry of Culture under the 2002 law). This designation guarantees scientific standards, public access, and inalienability of collections. Returns Muséofile ID, official name, commune, full address, postal code, phone, URL, designation decree date, lat/lon. Use reunion_get_museum_attendance for visitor statistics, reunion_search_joconde_collections for artwork records.',
      {},
      async () => {
        try {
          const data = await client.getRecords<RecordObject>(DATASET_MUSEUMS, { limit: 50 });
          return jsonResult({
            total_museums: data.total_count,
            museums: data.results.map((row) => ({
              museofile_id: pickString(row, ['identifiant_museofile']),
              name: pickString(row, ['nom_officiel_du_musee']),
              commune: pickString(row, ['commune']),
              address: pickString(row, ['adresse']),
              postal_code: pickString(row, ['code_postal']),
              phone: pickString(row, ['telephone']),
              url: pickString(row, ['url']),
              designation_date: pickString(row, ['date_arrete_attribution_appellation']),
              lat: pickNumber(row, ['latitude']),
              lon: pickNumber(row, ['longitude']),
            })),
          });
        } catch (error) {
          return errorResult(error instanceof Error ? error.message : 'Failed to list museums');
        }
      }
    );
  
    server.tool(
      'reunion_search_joconde_collections',
      'Search the Joconde national database extract restricted to La Réunion museum collections. Joconde is the official catalog of artworks and objects held by French museums. Returns reference, title, author, domain (painting, sculpture, photography, ethnography, etc.), denomination, materials/techniques, period and millesime of creation, inventory number, museum, Muséofile code, description, location within museum, city. Useful for cultural research, art history, exhibition curation.',
      {
        query: z.string().optional().describe('Free-text search across title, author, description, denomination'),
        museum: z.string().optional().describe('Museum name prefix match (e.g. "Musée Léon Dierx", "Stella Matutina")'),
        domain: z.string().optional().describe('Domain prefix match. Examples: "peinture", "sculpture", "photographie", "ethnographie", "estampe", "dessin"'),
        limit: z.number().int().min(1).max(100).default(25).describe('Max items to return (1-100, default 25)'),
      },
      async ({ query, museum, domain, limit }) => {
        try {
          const data = await client.getRecords<RecordObject>(DATASET_JOCONDE, {
            where: buildWhere([
              query ? `search(${quote(query)})` : undefined,
              museum ? `nom_officiel_musee LIKE ${quote(`${museum}%`)}` : undefined,
              domain ? `domaine LIKE ${quote(`${domain}%`)}` : undefined,
            ]),
            limit,
          });
          return jsonResult({
            total_items: data.total_count,
            items: data.results.map((row) => ({
              reference: pickString(row, ['reference']),
              title: pickString(row, ['titre']),
              author: pickString(row, ['auteur']),
              domain: pickString(row, ['domaine']),
              denomination: pickString(row, ['denomination']),
              materials: pickString(row, ['materiaux_techniques']),
              period: pickString(row, ['periode_de_creation']),
              millesime: pickString(row, ['millesime_de_creation']),
              inventory_number: pickString(row, ['numero_inventaire']),
              museum: pickString(row, ['nom_officiel_musee']),
              museofile_code: pickString(row, ['code_museofile']),
              description: pickString(row, ['description']),
              location: pickString(row, ['localisation']),
              city: pickString(row, ['ville']),
            })),
          });
        } catch (error) {
          return errorResult(error instanceof Error ? error.message : 'Failed to search Joconde');
        }
      }
    );

• src/modules/culture.ts:53-86 (handler)

  The actual handler function for 'reunion_search_joconde_collections' – an async function that accepts query, museum, domain, and limit parameters, queries the 'base-joconde-extraitculture' dataset via the ReunionClient, and returns structured results with fields like reference, title, author, domain, etc.

    async ({ query, museum, domain, limit }) => {
      try {
        const data = await client.getRecords<RecordObject>(DATASET_JOCONDE, {
          where: buildWhere([
            query ? `search(${quote(query)})` : undefined,
            museum ? `nom_officiel_musee LIKE ${quote(`${museum}%`)}` : undefined,
            domain ? `domaine LIKE ${quote(`${domain}%`)}` : undefined,
          ]),
          limit,
        });
        return jsonResult({
          total_items: data.total_count,
          items: data.results.map((row) => ({
            reference: pickString(row, ['reference']),
            title: pickString(row, ['titre']),
            author: pickString(row, ['auteur']),
            domain: pickString(row, ['domaine']),
            denomination: pickString(row, ['denomination']),
            materials: pickString(row, ['materiaux_techniques']),
            period: pickString(row, ['periode_de_creation']),
            millesime: pickString(row, ['millesime_de_creation']),
            inventory_number: pickString(row, ['numero_inventaire']),
            museum: pickString(row, ['nom_officiel_musee']),
            museofile_code: pickString(row, ['code_museofile']),
            description: pickString(row, ['description']),
            location: pickString(row, ['localisation']),
            city: pickString(row, ['ville']),
          })),
        });
      } catch (error) {
        return errorResult(error instanceof Error ? error.message : 'Failed to search Joconde');
      }
    }
  );

• src/modules/culture.ts:47-52 (schema)

  Zod schema definitions for input validation: query (optional string), museum (optional string), domain (optional string), limit (integer 1-100, default 25).

  {
    query: z.string().optional().describe('Free-text search across title, author, description, denomination'),
    museum: z.string().optional().describe('Museum name prefix match (e.g. "Musée Léon Dierx", "Stella Matutina")'),
    domain: z.string().optional().describe('Domain prefix match. Examples: "peinture", "sculpture", "photographie", "ethnographie", "estampe", "dessin"'),
    limit: z.number().int().min(1).max(100).default(25).describe('Max items to return (1-100, default 25)'),
  },

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

  Import of registerCultureTools from culture.ts.

  import { registerCultureTools } from './culture.js';

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

  Invocation of registerCultureTools(server) within registerAllTools.

  registerCultureTools(server);

• src/modules/culture.ts:10-10 (helper)

  Dataset constant DATASET_JOCONDE = 'base-joconde-extraitculture' used by the handler.

  const DATASET_JOCONDE = 'base-joconde-extraitculture';

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

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

• src/utils/helpers.ts:53-55 (helper)

  The quote helper used to safely quote string literals for ODSQL queries.

  export function quote(value: string): string {
    return `'${escapeOdSqlString(value)}'`;
  }