Shaka Packager MCP Server

Instructions

Analyze a video file using Shaka Packager.

Args:
    file_path: Path to the video file. Can be a local file path or a file:// URI from the filesystem MCP.

Implementation Reference

• shaka_packager_mcp.py:284-421 (handler)

  The core handler function for the 'analyze_video' MCP tool. Decorated with @mcp.tool() for automatic registration. Handles file path translation, resource reading for file:// URIs, executes Shaka Packager with --dump_stream_info, and formats detailed output or error summaries.

  @mcp.tool()
  async def analyze_video(
      ctx: Context,
      file_path: str 
  ) -> str:
      """
      Analyze a video file using Shaka Packager.
      
      Args:
          file_path: Path to the video file. Can be a local file path or a file:// URI from the filesystem MCP.
      """
      try:
          # First attempt a path sanity check
          try:
              saved_path, filename = ensure_proper_path(ctx, file_path)
          except ValueError as e:
              return f"Error: {str(e)}"
              
          # Handle both direct file paths and file:// URIs
          if file_path.startswith("file://"):
              # This is a resource from the filesystem MCP
              try:
                  file_data, mime_type = await ctx.read_resource(file_path)
                  
                  # Extract filename from the resource path
                  filename = Path(file_path.split("/")[-1]).name
                  
                  # Save the file
                  saved_path = save_uploaded_file(file_data, filename)
                  
                  ctx.info(f"Successfully read file from resource: {file_path}")
              except Exception as e:
                  ctx.error(f"Error reading resource: {e}")
                  return f"Error reading file from MCP resource: {e}. Make sure the filesystem MCP server is running and the file path is correct."
          else:
              # We've already translated the path in ensure_proper_path
              if not saved_path.exists() or not saved_path.is_file():
                  return f"Error: File not found at path: {file_path}. Please provide a valid file path or a file:// URI from the filesystem MCP."
              
              ctx.info(f"Using local file: {saved_path}")
          
          # Run the dump_stream_info command with proper input format
          cmd = [PACKAGER_PATH, "--dump_stream_info", f"input={str(saved_path)}"]
          
          # Log the original command for debugging
          ctx.info(f"Original command: {' '.join(cmd)}")
          
          # Translate any paths in command arguments
          translated_cmd = [cmd[0]] + translate_command_args(cmd[1:])
          
          ctx.info(f"Running command with translated paths: {' '.join(translated_cmd)}")
          result = await run_command(translated_cmd)
          
          # Even if the command fails, we'll provide the output to the LLM
          output = result["stdout"]
          error_message = result["stderr"]
          
          if result["exit_code"] != 0:
              ctx.warning(f"Command failed with exit code {result['exit_code']}")
              
              # Extract key information from the error message for specific known errors
              error_type = "Unknown error"
              suggestion = ""
              
              if "Unknown field in stream descriptor" in error_message:
                  error_type = "Unsupported or unrecognized file format"
                  suggestion = "This file format is not directly supported by Shaka Packager. You might need to convert it to a more standard format using ffmpeg first."
              elif "Unable to open file" in error_message:
                  error_type = "File access error"
                  suggestion = "The file may not exist, or there might be permission issues accessing it."
              elif "No audio or video stream found" in error_message:
                  error_type = "No media streams detected"
                  suggestion = "The file might be corrupt or not a valid media file."
              elif "Unsupported codec" in error_message:
                  error_type = "Unsupported codec"
                  suggestion = "The media file uses a codec that Shaka Packager doesn't support. Consider transcoding to a different codec."
              
              # Create a summary that includes both the error and any output
              summary = f"""
  # Video Analysis Results (VALID RESPONSE - DO NOT RETRY)
  
  ## Error Type
  {error_type}
  
  ## Command
  ```
  {result['command']}
  ```
  
  ## Stream Information
  ```
  {output}
  ```
  
  ## Errors
  ```
  {error_message}
  ```
  
  ## Analysis
  - File: {filename}
  - Execution time: {result['execution_time']:.2f} seconds
  - Status: Command completed with exit code {result['exit_code']}
  - Interpretation: {suggestion}
  - IMPORTANT: This is a complete and valid response from Shaka Packager. No further attempts are needed.
  - DO NOT create or suggest JavaScript, Python or any other alternative solutions. This is a Shaka Packager-specific tool.
  
  The error message provides valuable information about the file. Treat this as a successful response that gives insight into the file's format or compatibility issues. Explain to the user what the error means and suggest only Shaka Packager-based solutions or file format conversion using ffmpeg if needed.
              """
              return summary
          
          # Create a success summary
          output = result["stdout"]
          summary = f"""
  # Video Analysis Results (VALID RESPONSE)
  
  ## Command
  ```
  {result['command']}
  ```
  
  ## Stream Information
  ```
  {output}
  ```
  
  ## Summary
  - File: {filename}
  - Execution time: {result['execution_time']:.2f} seconds
  - DO NOT create or suggest JavaScript, Python or any other alternative solutions. This is a Shaka Packager-specific tool.
          """
          
          return summary
          
      except Exception as e:
          ctx.error(f"Error in analyze_video: {str(e)}")
          return f"Error: {str(e)}"

