Servidor MCP Whissle

Un servidor basado en Python que proporciona acceso a los puntos finales 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 puntos finales de la API de Whissle, lo que puede generar costos.
Cada herramienta que realiza una llamada API está marcada con una advertencia de costo
Por favor, siga estas pautas:
1. Utilice las herramientas únicamente cuando el usuario lo solicite explícitamente
2. Para las herramientas que procesan audio, tenga en cuenta 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 elevados.
4. Las herramientas sin advertencias de costo en su descripción son de uso gratuito ya que solo leen datos existentes

Prerrequisitos

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

Instalación

Clonar el repositorio:
git clone <repository-url> cd whissle_mcp
Crear y activar un entorno virtual:
python -m venv venv source venv/bin/activate # On Windows, use: venv\Scripts\activate
Instalar los paquetes necesarios:
pip install -e .
Configurar 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 envíes tu token al repositorio. El archivo .env está incluido en .gitignore para evitar envíos accidentales.
Configurar la integración de Claude: copie claude_config.example.json en 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 (obligatorio)
- Esta es una credencial confidencial que nunca debe compartirse ni entregarse al control de versiones.
- Comuníquese con su administrador para obtener un token válido
- Guárdelo de forma segura en su archivo .env local
WHISSLE_MCP_BASE_PATH : Directorio base para operaciones de archivos (opcional, el valor predeterminado es el escritorio del usuario)

Formatos de audio compatibles

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

Convierte voz en texto usando la API 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 del habla

Convierte voz en 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

Traducir texto de un idioma a otro.

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

4. Resumen del texto

Resumir 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. Enumere los modelos ASR

Enumere todos los modelos ASR disponibles y sus capacidades.

response = list_asr_models()

Formato de respuesta

Conversión de 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 falla
Validación de archivos (existencia, tamaño, formato)
Comprobaciones de autenticación

Tipos de errores comunes:

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

Ejecución del servidor

Iniciar el servidor:
mcp serve
El servidor estará disponible en el puerto MCP predeterminado (normalmente 8000)

Pruebas

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

python test_whissle.py

El script de prueba hará lo siguiente:

Comprobar el token de autenticación
Pruebe todas las herramientas disponibles
Proporcionar resultados detallados de cada operación
Manejar los errores con elegancia

Apoyo

Para problemas o preguntas, por favor:

Consulte 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
Comuníquese con el soporte de Whissle para problemas relacionados con la API

Licencia

[Agregue la información de su licencia aquí]

Whissle MCP Server

Integrations