Gallica/BnF MCP Server

Instructions

Implementation Reference

• src/tools/items.ts:38-91 (handler)

  Main tool handler function 'createGetItemPagesTool' that defines the MCP tool with name, description, input schema, and handler logic. The handler parses Zod-validated arguments and calls the ItemsClient.getItemPages method with appropriate options (page, pageSize, or range).

  export function createGetItemPagesTool(itemsClient: ItemsClient) {
    return {
      name: 'get_item_pages',
      description: 'Enumerate pages of a document. Returns logical page numbers, IIIF image URLs, and text availability flags.',
      inputSchema: {
        type: 'object',
        properties: {
          ark: {
            type: 'string',
            description: 'ARK identifier',
          },
          page: {
            type: 'number',
            description: 'Get specific page number',
          },
          page_size: {
            type: 'number',
            description: 'Get first N pages',
          },
          page_range: {
            type: 'array',
            items: { type: 'number' },
            minItems: 2,
            maxItems: 2,
            description: 'Get pages in range [start, end]',
          },
        },
        required: ['ark'],
      },
      handler: async (args: unknown) => {
        const parsed = z.object({
          ark: z.string(),
          page: z.number().int().positive().optional(),
          page_size: z.number().int().positive().optional(),
          page_range: z.tuple([z.number().int().positive(), z.number().int().positive()]).optional(),
        }).parse(args);
  
        const options: {
          page?: number;
          pageSize?: number;
          range?: [number, number];
        } = {};
  
        if (parsed.page !== undefined) {
          options.page = parsed.page;
        } else if (parsed.page_size !== undefined) {
          options.pageSize = parsed.page_size;
        } else if (parsed.page_range !== undefined) {
          options.range = parsed.page_range;
        }
  
        return await itemsClient.getItemPages(parsed.ark, options);
      },
    };

• src/gallica/items.ts:107-140 (handler)

  Backend implementation 'getItemPages' method in ItemsClient class. Parses IIIF manifest, filters pages based on options (single page, page range, or first N pages), and returns array of PageInfo objects with page numbers, IIIF URLs, and text availability flags.

  async getItemPages(
    ark: string,
    options?: {
      page?: number;
      pageSize?: number;
      range?: [number, number];
    }
  ): Promise<PageInfo[]> {
    if (!ark) {
      return [];
    }
    try {
      const manifest = await this.iiifClient.parseManifest(ark);
      let pages = manifest.pages;
  
      // Apply filters
      if (options?.range) {
        const [start, end] = options.range;
        pages = pages.filter((p) => p.page >= start && p.page <= end);
      } else if (options?.page !== undefined) {
        // Get single page
        const page = pages.find((p) => p.page === options.page);
        return page ? [page] : [];
      } else if (options?.pageSize !== undefined) {
        // Get first N pages
        pages = pages.slice(0, options.pageSize);
      }
  
      return pages;
    } catch (error) {
      logger.error(`Error getting pages for ${ark}: ${error instanceof Error ? error.message : String(error)}`);
      return [];
    }
  }

• src/gallica/types.ts:145-151 (schema)

  Type definition for PageInfo interface that defines the structure of page objects returned by get_item_pages tool, including page number, label, IIIF image URL, text availability flag, and optional thumbnail URL.

  export interface PageInfo {
    page: number;
    label?: string;
    iiif_image_url: string;
    has_text: boolean;
    thumbnail_url?: string;
  }

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

  Tool instantiation: creates the get_item_pages tool by calling createGetItemPagesTool with the itemsClient instance.

  const getItemPages = createGetItemPagesTool(itemsClient);

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

  Tool registration: adds getItemPages to the tools array that is registered with the MCP server for listing and calling.

  getItemPages,