Gallica/BnF MCP Server

Instructions

Implementation Reference

• src/tools/items.ts:97-145 (handler)

  Main tool implementation: createGetPageImageTool function that defines the get_page_image tool with its name, description, input schema, and async handler that validates inputs and calls iiifClient.getImageUrl to return IIIF image URLs

  export function createGetPageImageTool(iiifClient: IIIFClient) {
    return {
      name: 'get_page_image',
      description: 'Get IIIF image URL for a specific page. Returns URL and metadata, not binary data.',
      inputSchema: {
        type: 'object',
        properties: {
          ark: {
            type: 'string',
            description: 'ARK identifier',
          },
          page: {
            type: 'number',
            description: 'Page number',
          },
          size: {
            type: 'string',
            description: 'Image size (e.g., "full", "200,", "500,500", "pct:50")',
          },
          region: {
            type: 'string',
            description: 'Image region (e.g., "full", "x,y,w,h")',
          },
        },
        required: ['ark', 'page'],
      },
      handler: async (args: unknown) => {
        const parsed = z.object({
          ark: z.string(),
          page: z.number().int().positive(),
          size: z.string().optional(),
          region: z.string().optional(),
        }).parse(args);
  
        const options: { size?: string; region?: string } = {};
        if (parsed.size) options.size = parsed.size;
        if (parsed.region) options.region = parsed.region;
        
        const url = iiifClient.getImageUrl(parsed.ark, parsed.page, options);
  
        return {
          ark: parsed.ark,
          page: parsed.page,
          iiif_url: url,
          thumbnail_url: iiifClient.getImageUrl(parsed.ark, parsed.page, { size: '200,' }),
        };
      },
    };
  }

• src/tools/items.ts:101-122 (schema)

  Input schema definition: Validates 'ark' (required string), 'page' (required number), 'size' (optional string for image size), and 'region' (optional string for image region)

  inputSchema: {
    type: 'object',
    properties: {
      ark: {
        type: 'string',
        description: 'ARK identifier',
      },
      page: {
        type: 'number',
        description: 'Page number',
      },
      size: {
        type: 'string',
        description: 'Image size (e.g., "full", "200,", "500,500", "pct:50")',
      },
      region: {
        type: 'string',
        description: 'Image region (e.g., "full", "x,y,w,h")',
      },
    },
    required: ['ark', 'page'],
  },

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

  Tool instantiation: Creates getPageImage tool instance using createGetPageImageTool with iiifClient dependency

  const getPageImage = createGetPageImageTool(iiifClient);

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

  Tool registration: Adds getPageImage to the tools array for MCP server registration

  getPageImage,

• src/gallica/iiif.ts:34-45 (helper)

  Helper method: IIIFClient.getImageUrl that constructs IIIF image URLs using ark, page, and options (region, size, rotation, quality, format)

  getImageUrl(ark: string, page: number, options: IIIFImageOptions = {}): string {
    // Extract ARK identifier
    const arkId = ark.replace(/^ark:\/12148\//, '').replace(/^\/ark:\/12148\//, '');
    
    const region = options.region || 'full';
    const size = options.size || 'full';
    const rotation = options.rotation !== undefined ? options.rotation : 0;
    const quality = options.quality || 'native';
    const format = options.format || 'jpg';
  
    return `${this.baseUrl}/iiif/ark:/12148/${arkId}/f${page}/${region}/${size}/${rotation}/${quality}.${format}`;
  }