natural_language_search

Instructions

Implementation Reference

• src/tools/gallicaSearch.ts:270-302 (handler)

  Main tool handler - createNaturalLanguageSearchTool function defines the 'natural_language_search' MCP tool with its name, description, inputSchema, and async handler that calls searchApi.naturalLanguageSearch().

  export function createNaturalLanguageSearchTool(searchApi: SearchAPI) {
    return {
      name: 'natural_language_search',
      description: 'Search the Gallica digital library using natural language. This is a simplified search that uses the "gallica all" operator to search across all fields.',
      inputSchema: {
        type: 'object',
        properties: {
          query: {
            type: 'string',
            description: 'Natural language search query',
          },
          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: ['query'],
      },
      handler: async (args: unknown) => {
        const parsed = searchParamsSchema.extend({ query: z.string() }).parse(args);
        return await searchApi.naturalLanguageSearch(
          parsed.query,
          parsed.max_results ?? config.defaultMaxRecords,
          parsed.start_record ?? config.defaultStartRecord
        );
      },
    };

• src/gallica/search.ts:252-259 (handler)

  Core search logic - naturalLanguageSearch method formats the query as 'gallica all "{query}"' and delegates to the base search method.

  naturalLanguageSearch(
    query: string,
    maxResults: number = config.defaultMaxRecords,
    startRecord: number = config.defaultStartRecord
  ): Promise<SearchResult> {
    const formattedQuery = `gallica all "${query}"`;
    return this.search(formattedQuery, startRecord, maxResults);
  }

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

  Zod schema definition for search parameters (max_results and start_record) used for input validation in the handler.

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

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

  Tool registration - creates the naturalLanguageSearch tool instance and adds it to the tools array that is registered with the MCP server.

  const naturalLanguageSearch = createNaturalLanguageSearchTool(searchApi);
  
  // Register extended item tools (4 new tools)
  const getItemDetails = createGetItemDetailsTool(itemsClient);
  const getItemPages = createGetItemPagesTool(itemsClient);
  const getPageImage = createGetPageImageTool(iiifClient);
  const getPageText = createGetPageTextTool(textClient);
  
  // Register sequential reporting tool
  const sequentialReporting = createSequentialReportingTool(reportingServer);
  
  // Register all tools with error handling
  const tools = [
    searchByTitle,
    searchByAuthor,
    searchBySubject,
    searchByDate,
    searchByDocumentType,
    advancedSearch,
    naturalLanguageSearch,
    getItemDetails,
    getItemPages,
    getPageImage,
    getPageText,
    sequentialReporting,
  ];

• src/mcpServer.ts:127-150 (registration)

  CallTool handler registration - handles incoming tool call requests, finds the tool by name (e.g., 'natural_language_search'), and executes its handler.

  server.setRequestHandler(
    CallToolRequestSchema,
    async (request) => {
      logger.info(`[TOOL] Tool call requested: ${request.params.name}`);
      logger.info(`[TOOL] Tool arguments: ${JSON.stringify(request.params.arguments, null, 2)}`);
      
      const tool = tools.find((t) => t.name === request.params.name);
      if (!tool) {
        logger.error(`[TOOL] Tool not found: ${request.params.name || 'unknown'}`);
        logger.info(`[TOOL] Available tools: ${tools.map(t => t.name).join(', ')}`);
        throw new Error(`Tool not found: ${request.params.name || 'unknown'}`);
      }
  
      try {
        logger.info(`[TOOL] Executing tool: ${tool.name}`);
        logger.debug(`[TOOL] Tool handler called with arguments:`, request.params.arguments);
        const result = await tool.handler(request.params.arguments);
        logger.info(`[TOOL] Tool ${tool.name} completed successfully`);
        const resultStr = typeof result === 'string' ? result : JSON.stringify(result);
        logger.debug(`[TOOL] Tool result type: ${typeof result}, length: ${resultStr.length}`);
        
        const response = {
          content: [
            {