TranscriptionTools MCP Server

Instructions

Implementation Reference

• src/tools/formatting.ts:18-115 (handler)

  Core implementation of the format_transcript tool: parses timestamped lines, extracts times, groups text, and applies formatting rules based on time gaps and grammar for natural reading flow.

  export async function formatTranscript(params: FormatTranscriptParams): Promise<{ formatted_text: string }> {
    try {
      const { 
        input_text, 
        is_file_path = false, 
        paragraph_gap = 8, // default 8 seconds for paragraph breaks
        line_gap = 4 // default 4 seconds for line breaks
      } = params;
      
      // Resolve content (either direct text or from file)
      const textContent = await FileHandler.resolveTextContent(input_text, is_file_path);
      
      // Parse the timestamped transcript
      const lines = textContent.trim().split('\n');
      
      // This will store our processed text segments with their timestamps
      const segments: Array<{ time: number; text: string }> = [];
      
      // Parse each line to extract timestamp and text
      for (const line of lines) {
        // Extract timestamp using regex
        const match = line.match(/\[(\d{2}):(\d{2}):(\d{2})\]\s*(.*)/);
        
        if (match) {
          const hours = parseInt(match[1], 10);
          const minutes = parseInt(match[2], 10);
          const seconds = parseInt(match[3], 10);
          const text = match[4].trim();
          
          // Convert timestamp to seconds
          const timeInSeconds = hours * 3600 + minutes * 60 + seconds;
          
          // Add to segments
          segments.push({ time: timeInSeconds, text });
        } else {
          // Handle lines without timestamps
          if (segments.length > 0) {
            // Append to the previous segment if it exists
            segments[segments.length - 1].text += ' ' + line.trim();
          } else {
            // Create a new segment with time 0 if no previous segment
            segments.push({ time: 0, text: line.trim() });
          }
        }
      }
      
      // Process segments to create naturally formatted text
      let formattedText = '';
      let lastTime = -1;
      
      for (let i = 0; i < segments.length; i++) {
        const segment = segments[i];
        
        // First segment or determine spacing based on time gap
        if (i === 0) {
          formattedText = segment.text;
        } else {
          const timeGap = segment.time - lastTime;
          
          // Rule 1: Paragraph break for gaps > paragraph_gap seconds
          if (timeGap > paragraph_gap) {
            formattedText += '\n\n' + segment.text;
          }
          // Rule 2: Line break for gaps > line_gap seconds
          else if (timeGap > line_gap) {
            formattedText += '\n' + segment.text;
          }
          // Rule 3: Apply natural grammar rules
          else {
            // Check if we should add space or join without space
            const lastChar = formattedText.charAt(formattedText.length - 1);
            const endsWithSentenceMarker = /[.!?]$/.test(formattedText);
            const startsWithLowerCase = /^[a-z]/.test(segment.text);
            
            if (endsWithSentenceMarker) {
              // Start a new sentence
              formattedText += ' ' + segment.text;
            } else if (lastChar === ',' || lastChar === ';' || lastChar === ':') {
              // Continue after punctuation
              formattedText += ' ' + segment.text;
            } else if (startsWithLowerCase) {
              // Likely continuing a thought
              formattedText += ' ' + segment.text;
            } else {
              // Otherwise just add space
              formattedText += ' ' + segment.text;
            }
          }
        }
        
        lastTime = segment.time;
      }
      
      return { formatted_text: formattedText };
    } catch (error) {
      throw new Error(`Formatting process failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/tools/formatting.ts:6-11 (schema)

  TypeScript interface defining the input parameters for the formatTranscript function.

  export interface FormatTranscriptParams {
    input_text: string;
    is_file_path?: boolean;
    paragraph_gap?: number; // seconds
    line_gap?: number; // seconds
  }

• src/index.ts:88-116 (registration)

  MCP tool registration in listTools handler: defines name, description, and inputSchema for format_transcript.

  {
    name: 'format_transcript',
    description: 'Transforms timestamped transcripts into naturally formatted text',
    inputSchema: {
      type: 'object',
      properties: {
        input_text: {
          type: 'string',
          description: 'Timestamped transcript text or path to file'
        },
        is_file_path: {
          type: 'boolean',
          description: 'Whether input_text is a file path',
          default: false
        },
        paragraph_gap: {
          type: 'number', 
          description: 'Seconds gap for paragraph breaks',
          default: 8
        },
        line_gap: {
          type: 'number',
          description: 'Seconds gap for line breaks',
          default: 4
        }
      },
      required: ['input_text']
    }
  },

• src/index.ts:185-198 (registration)

  Dispatch logic in callToolRequest handler: validates params and invokes formatTranscript function for format_transcript tool.

  case 'format_transcript':
    // Validate required parameters
    if (!args || typeof args.input_text !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: input_text');
    }
    const formatResult = await formatTranscript(args as unknown as FormatTranscriptParams);
    return {
      content: [
        {
          type: 'text',
          text: formatResult.formatted_text
        }
      ]
    };