list_transcripts

Instructions

Implementation Reference

• main.py:524-547 (handler)

  Tool registration and handler for 'list_transcripts'. Uses @mcp.tool() decorator. Extracts video ID, calls api.list(video_id) to get available transcripts, and formats each transcript's language, code, type (auto-generated/manual), and translatability.

  @mcp.tool()
  def list_transcripts(url: str) -> str:
      """List available transcript languages for a YouTube video.
  
      Args:
          url: YouTube video URL or video ID
      """
      try:
          video_id = extract_video_id(url)
      except ValueError as e:
          return f"Error: {e}"
  
      try:
          transcript_list = api.list(video_id)
          lines = [f"Available transcripts for video '{video_id}':\n"]
          for t in transcript_list:
              kind = "auto-generated" if t.is_generated else "manual"
              translatable = "translatable" if t.is_translatable else "not translatable"
              lines.append(f"  - {t.language} ({t.language_code}) [{kind}, {translatable}]")
          if len(lines) == 1:
              return f"No transcripts found for video '{video_id}'."
          return "\n".join(lines)
      except Exception as e:
          return _handle_transcript_error(e, video_id, None)

• main.py:524-524 (registration)

  The @mcp.tool() decorator on line 524 registers 'list_transcripts' as an MCP tool with FastMCP server 'youtube-summary'.

  @mcp.tool()

• main.py:40-63 (helper)

  extract_video_id helper used by list_transcripts to parse video ID from URLs or bare IDs.

  def extract_video_id(url_or_id: str) -> str:
      """Extract a YouTube video ID from a URL or bare ID string."""
      url_or_id = url_or_id.strip()
      if BARE_ID_REGEX.match(url_or_id):
          return url_or_id
      match = VIDEO_ID_REGEX.search(url_or_id)
      if match:
          return match.group(1)
      raise ValueError(
          f"Could not extract a YouTube video ID from: {url_or_id}"
      )
  
  
  def extract_playlist_id(url_or_id: str) -> str:
      """Extract a YouTube playlist ID from a URL or bare ID string."""
      s = url_or_id.strip()
      if BARE_PLAYLIST_ID_REGEX.match(s):
          return s
      match = PLAYLIST_LIST_PARAM_REGEX.search(s)
      if match:
          return match.group(1)
      raise ValueError(
          f"Could not extract a YouTube playlist ID from: {url_or_id}"
      )

• main.py:74-104 (helper)

  _handle_transcript_error helper used by list_transcripts and other tools to convert youtube_transcript_api exceptions to user-friendly error messages.

  def _handle_transcript_error(e: Exception, video_id: str, languages: list[str] | None = None) -> str:
      """Convert youtube_transcript_api exceptions into user-friendly error strings."""
      from youtube_transcript_api import (
          AgeRestricted,
          InvalidVideoId,
          IpBlocked,
          NoTranscriptFound,
          RequestBlocked,
          TranscriptsDisabled,
          VideoUnavailable,
      )
  
      if isinstance(e, TranscriptsDisabled):
          return f"Error: Transcripts are disabled for video '{video_id}'."
      if isinstance(e, NoTranscriptFound):
          lang_str = ", ".join(languages) if languages else "any"
          return (
              f"Error: No transcript found for video '{video_id}' "
              f"in language(s): {lang_str}. Use list_transcripts to see available languages."
          )
      if isinstance(e, VideoUnavailable):
          return f"Error: Video '{video_id}' is unavailable."
      if isinstance(e, InvalidVideoId):
          return f"Error: '{video_id}' is not a valid YouTube video ID."
      if isinstance(e, AgeRestricted):
          return f"Error: Video '{video_id}' is age-restricted and cannot be accessed."
      if isinstance(e, IpBlocked):
          return "Error: YouTube is blocking requests from this IP address."
      if isinstance(e, RequestBlocked):
          return "Error: The request to YouTube was blocked."
      return f"Error fetching transcript for '{video_id}': {e}"