Whissle MCP Server

Instructions

Implementation Reference

• whissle_mcp/server.py:107-201 (handler)

  The handler function that implements the speech_to_text tool logic. It performs input validation on the audio file (existence, size, format), calls the Whissle client's speech_to_text method with retries and error handling, processes the response to extract transcript, timestamps, etc., and returns a dictionary with the results.
  def speech_to_text(audio_file_path: str, model_name: str = "en-NER", timestamps: bool = True, boosted_lm_words: List[str] = None, boosted_lm_score: int = 80) -> Dict: """Convert speech to text using Whissle API""" try: # Check if file exists if not os.path.exists(audio_file_path): logger.error(f"Audio file not found: {audio_file_path}") return {"error": f"Audio file not found: {audio_file_path}"} # Check file size file_size = os.path.getsize(audio_file_path) if file_size == 0: logger.error(f"Audio file is empty: {audio_file_path}") return {"error": f"Audio file is empty: {audio_file_path}"} # Check file format file_ext = os.path.splitext(audio_file_path)[1].lower() if file_ext not in ['.wav', '.mp3', '.ogg', '.flac', '.m4a']: logger.error(f"Unsupported audio format: {file_ext}") return {"error": f"Unsupported audio format: {file_ext}. Supported formats: wav, mp3, ogg, flac, m4a"} # Check file size limits max_size_mb = 25 if file_size > max_size_mb * 1024 * 1024: logger.error(f"File too large: {file_size / (1024*1024):.2f} MB") return {"error": f"File too large ({file_size / (1024*1024):.2f} MB). Maximum size is {max_size_mb} MB."} # Log the request details logger.info(f"Transcribing audio file: {audio_file_path}") logger.info(f"File size: {file_size / (1024*1024):.2f} MB") logger.info(f"File format: {file_ext}") # Try with a different model if the default one fails models_to_try = ["en-NER"] last_error = None for try_model in models_to_try: retry_count = 0 max_retries = 2 while retry_count <= max_retries: try: logger.info(f"Attempting transcription with model: {try_model} (Attempt {retry_count+1}/{max_retries+1})") response = client.speech_to_text( audio_file_path=audio_file_path, model_name=try_model, timestamps=timestamps, boosted_lm_words=boosted_lm_words, boosted_lm_score=boosted_lm_score ) if response and hasattr(response, 'transcript'): logger.info(f"Transcription successful with model: {try_model}") result = { "transcript": response.transcript, "duration_seconds": getattr(response, 'duration_seconds', 0), "language_code": getattr(response, 'language_code', 'en') } if hasattr(response, 'timestamps'): result["timestamps"] = response.timestamps if hasattr(response, 'diarize_output') and response.diarize_output: result["diarize_output"] = response.diarize_output return result else: last_error = "No transcription was returned from the API" logger.error(f"No transcription returned from API with model {try_model}") break except Exception as api_error: error_msg = str(api_error) logger.error(f"Error with model {try_model}: {error_msg}") last_error = error_msg error_result = handle_api_error(error_msg, "transcription", retry_count, max_retries) if error_result is not None: if retry_count == max_retries: break else: return {"error": error_result} retry_count += 1 if "HTTP 500" in last_error: logger.error(f"All transcription attempts failed with HTTP 500: {last_error}") return {"error": f"Server error during transcription. This might be a temporary issue with the Whissle API. Please try again later or contact Whissle support. Error: {last_error}"} else: logger.error(f"All transcription attempts failed: {last_error}") return {"error": f"Failed to transcribe audio: {last_error}"} except Exception as e: logger.error(f"Unexpected error during transcription: {str(e)}") return {"error": f"Failed to transcribe audio: {str(e)}"}
• whissle_mcp/server.py:88-106 (registration)

  The @mcp.tool decorator registers the speech_to_text tool with the FastMCP server and defines its description, input parameters schema, and usage instructions.
  @mcp.tool( description="""Convert speech to text with a given model and save the output text file to a given directory. Directory is optional, if not provided, the output file will be saved to $HOME/Desktop. ⚠️ COST WARNING: This tool makes an API call to Whissle which may incur costs. Only use when explicitly requested by the user. Args: audio_file_path (str): Path to the audio file to transcribe model_name (str, optional): The name of the ASR model to use. Defaults to "en-NER" timestamps (bool, optional): Whether to include word timestamps boosted_lm_words (List[str], optional): Words to boost in recognition boosted_lm_score (int, optional): Score for boosted words (0-100) output_directory (str, optional): Directory where files should be saved. Defaults to $HOME/Desktop if not provided. Returns: TextContent with the transcription and path to the output file. """ )
• whissle_mcp/server.py:51-86 (helper)

  Helper function used by the speech_to_text handler to manage API errors, implement retries for HTTP 500 errors with exponential backoff, and generate user-friendly error messages for various HTTP 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}")