sequential_reporting

Instructions

Implementation Reference

• src/tools/reports.ts:11-118 (registration)

  Tool registration and schema definition - createSequentialReportingTool defines the tool name, description, input schema with all parameters (topic, page_count, source_count, search_sources, section_number, total_sections, title, content, is_bibliography, sources_used, next_section_needed, include_graphics), and the handler that wraps the SequentialReportingServer.processSection call.

  export function createSequentialReportingTool(reportingServer: SequentialReportingServer) {
    return {
      name: 'sequential_reporting',
      description: `Generate a research report in a sequential, step-by-step manner using Gallica BnF sources.
  
  This tool follows a sequential approach to report generation:
  1. Initialize with a topic
  2. Search for sources
  3. Create bibliography
  4. Create content sections in order
  
  Parameters:
  - topic: Research topic (only needed for initialization)
  - page_count: Number of pages for the report (default: 4)
  - source_count: Number of sources to find (default: 10)
  - search_sources: Set to true to search for sources after initialization
  - section_number: Current section number (1-based)
  - total_sections: Total number of sections in the report
  - title: Title of the current section
  - content: Content for the current section
  - is_bibliography: Whether this section is the bibliography
  - sources_used: List of source IDs used in this section
  - next_section_needed: Whether another section is needed
  - include_graphics: Whether to include images and maps in the report`,
      inputSchema: {
        type: 'object',
        properties: {
          topic: {
            type: 'string',
            description: 'Research topic for the report (only needed for initialization)',
          },
          page_count: {
            type: 'number',
            description: 'Number of pages to generate',
            minimum: 1,
            default: 4,
          },
          source_count: {
            type: 'number',
            description: 'Number of sources to find',
            minimum: 1,
            default: 10,
          },
          search_sources: {
            type: 'boolean',
            description: 'Set to true to search for sources after initialization',
          },
          section_number: {
            type: 'number',
            description: 'Current section number',
            minimum: 1,
          },
          total_sections: {
            type: 'number',
            description: 'Total sections in the report',
            minimum: 1,
          },
          title: {
            type: 'string',
            description: 'Title of the current section',
          },
          content: {
            type: 'string',
            description: 'Content of the current section',
          },
          is_bibliography: {
            type: 'boolean',
            description: 'Whether this section is the bibliography',
          },
          sources_used: {
            type: 'array',
            items: { type: 'number' },
            description: 'List of source IDs used in this section',
          },
          next_section_needed: {
            type: 'boolean',
            description: 'Whether another section is needed',
          },
          include_graphics: {
            type: 'boolean',
            description: 'Whether to include graphics in the report',
            default: false,
          },
        },
        required: ['section_number', 'total_sections', 'title', 'content', 'next_section_needed'],
      },
      handler: async (args: unknown) => {
        // Use a more flexible schema that allows partial validation
        const schema = z.object({
          topic: z.string().optional(),
          page_count: z.number().int().positive().optional(),
          source_count: z.number().int().positive().optional(),
          search_sources: z.boolean().optional(),
          section_number: z.number().int().positive().optional(),
          total_sections: z.number().int().positive().optional(),
          title: z.string().optional(),
          content: z.string().optional(),
          is_bibliography: z.boolean().optional(),
          sources_used: z.array(z.number().int()).optional(),
          next_section_needed: z.boolean().optional(),
          include_graphics: z.boolean().optional(),
        });
  
        const parsed = schema.parse(args);
        return await reportingServer.processSection(parsed);
      },
    };
  }

