Whissle MCP Server

Accede a la API de Whissle para conversión de voz a texto, diarización, traducción y resumen de texto.

Documentación

Servidor MCP de Whissle

Un servidor basado en Python que proporciona acceso a los endpoints de la API de Whissle para conversión de voz a texto, diarización, traducción y resumen de texto.

⚠️ Notas Importantes

Este servidor proporciona acceso a los endpoints de la API de Whissle, lo que puede generar costos
Cada herramienta que realiza una llamada a la API está marcada con una advertencia de costo
Por favor, siga estas pautas:
1. Utilice las herramientas solo cuando el usuario lo solicite explícitamente
2. Para las herramientas que procesan audio, considere la duración del audio, ya que afecta los costos
3. Algunas operaciones como la traducción o el resumen pueden tener costos más altos
4. Las herramientas sin advertencias de costo en su descripción son gratuitas, ya que solo leen datos existentes

Requisitos Previos

Python 3.8 o superior
pip (instalador de paquetes de Python)
Un token de autenticación de la API de Whissle

Instalación

Clone el repositorio:

git clone <repository-url>
cd whissle_mcp

Cree y active un entorno virtual:

python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

Instale los paquetes requeridos:
```
pip install -e .
```
Configure las variables de entorno: Cree un archivo .env en la raíz del proyecto con el siguiente contenido:
```
WHISSLE_AUTH_TOKEN=insert_auth_token_here  # Replace with your actual Whissle API token
WHISSLE_MCP_BASE_PATH=/path/to/your/base/directory
```
⚠️ Importante: Nunca confirme su token real en el repositorio. El archivo .env está incluido en .gitignore para evitar confirmaciones accidentales.

Configure la integración con Claude: Copie claude_config.example.json a claude_config.json y actualice las rutas:

{
    "mcpServers": {
        "Whissle": {
            "command": "/path/to/your/venv/bin/python",
            "args": [
                "/path/to/whissle_mcp/server.py"
            ],
            "env": {
                "WHISSLE_AUTH_TOKEN": "insert_auth_token_here"
            }
        }
    }
}

Reemplace /path/to/your/venv/bin/python con la ruta real a su intérprete de Python en el entorno virtual
Reemplace /path/to/whissle_mcp/server.py con la ruta real a su archivo server.py

Configuración

Variables de Entorno

WHISSLE_AUTH_TOKEN: Su token de autenticación de la API de Whissle (requerido)
- Esta es una credencial sensible que nunca debe compartirse ni confirmarse en el control de versiones
- Contacte a su administrador para obtener un token válido
- Almacénelo de forma segura en su archivo local .env
WHISSLE_MCP_BASE_PATH: Directorio base para operaciones de archivos (opcional, por defecto es el Escritorio del usuario)

Formatos de Audio Soportados

El servidor admite los siguientes formatos de audio:

WAV (.wav)
MP3 (.mp3)
OGG (.ogg)
FLAC (.flac)
M4A (.m4a)

Límites de Tamaño de Archivo

Tamaño máximo de archivo: 25 MB
Los archivos que superen este límite serán rechazados

Herramientas Disponibles

1. Voz a Texto

Convierta voz a texto utilizando la API de Whissle.

response = speech_to_text(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # Default model
    timestamps=True,      # Include word timestamps
    boosted_lm_words=["specific", "terms"],  # Words to boost in recognition
    boosted_lm_score=80   # Score for boosted words (0-100)
)

2. Diarización de Voz

Convierta voz a texto con identificación del hablante.

response = diarize_speech(
    audio_file_path="path/to/audio.wav",
    model_name="en-NER",  # Default model
    max_speakers=2,       # Maximum number of speakers to identify
    boosted_lm_words=["specific", "terms"],
    boosted_lm_score=80
)

3. Traducción de Texto

Traduzca texto de un idioma a otro.

response = translate_text(
    text="Hello, world!",
    source_language="en",
    target_language="es"
)

4. Resumen de Texto

Resuma texto utilizando un modelo LLM.

response = summarize_text(
    content="Long text to summarize...",
    model_name="openai",  # Default model
    instruction="Provide a brief summary"  # Optional
)

5. Listar Modelos ASR

Liste todos los modelos ASR disponibles y sus capacidades.

response = list_asr_models()

Formato de Respuesta

Voz a Texto y Diarización

{
    "transcript": "The transcribed text",
    "duration_seconds": 10.5,
    "language_code": "en",
    "timestamps": [
        {
            "word": "The",
            "startTime": 0,
            "endTime": 100,
            "confidence": 0.95
        }
    ],
    "diarize_output": [
        {
            "text": "The transcribed text",
            "speaker_id": 1,
            "start_timestamp": 0,
            "end_timestamp": 10.5
        }
    ]
}

Traducción

{
    "type": "text",
    "text": "Translation:\nTranslated text here"
}

Resumen

{
    "type": "text",
    "text": "Summary:\nSummarized text here"
}

Respuesta de Error

{
    "error": "Error message here"
}

Manejo de Errores

El servidor incluye un manejo robusto de errores con:

Reintentos automáticos para errores HTTP 500
Mensajes de error detallados para diferentes escenarios de fallo
Validación de archivos (existencia, tamaño, formato)
Verificaciones de autenticación

Tipos de error comunes:

HTTP 500: Error del servidor (con mecanismo de reintento)
HTTP 413: Archivo demasiado grande
HTTP 415: Formato de archivo no soportado
HTTP 401/403: Error de autenticación

Ejecución del Servidor

Inicie el servidor:
```
mcp serve
```
El servidor estará disponible en el puerto MCP predeterminado (generalmente 8000)

Pruebas

Se proporciona un script de prueba para verificar la funcionalidad de todas las herramientas:

python test_whissle.py

El script de prueba:

Verificará el token de autenticación
Probará todas las herramientas disponibles
Proporcionará una salida detallada de cada operación
Manejará los errores de manera elegante

Soporte

Para problemas o preguntas, por favor:

Revise los mensajes de error para obtener detalles específicos
Verifique su token de autenticación
Asegúrese de que sus archivos de audio cumplan con los requisitos
Contacte al soporte de Whissle para problemas relacionados con la API

Licencia

[Añada aquí su información de licencia]