search_by_subject

Instructions

Implementation Reference

• src/tools/gallicaSearch.ts:112-150 (handler)

  The main tool handler and registration for search_by_subject. Creates the tool with name, description, input schema, and async handler function that parses arguments and calls the SearchAPI.searchBySubject method.

  export function createSearchBySubjectTool(searchApi: SearchAPI) {
    return {
      name: 'search_by_subject',
      description: 'Search for documents in the Gallica digital library by subject.',
      inputSchema: {
        type: 'object',
        properties: {
          subject: {
            type: 'string',
            description: 'The subject to search for',
          },
          exact_match: {
            type: 'boolean',
            description: 'If true, search for the exact subject; otherwise, search for subject 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: ['subject'],
      },
      handler: async (args: unknown) => {
        const parsed = exactMatchSchema.extend({ subject: z.string() }).parse(args);
        return await searchApi.searchBySubject(
          parsed.subject,
          parsed.exact_match ?? false,
          parsed.max_results ?? config.defaultMaxRecords,
          parsed.start_record ?? config.defaultStartRecord
        );
      },
    };

• src/gallica/search.ts:203-211 (handler)

  The actual implementation of searchBySubject method in the SearchAPI class. Constructs the SRU query using 'dc.subject' field with optional exact matching, then delegates to the core search method.

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

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

  Schema definitions used by search_by_subject. Defines searchParamsSchema (max_results, start_record) and exactMatchSchema which extends it with exact_match boolean field.

  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(),
  });

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

  Import statement for createSearchBySubjectTool function from tools/gallicaSearch.js.

  createSearchBySubjectTool,

• src/mcpServer.ts:78-97 (registration)

  Tool instantiation and registration. Creates the searchBySubject tool instance on line 78 and adds it to the tools array on line 97 for MCP server registration.

  const searchBySubject = createSearchBySubjectTool(searchApi);
  const searchByDate = createSearchByDateTool(searchApi);
  const searchByDocumentType = createSearchByDocumentTypeTool(searchApi);
  const advancedSearch = createAdvancedSearchTool(searchApi);
  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,