YouTube Search & Download MCP Server

Instructions

Implementation Reference

• src/youtube_search_mcp/tools/playlist_tools.py:29-92 (handler)

  The handler function `search_playlists` which is registered as an MCP tool. It validates the input, calls the search provider, formats the results, and handles exceptions.

  @mcp.tool()
  async def search_playlists(
      query: str, max_results: int = 10, output_format: str = "json"
  ) -> str:
      """
      Search YouTube for playlists matching a query.
  
      Args:
          query: Search query string (e.g., "python tutorial playlist")
          max_results: Maximum number of results to return (1-50, default: 10)
          output_format: Output format - "json" or "markdown" (default: "json")
  
      Returns:
          Formatted search results with playlist metadata
  
      Example:
          search_playlists("machine learning course", max_results=5, output_format="json")
      """
      try:
          logger.info(f"Playlist search request: query='{query}', max_results={max_results}")
  
          # Validate query
          validated_query = validate_query(query)
  
          # Execute search
          provider = get_search_provider()
          playlists = await provider.search_playlists(validated_query, max_results)
  
          # Format results
          formatter = get_formatter(output_format)
          result = formatter.format_playlists(playlists)
  
          logger.info(f"Playlist search completed: found {len(playlists)} playlists")
          return result
  
      except InvalidQueryError as e:
          logger.warning(f"Invalid query: {e.message}")
          return json.dumps({"error": "invalid_query", "message": e.message})
      except NetworkError as e:
          logger.error(f"Network error: {e.message}")
          return json.dumps(
              {
                  "error": "network_error",
                  "message": "Failed to connect to YouTube. Please try again.",
                  "details": e.message,
              }
          )
      except SearchProviderError as e:
          logger.error(f"Search provider error: {e.message}", exc_info=True)
          return json.dumps(
              {
                  "error": "search_failed",
                  "message": "Playlist search operation failed. Please try a different query.",
                  "details": e.message,
              }
          )
      except Exception:
          logger.exception("Unexpected error in search_playlists")
          return json.dumps(
              {
                  "error": "internal_error",
                  "message": "An unexpected error occurred. Please try again later.",
              }
          )

• src/youtube_search_mcp/tools/playlist_tools.py:21-27 (registration)

  The `register_playlist_tools` function that registers the tools to the FastMCP instance.

  def register_playlist_tools(mcp: FastMCP) -> None:
      """
      Register all playlist-related tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance
      """