• src/gallica/sequential_reporting.ts:372-489 (handler)

  Main handler logic - processSection method implements the sequential reporting workflow: validates input data, handles initialization with topic, searches for sources and graphics, processes report sections, updates state, and returns structured responses with progress tracking and next steps.

  async processSection(inputData: unknown): Promise<{ content: Array<{ text: string }>; isError?: boolean }> {
    try {
      const data = this.validateSectionData(inputData as Record<string, unknown>);
  
      // Initialize with topic
      if ('topic' in data) {
        this.state.topic = data.topic as string;
        this.state.page_count = (data.page_count as number) || DEFAULT_PAGE_COUNT;
        this.state.source_count = (data.source_count as number) || DEFAULT_SOURCE_COUNT;
        this.state.include_graphics = Boolean(data.include_graphics);
        this.state.sources = [];
        this.state.graphics = [];
        this.state.report_sections = [];
        this.state.current_step = 0;
  
        // Create plan
        this.state.plan = this.createPlan(this.state.topic, this.state.page_count);
  
        return {
          content: [{
            text: JSON.stringify({
              topic: this.state.topic,
              pageCount: this.state.page_count,
              sourceCount: this.state.source_count,
              includeGraphics: this.state.include_graphics,
              plan: this.state.plan,
              nextStep: 'Search for sources using natural_language_search or search_by_subject',
            }),
          }],
        };
      }
  
      // Search for sources
      if (data.search_sources) {
        if (!this.state.topic) {
          return {
            content: [{ text: 'Error: No topic specified. Please initialize with a topic first.' }],
            isError: true,
          };
        }
  
        this.state.sources = await this.searchSources(this.state.topic, this.state.source_count);
  
        // If graphics are requested, search for them
        if (this.state.include_graphics) {
          this.state.graphics = await this.searchGraphics(this.state.topic, 5);
        }
  
        this.state.current_step = 1;
  
        return {
          content: [{
            text: JSON.stringify({
              sources: this.state.sources,
              graphics: this.state.include_graphics ? this.state.graphics : [],
              nextStep: 'Create bibliography section',
            }),
          }],
        };
      }
  
      // Process section data
      const validatedInput = this.validateSectionData(inputData as Record<string, unknown>);
  
      // Adjust total sections if needed
      if ((validatedInput.section_number as number) > (validatedInput.total_sections as number)) {
        validatedInput.total_sections = validatedInput.section_number;
      }
  
      // Add section to report
      this.state.report_sections.push(validatedInput as unknown as ReportSection);
  
      // Update current step in plan
      let nextStep = 'Continue writing the report';
      if (this.state.plan) {
        this.state.plan.current_section = validatedInput.section_number as number;
        const sectionIndex = (validatedInput.section_number as number) - 1;
        if (sectionIndex < this.state.plan.sections.length) {
          const nextSectionTitle = this.state.plan.sections[sectionIndex + 1]?.title || 'Next Section';
          nextStep = `Create section ${(validatedInput.section_number as number) + 1}: ${nextSectionTitle}`;
        } else {
          nextStep = 'Report complete';
        }
      }
  
      if (!validatedInput.next_section_needed) {
        nextStep = 'Report complete';
      }
  
      // Calculate progress
      const progress = (this.state.report_sections.length / (validatedInput.total_sections as number)) * 100;
  
      return {
        content: [{
          text: JSON.stringify({
            sectionNumber: validatedInput.section_number,
            totalSections: validatedInput.total_sections,
            nextSectionNeeded: validatedInput.next_section_needed,
            progress: `${progress.toFixed(1)}%`,
            reportSectionsCount: this.state.report_sections.length,
            nextStep: nextStep,
            sources: validatedInput.is_bibliography ? this.state.sources : undefined,
          }),
        }],
      };
    } catch (error) {
      logger.error(`Error processing report section: ${error instanceof Error ? error.message : String(error)}`);
      return {
        content: [{
          text: JSON.stringify({
            error: error instanceof Error ? error.message : String(error),
            status: 'failed',
          }),
        }],
        isError: true,
      };
    }
  }

• src/gallica/sequential_reporting.ts:17-34 (handler)

  SequentialReportingServer class constructor - initializes the reporting server with GallicaAPI and SearchAPI dependencies, sets up the initial state with default values for page_count (4), source_count (10), and empty arrays for sources, graphics, and report sections.

  export class SequentialReportingServer {
    private searchApi: SearchAPI;
    private state: SequentialReportState;
  
    constructor(_gallicaApi: GallicaAPI, searchApi: SearchAPI) {
      this.searchApi = searchApi;
      this.state = {
        topic: null,
        page_count: DEFAULT_PAGE_COUNT,
        source_count: DEFAULT_SOURCE_COUNT,
        sources: [],
        report_sections: [],
        plan: null,
        current_step: 0,
        include_graphics: false,
        graphics: [],
      };
    }

• src/gallica/types.ts:112-122 (schema)

  Type definition for SequentialReportState schema - defines the state structure including topic, page_count, source_count, sources array, report_sections array, plan, current_step, include_graphics, and graphics array.

  export interface SequentialReportState {
    topic: string | null;
    page_count: number;
    source_count: number;
    sources: Source[];
    report_sections: ReportSection[];
    plan: ReportPlan | null;
    current_step: number;
    include_graphics: boolean;
    graphics: Graphic[];
  }

• src/mcpServer.ts:73-106 (registration)

  MCP server registration - instantiates SequentialReportingServer with gallicaApi and searchApi (line 73), creates the sequentialReporting tool using createSequentialReportingTool (line 91), and adds it to the tools array that is registered with the MCP server (line 106).

  const reportingServer = new SequentialReportingServer(gallicaApi, searchApi);
  
  // Register search tools (7 tools matching Python)
  const searchByTitle = createSearchByTitleTool(searchApi);
  const searchByAuthor = createSearchByAuthorTool(searchApi);
  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,
    searchByDate,
    searchByDocumentType,
    advancedSearch,
    naturalLanguageSearch,
    getItemDetails,
    getItemPages,
    getPageImage,
    getPageText,
    sequentialReporting,