youtube-summarize

Instructions

Implementation Reference

• main.py:165-188 (handler)

  The list_transcripts tool handler that fetches and displays available transcript languages for a YouTube video, including metadata about each transcript (language, type, translatable status).

  @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:37-47 (helper)

  Helper function extract_video_id that parses a YouTube video URL or bare ID to extract the 11-character video ID used by list_transcripts.

  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}"
      )

• main.py:58-88 (helper)

  Error handling helper function _handle_transcript_error that converts youtube_transcript_api exceptions into user-friendly error messages for list_transcripts.

  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}"