YouTube Transcript Server

Instructions

Implementation Reference

• src/index.ts:170-222 (handler)

  Tool dispatch handler for 'get_transcript': validates input arguments, extracts video ID, fetches transcript via extractor, formats response with metadata.

  case "get_transcript": {
    const { url: input, lang = "en" } = args;
    
    if (!input || typeof input !== 'string') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'URL parameter is required and must be a string'
      );
    }
  
    if (lang && typeof lang !== 'string') {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Language code must be a string'
      );
    }
    
    try {
      const videoId = this.extractor.extractYoutubeId(input);
      console.error(`Processing transcript for video: ${videoId}`);
      
      const transcript = await this.extractor.getTranscript(videoId, lang);
      console.error(`Successfully extracted transcript (${transcript.length} chars)`);
      
      return {
        toolResult: {
          content: [{
            type: "text",
            text: transcript,
            metadata: {
              videoId,
              language: lang,
              timestamp: new Date().toISOString(),
              charCount: transcript.length
            }
          }],
          isError: false
        }
      };
    } catch (error) {
      console.error('Transcript extraction failed:', error);
      
      if (error instanceof McpError) {
        throw error;
      }
      
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to process transcript: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:92-107 (handler)

  Core implementation of transcript extraction: calls external 'getSubtitles' library and formats the result.

  async getTranscript(videoId: string, lang: string): Promise<string> {
    try {
      const transcript = await getSubtitles({
        videoID: videoId,
        lang: lang,
      });
  
      return this.formatTranscript(transcript);
    } catch (error) {
      console.error('Failed to fetch transcript:', error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to retrieve transcript: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:17-37 (schema)

  Tool schema definition including name, description, and input schema for parameters 'url' and 'lang'.

  const TOOLS: Tool[] = [
    {
      name: "get_transcript",
      description: "Extract transcript from a YouTube video URL or ID",
      inputSchema: {
        type: "object",
        properties: {
          url: {
            type: "string",
            description: "YouTube video URL or ID"
          },
          lang: {
            type: "string",
            description: "Language code for transcript (e.g., 'ko', 'en')",
            default: "en"
          }
        },
        required: ["url", "lang"]
      }
    }
  ];

• src/index.ts:155-157 (registration)

  Registers the tool by providing it in the listTools response.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS
  }));

• src/index.ts:49-87 (helper)

  Helper function to extract canonical YouTube video ID from URL or direct ID input.

  extractYoutubeId(input: string): string {
    if (!input) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'YouTube URL or ID is required'
      );
    }
  
    // Handle URL formats
    try {
      const url = new URL(input);
      if (url.hostname === 'youtu.be') {
        return url.pathname.slice(1);
      } else if (url.hostname.includes('youtube.com')) {
        const videoId = url.searchParams.get('v');
        if (!videoId) {
          throw new McpError(
            ErrorCode.InvalidParams,
            `Invalid YouTube URL: ${input}`
          );
        }
        return videoId;
      }
    } catch (error) {
      // Not a URL, check if it's a direct video ID
      if (!/^[a-zA-Z0-9_-]{11}$/.test(input)) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `Invalid YouTube video ID: ${input}`
        );
      }
      return input;
    }
  
    throw new McpError(
      ErrorCode.InvalidParams,
      `Could not extract video ID from: ${input}`
    );
  }