get_item_details

Instructions

Implementation Reference

• src/tools/items.ts:14-33 (handler)

  Main tool definition with handler function that creates the get_item_details tool. Includes name, description, input schema validation, and handler that parses the ARK parameter and calls itemsClient.getItemMetadata().

  export function createGetItemDetailsTool(itemsClient: ItemsClient) {
    return {
      name: 'get_item_details',
      description: 'Get full metadata for a Gallica item by its ARK identifier. Returns bibliographic data, available formats, and helpful URLs.',
      inputSchema: {
        type: 'object',
        properties: {
          ark: {
            type: 'string',
            description: 'ARK identifier (e.g., "ark:/12148/bpt6k123456" or "bpt6k123456")',
          },
        },
        required: ['ark'],
      },
      handler: async (args: unknown) => {
        const parsed = z.object({ ark: z.string() }).parse(args);
        return await itemsClient.getItemMetadata(parsed.ark);
      },
    };
  }

• src/gallica/items.ts:26-68 (helper)

  ItemsClient.getItemMetadata method that implements the core logic for fetching item metadata. It extracts the ARK identifier, fetches the IIIF manifest, extracts metadata fields (title, creator, date, publisher, etc.), and determines available formats.

  async getItemMetadata(ark: string): Promise<ItemMetadata> {
    // Extract ARK identifier
    const arkId = ark.replace(/^ark:\/12148\//, '').replace(/^\/ark:\/12148\//, '');
    const fullArk = `ark:/12148/${arkId}`;
    const gallicaUrl = `${this.baseUrl}/ark:/12148/${arkId}`;
  
    try {
      // Try to get metadata from IIIF manifest first
      if (!ark) {
        throw new Error('ARK is required');
      }
      const manifest = await this.iiifClient.parseManifest(ark);
      
      // Extract metadata from manifest if available
      const metadata = manifest.metadata as Record<string, unknown> || {};
      
      // Build metadata object
      const itemMetadata: ItemMetadata = {
        ark: fullArk,
        gallica_url: gallicaUrl,
        manifest_url: this.iiifClient.getManifestUrl(ark),
        available_formats: ['iiif', 'image'],
        ...this.extractMetadataFromManifest(metadata),
      };
  
      // Check if text is available
      if (manifest.pages.length > 0 && manifest.pages[0]?.has_text) {
        itemMetadata.available_formats.push('text', 'alto');
      }
  
      return itemMetadata;
    } catch (error) {
      logger.warn(`Could not fetch full metadata for ${ark}, returning basic info: ${error instanceof Error ? error.message : String(error)}`);
      
      // Return basic metadata
      return {
        ark: fullArk,
        gallica_url: gallicaUrl,
        manifest_url: this.iiifClient.getManifestUrl(ark),
        available_formats: ['iiif', 'image'],
      };
    }
  }

• src/mcpServer.ts:28-29 (registration)

  Import statement for createGetItemDetailsTool function from the items tools module.

  import {
    createGetItemDetailsTool,

• src/mcpServer.ts:85-85 (registration)

  Tool instantiation where getItemDetails is created by calling createGetItemDetailsTool(itemsClient).

  const getItemDetails = createGetItemDetailsTool(itemsClient);

• src/mcpServer.ts:94-107 (registration)

  Tools array registration where getItemDetails is added to the list of available tools that will be exposed via MCP protocol.

  const tools = [
    searchByTitle,
    searchByAuthor,
    searchBySubject,
    searchByDate,
    searchByDocumentType,
    advancedSearch,
    naturalLanguageSearch,
    getItemDetails,
    getItemPages,
    getPageImage,
    getPageText,
    sequentialReporting,
  ];