Whissle MCP Server

Instructions

Implementation Reference

• whissle_mcp/server.py:452-513 (handler)

  The primary handler implementation for the 'list_asr_models' MCP tool. It is registered via the @mcp.tool decorator (which also serves as schema definition with no input parameters). The function fetches ASR models from the WhissleClient, handles various response formats, implements retry logic using handle_api_error, and returns a formatted TextContent.

  @mcp.tool(
      description="List all available ASR models and their capabilities."
  )
  def list_asr_models() -> TextContent:
      """List all available ASR models.
  
      Returns:
          TextContent with a formatted list of available models
      """
      try:
          logger.info("Fetching available ASR models...")
          
          retry_count = 0
          max_retries = 2  # Increased from 1 to 2
          
          while retry_count <= max_retries:
              try:
                  logger.info(f"Attempting to list models (Attempt {retry_count+1}/{max_retries+1})")
                  models = client.list_asr_models()
                  
                  if not models:
                      logger.error("No models were returned from the API")
                      return make_error("No models were returned from the API")
  
                  # Handle both string and object responses
                  if isinstance(models, list):
                      if all(isinstance(model, str) for model in models):
                          # If models is a list of strings
                          model_list = "\n".join(f"Model: {model}" for model in models)
                      else:
                          # If models is a list of objects with name and description
                          model_list = "\n".join(
                              f"Model: {model.name}\nDescription: {model.description}\n"
                              for model in models
                          )
                  else:
                      logger.error("Unexpected response format from API")
                      return make_error("Unexpected response format from API")
  
                  logger.info("Successfully retrieved ASR models")
                  return TextContent(
                      type="text",
                      text=f"Available ASR Models:\n\n{model_list}",
                  )
              except Exception as api_error:
                  error_msg = str(api_error)
                  logger.error(f"Error listing models: {error_msg}")
                  
                  # Handle API errors with retries
                  error_result = handle_api_error(error_msg, "listing models", retry_count, max_retries)
                  if error_result is not None:  # If we should not retry
                      return error_result  # Return the error message
                  
                  retry_count += 1
          
          # If we get here, all retries failed
          logger.error(f"All attempts to list models failed after {max_retries+1} attempts")
          return make_error(f"Failed to list ASR models after {max_retries+1} attempts")
      except Exception as e:
          logger.error(f"Unexpected error listing ASR models: {str(e)}")
          return make_error(f"Failed to list ASR models: {str(e)}")

• whissle_mcp/server.py:51-86 (helper)

  Shared helper function used by list_asr_models (and other tools) for handling API errors with retry logic for HTTP 500 errors and specific error messages for other status codes.

  def handle_api_error(error_msg, operation_name, retry_count=0, max_retries=2):
      """Helper function to handle API errors with retries and better error messages"""
      logger.error(f"API error during {operation_name}: {error_msg}")
      
      if "HTTP 500" in error_msg:
          if retry_count < max_retries:
              # Exponential backoff: 2, 4, 8 seconds
              wait_time = 2 ** (retry_count + 1)
              logger.info(f"HTTP 500 error during {operation_name}. Retrying in {wait_time} seconds... (Attempt {retry_count+1}/{max_retries+1})")
              time.sleep(wait_time)
              return None  # Signal to retry
          else:
              # Provide more detailed error message for upload issues
              if "uploading file" in error_msg.lower():
                  return make_error(
                      f"Server error during {operation_name}. The file upload to the Whissle API failed. "
                      f"This could be due to:\n"
                      f"1. Temporary server issues\n"
                      f"2. File format compatibility issues\n"
                      f"3. Network connectivity problems\n"
                      f"Please try again later or contact Whissle support. Error: {error_msg}"
                  )
              else:
                  return make_error(
                      f"Server error during {operation_name}. This might be a temporary issue with the Whissle API. "
                      f"Please try again later or contact Whissle support. Error: {error_msg}"
                  )
      elif "HTTP 413" in error_msg:
          return make_error(f"File too large. Please try a smaller file. Error: {error_msg}")
      elif "HTTP 415" in error_msg:
          return make_error(f"Unsupported file format. Please use a supported format. Error: {error_msg}")
      elif "HTTP 401" in error_msg or "HTTP 403" in error_msg:
          return make_error(f"Authentication error. Please check your API token. Error: {error_msg}")
      else:
          return make_error(f"API error during {operation_name}: {error_msg}")

• whissle_mcp/utils.py:9-11 (helper)

  Utility helper from utils.py imported and used in list_asr_models for creating standardized error responses.

  def make_error(message: str) -> None:
      """Raise an error with a message."""
      raise ValueError(message)