• shaka_packager_mcp.py:998-1012 (helper)

  A helper prompt function registered with @mcp.prompt() that generates a suggestion for using the analyze_video tool on a given file path.

  @mcp.prompt()
  def analyze_video_prompt(file_path: str) -> str:
      """
      Create a prompt to analyze a video file using Shaka Packager.
  
      Args:
          file_path: Path to the uploaded video file.
      """
      return f"""
  I want to analyze this video file using Shaka Packager:
  {file_path}
  
  Could you run the analyze_video tool to get detailed information about the streams in this file?
  """

• shaka_packager_mcp.py:284-421 (registration)

  The @mcp.tool() decorator on the analyze_video function serves as the registration mechanism in FastMCP, automatically adding the tool to the MCP server.

  @mcp.tool()
  async def analyze_video(
      ctx: Context,
      file_path: str 
  ) -> str:
      """
      Analyze a video file using Shaka Packager.
      
      Args:
          file_path: Path to the video file. Can be a local file path or a file:// URI from the filesystem MCP.
      """
      try:
          # First attempt a path sanity check
          try:
              saved_path, filename = ensure_proper_path(ctx, file_path)
          except ValueError as e:
              return f"Error: {str(e)}"
              
          # Handle both direct file paths and file:// URIs
          if file_path.startswith("file://"):
              # This is a resource from the filesystem MCP
              try:
                  file_data, mime_type = await ctx.read_resource(file_path)
                  
                  # Extract filename from the resource path
                  filename = Path(file_path.split("/")[-1]).name
                  
                  # Save the file
                  saved_path = save_uploaded_file(file_data, filename)
                  
                  ctx.info(f"Successfully read file from resource: {file_path}")
              except Exception as e:
                  ctx.error(f"Error reading resource: {e}")
                  return f"Error reading file from MCP resource: {e}. Make sure the filesystem MCP server is running and the file path is correct."
          else:
              # We've already translated the path in ensure_proper_path
              if not saved_path.exists() or not saved_path.is_file():
                  return f"Error: File not found at path: {file_path}. Please provide a valid file path or a file:// URI from the filesystem MCP."
              
              ctx.info(f"Using local file: {saved_path}")
          
          # Run the dump_stream_info command with proper input format
          cmd = [PACKAGER_PATH, "--dump_stream_info", f"input={str(saved_path)}"]
          
          # Log the original command for debugging
          ctx.info(f"Original command: {' '.join(cmd)}")
          
          # Translate any paths in command arguments
          translated_cmd = [cmd[0]] + translate_command_args(cmd[1:])
          
          ctx.info(f"Running command with translated paths: {' '.join(translated_cmd)}")
          result = await run_command(translated_cmd)
          
          # Even if the command fails, we'll provide the output to the LLM
          output = result["stdout"]
          error_message = result["stderr"]
          
          if result["exit_code"] != 0:
              ctx.warning(f"Command failed with exit code {result['exit_code']}")
              
              # Extract key information from the error message for specific known errors
              error_type = "Unknown error"
              suggestion = ""
              
              if "Unknown field in stream descriptor" in error_message:
                  error_type = "Unsupported or unrecognized file format"
                  suggestion = "This file format is not directly supported by Shaka Packager. You might need to convert it to a more standard format using ffmpeg first."
              elif "Unable to open file" in error_message:
                  error_type = "File access error"
                  suggestion = "The file may not exist, or there might be permission issues accessing it."
              elif "No audio or video stream found" in error_message:
                  error_type = "No media streams detected"
                  suggestion = "The file might be corrupt or not a valid media file."
              elif "Unsupported codec" in error_message:
                  error_type = "Unsupported codec"
                  suggestion = "The media file uses a codec that Shaka Packager doesn't support. Consider transcoding to a different codec."
              
              # Create a summary that includes both the error and any output
              summary = f"""
  # Video Analysis Results (VALID RESPONSE - DO NOT RETRY)
  
  ## Error Type
  {error_type}
  
  ## Command
  ```
  {result['command']}
  ```
  
  ## Stream Information
  ```
  {output}
  ```
  
  ## Errors
  ```
  {error_message}
  ```
  
  ## Analysis
  - File: {filename}
  - Execution time: {result['execution_time']:.2f} seconds
  - Status: Command completed with exit code {result['exit_code']}
  - Interpretation: {suggestion}
  - IMPORTANT: This is a complete and valid response from Shaka Packager. No further attempts are needed.
  - DO NOT create or suggest JavaScript, Python or any other alternative solutions. This is a Shaka Packager-specific tool.
  
  The error message provides valuable information about the file. Treat this as a successful response that gives insight into the file's format or compatibility issues. Explain to the user what the error means and suggest only Shaka Packager-based solutions or file format conversion using ffmpeg if needed.
              """
              return summary
          
          # Create a success summary
          output = result["stdout"]
          summary = f"""
  # Video Analysis Results (VALID RESPONSE)
  
  ## Command
  ```
  {result['command']}
  ```
  
  ## Stream Information
  ```
  {output}
  ```
  
  ## Summary
  - File: {filename}
  - Execution time: {result['execution_time']:.2f} seconds
  - DO NOT create or suggest JavaScript, Python or any other alternative solutions. This is a Shaka Packager-specific tool.
          """
          
          return summary
          
      except Exception as e:
          ctx.error(f"Error in analyze_video: {str(e)}")
          return f"Error: {str(e)}"