Gallica/BnF MCP Server

Instructions

Implementation Reference

• src/tools/gallicaSearch.ts:24-62 (handler)

  Main MCP tool factory function that creates the search_by_title tool with its name, description, input schema (lines 28-52), and handler logic (lines 53-61) which validates inputs using zod and calls the SearchAPI.searchByTitle method.

  export function createSearchByTitleTool(searchApi: SearchAPI) {
    return {
      name: 'search_by_title',
      description: 'Search for documents in the Gallica digital library by title.',
      inputSchema: {
        type: 'object',
        properties: {
          title: {
            type: 'string',
            description: 'The title to search for',
          },
          exact_match: {
            type: 'boolean',
            description: 'If true, search for the exact title; otherwise, search for title containing the words',
            default: false,
          },
          max_results: {
            type: 'number',
            description: 'Maximum number of results to return (1-50)',
            default: config.defaultMaxRecords,
          },
          start_record: {
            type: 'number',
            description: 'Starting record for pagination',
            default: config.defaultStartRecord,
          },
        },
        required: ['title'],
      },
      handler: async (args: unknown) => {
        const parsed = exactMatchSchema.extend({ title: z.string() }).parse(args);
        return await searchApi.searchByTitle(
          parsed.title,
          parsed.exact_match ?? false,
          parsed.max_results ?? config.defaultMaxRecords,
          parsed.start_record ?? config.defaultStartRecord
        );
      },
    };

• src/gallica/search.ts:177-185 (handler)

  The actual search implementation in SearchAPI class that constructs the CQL query (exact match uses quotes, otherwise searches for words in title) and delegates to the core search method.

  searchByTitle(
    title: string,
    exactMatch: boolean = false,
    maxResults: number = config.defaultMaxRecords,
    startRecord: number = config.defaultStartRecord
  ): Promise<SearchResult> {
    const query = exactMatch ? `dc.title all "${title}"` : `dc.title all ${title}`;
    return this.search(query, startRecord, maxResults);
  }

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

  Tool instantiation: createSearchByTitleTool is called with searchApi to create the searchByTitle tool object.

  const searchByTitle = createSearchByTitleTool(searchApi);

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

  Tool registration: searchByTitle is added to the tools array which is used in the ListToolsRequestSchema handler to expose available tools to MCP clients.

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

• src/tools/gallicaSearch.ts:12-19 (schema)

  Zod schema definitions used for input validation: searchParamsSchema defines common parameters (max_results, start_record) and exactMatchSchema extends it with exact_match boolean option.

  const searchParamsSchema = z.object({
    max_results: z.number().int().positive().max(50).optional(),
    start_record: z.number().int().positive().optional(),
  });
  
  const exactMatchSchema = searchParamsSchema.extend({
    exact_match: z.boolean().optional(),
  });