SRT Translation MCP Server

Instructions

Implementation Reference

• src/mcp/server.ts:669-722 (handler)

  The main execution handler for the 'translate_srt' tool. Parses SRT content using parseSRTFile and structures it into a format with subtitles, timings, and instructions for an AI to perform the actual translation. Does not translate text itself; it's a helper tool.

  private async handleTranslateSRT(args: any) {
    const { content, targetLanguage, sourceLanguage } = args;
    
    const parseResult = parseSRTFile(content);
  
    if (!parseResult.success || !parseResult.file) {
      const errorDetails = parseResult.errors?.map(e => `${e.type}: ${e.message}`).join(', ') || 'Unknown parsing error';
      throw new Error(`Failed to parse SRT file: ${errorDetails}`);
    }
  
    // Return structured data for AI translation - DO NOT TRANSLATE HERE
    const translationData = {
      originalSRT: content,
      parsedData: parseResult.file,
      translationInstructions: {
        targetLanguage: targetLanguage,
        sourceLanguage: sourceLanguage || 'auto',
        preserveTiming: true,
        preserveFormatting: true,
        context: 'subtitle_translation'
      },
      subtitles: parseResult.file.subtitles.map((subtitle, index) => ({
        index: index,
        id: `subtitle-${subtitle.index}`,
        startTime: subtitle.startTime,
        endTime: subtitle.endTime,
        originalText: subtitle.text,
        translationInstructions: {
          preserveTags: true,
          maintainTone: 'conversational',
          context: `Subtitle ${index + 1} of ${parseResult.file!.subtitles.length}`
        }
      })),
      aiTranslationTask: {
        description: `Translate ${parseResult.file!.subtitles.length} subtitles from ${sourceLanguage || 'auto'} to ${targetLanguage}`,
        instructions: [
          'Translate each subtitle text while preserving timing and formatting',
          'Maintain conversational tone and context',
          'Preserve any HTML tags or formatting',
          'Return complete translated SRT file'
        ],
        expectedOutput: 'Complete translated SRT file with all timing preserved'
      }
    };
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(translationData, null, 2),
        },
      ],
    };
  }

• src/mcp/server.ts:243-308 (registration)

  Tool registration in the MCP server's listTools handler, including the tool name, detailed description emphasizing it's a helper, and input schema defining parameters: content (required), targetLanguage (required), sourceLanguage (optional).

            {
              name: 'translate_srt',
              description: `🌍 SRT TRANSLATION HELPER TOOL 🌍
  
  🚨 CRITICAL: THIS IS A HELPER TOOL ONLY - AI DOES THE TRANSLATION! 🚨
  
  🎯 PURPOSE:
  This tool helps prepare SRT content for AI translation but DOES NOT translate text itself.
  The AI assistant must perform the actual translation work.
  
  📝 WHAT IT DOES:
  - Parses SRT content and extracts subtitle text for AI translation
  - Preserves timing and formatting structure
  - Returns structured data for AI to translate
  - Provides context and metadata for better translation
  
  ❌ WHAT IT DOES NOT DO:
  - ❌ Does NOT translate text automatically
  - ❌ Does NOT return translated content
  - ❌ Does NOT perform any AI translation
  
  ✅ WHAT IT RETURNS:
  - Structured SRT data with original text
  - Timing and formatting information
  - Translation context and metadata
  - Ready-to-translate format for AI
  
  🔄 RECOMMENDED WORKFLOW:
  1. Use detect_conversations to analyze file structure
  2. Use get_next_chunk to get individual chunks
  3. Use translate_srt to prepare chunk for AI translation
  4. AI assistant translates the text content
  5. AI assistant combines results into final SRT file
  
  💡 USAGE PATTERNS:
  
  Prepare Full File for Translation:
  {"content": "full SRT content", "targetLanguage": "es", "sourceLanguage": "en"}
  
  Prepare Individual Chunk for Translation:
  {"content": "chunk SRT content", "targetLanguage": "es", "sourceLanguage": "en"}
  
  ⚠️ CRITICAL INSTRUCTIONS:
  - This tool ONLY prepares content for AI translation
  - AI assistant must do the actual text translation
  - Use this to get structured data, then translate with AI
  - Return format is ready for AI processing`,
              inputSchema: {
                type: 'object',
                properties: {
                  content: {
                    type: 'string',
                    description: 'SRT file content to translate',
                  },
                  targetLanguage: {
                    type: 'string',
                    description: 'Target language code (e.g., es, fr, de)',
                  },
                  sourceLanguage: {
                    type: 'string',
                    description: 'Source language code (optional, auto-detect if not provided)',
                  },
                },
                required: ['content', 'targetLanguage'],
              },
            },

• src/mcp/server.ts:290-307 (schema)

  Input schema for the translate_srt tool, specifying the expected arguments structure and types.

  inputSchema: {
    type: 'object',
    properties: {
      content: {
        type: 'string',
        description: 'SRT file content to translate',
      },
      targetLanguage: {
        type: 'string',
        description: 'Target language code (e.g., es, fr, de)',
      },
      sourceLanguage: {
        type: 'string',
        description: 'Source language code (optional, auto-detect if not provided)',
      },
    },
    required: ['content', 'targetLanguage'],
  },