Servidor MCP de generación de voz similar a IA

Una implementación de servidor para la API de generación de voz Resemble AI que se integra con Claude y Cursor utilizando el Protocolo de contexto de modelo (MCP).

Características

• Genere audio de voz a partir de texto usando las voces de Resemble AI
• Lista de modelos de voz disponibles
• Devuelve el audio como un archivo local o una cadena codificada en base64
• Múltiples métodos de conexión:
  • Transporte SSE : eventos enviados por el servidor basados en la red (predeterminado)
  • Transporte StdIO : comunicación directa del proceso

Instrucciones de configuración

Prerrequisitos

• Python 3.10 o superior
• Clave API de Resemble AI (regístrese en Resemble AI )

Configuración del entorno

Opción 1: Usar Conda (recomendado)

Opción 2: Uso del entorno virtual

Configuración

Establezca su clave API de Resemble AI como una variable de entorno:

Alternativamente, cree un archivo .env en la raíz del proyecto con el siguiente contenido:

Ejecución del servidor

Uso del script de ejecución (recomendado)

Elija su implementación preferida:

Usando la CLI directamente

Conexión a Claude Desktop

Conexión de transporte SSE

Cree un archivo claude_desktop_config.json :

Conexión de transporte StdIO

Cree un archivo claude_desktop_config.json :

Conectando al cursor

Conexión de transporte SSE

1. Vaya a Configuración → IA → Servidores MCP
2. Haga clic en "Agregar servidor"
3. Seleccione “SSE” como tipo de conexión
4. Establezca la URL en: http://localhost:8083/sse

Conexión de transporte StdIO

1. Vaya a Configuración → IA → Servidores MCP
2. Haga clic en "Agregar servidor"
3. Seleccione “Subproceso” como tipo de conexión
4. Establezca el comando en: python -m src.cli --implementation stdio
5. Opcionalmente agregue variables de entorno:
   • RESEMBLE_API_KEY : Su clave API de Resemble AI

Herramientas disponibles

list_voices

Enumera los modelos de voz disponibles de Resemble AI.

generate_tts

Genera audio de voz a partir de texto.

Parámetros:

• text : El texto a convertir a voz
• voice_id : ID de la voz a utilizar
• return_type : Cómo devolver el audio: 'archivo' o 'base64' (opcional, predeterminado: 'archivo')
• output_filename : Nombre del archivo de salida sin extensión (opcional)

Detalles de implementación

El proyecto incluye varias implementaciones:

• src/resemble_mcp_server.py : utiliza el SDK de MCP con transporte SSE
• src/resemble_stdio_server.py : utiliza el transporte StdIO para la comunicación directa del proceso
• src/resemble_http_server.py : implementación HTTP con SSE (respaldo)
• src/resemble_ai_server.py : Implementación directa de API
• src/resemble_ai_sdk_server.py : Implementación utilizando el SDK oficial de Resemble

Solución de problemas

Errores de importación del SDK de MCP

Si encuentra problemas al importar el SDK de MCP, el servidor recurrirá automáticamente a la implementación HTTP con transporte SSE.

Problemas de conexión

Si Claude o Cursor no pueden conectarse al servidor:

1. Compruebe que el servidor esté en funcionamiento
2. Verifique que la URL esté configurada correctamente
3. Comprueba que tu clave API sea válida
4. Busque errores en los registros del servidor

Transporte StdIO frente a SSE

• Utilice SSE Transport cuando desee ejecutar el servidor por separado o en una máquina diferente
• Utilice StdIO Transport cuando desee que Claude/Cursor administre el proceso del servidor por usted

Ejemplos

Se pueden encontrar ejemplos de uso en el directorio examples/ .

📁 Estructura del repositorio

🚀 Configuración rápida

Se proporcionan dos scripts de configuración para facilitar la instalación:

Uso de Conda (recomendado)

Usando Python venv

Cualquiera de los dos scripts:

1. Crear un entorno de Python 3.10+
2. Instalar todas las dependencias necesarias
3. Configurar un archivo de plantilla .env
4. Crear el directorio de salida para archivos de audio

Instalación manual

Si prefiere configurarlo manualmente:

1. Cree un entorno Python 3.10+:
   # Using conda conda create -n resemble_mcp python=3.10 conda activate resemble_mcp # OR using venv (with Python 3.10+ already installed) python3.10 -m venv venv source venv/bin/activate
2. Instalar dependencias:
   pip install uvicorn fastapi python-dotenv requests pydantic httpx sse-starlette pip install git+https://github.com/modelcontextprotocol/python-sdk.git
3. Configure sus variables de entorno:
   cp .env.example .env
   Edite el archivo .env y agregue su clave API de Resemble AI:
   RESEMBLE_API_KEY=your_api_key_here
   Opcional: Personalice la configuración de salida de audio
   OUTPUT_DIR=./output AUDIO_FORMAT=mp3
4. Crear directorio de salida:
   mkdir -p output

🚀 Ejecución del servidor

Puede ejecutar el servidor utilizando nuestra nueva herramienta CLI que admite todas las implementaciones:

🔌 Integración con Cursor AI

El cursor puede interactuar con el servidor de generación de voz Resemble AI a través de la interfaz SSE:

1. En Cursor, vaya a Configuración → IA → Servidores MCP
2. Haga clic en "Agregar servidor" e ingrese la URL de SSE: http://localhost:8083/sse (ajuste el puerto si es necesario)
3. Guardar la configuración

🔌 Integración con Claude Desktop

1. Configurar el servidor MCP en la configuración de Claude Desktop:
   { "mcpServers": { "resemble-ai": { "command": "python", "args": ["-m", "src.cli", "--implementation", "mcp"], "env": { "RESEMBLE_API_KEY": "your_api_key_here" }, "disabled": false, "autoApprove": [] } } }

🛠️ Documentación de la herramienta

lista_voces

Enumera todos los modelos de voz disponibles de Resemble AI.

Parámetros: Ninguno

Devoluciones:

• voices : Lista de modelos de voz disponibles con identificaciones, nombres, géneros, idiomas, acentos y descripciones

generar_tts

Genera audio de voz a partir de texto.

Parámetros:

• text (cadena, obligatorio): El texto que se convertirá a voz
• voice_id (cadena, obligatoria): el ID de la voz a utilizar
• return_type (cadena, opcional): Cómo devolver el audio: 'archivo' o 'base64' (predeterminado: 'archivo')
• output_filename (cadena, opcional): nombre de archivo para la salida sin extensión (predeterminado: nombre generado automáticamente)

Devoluciones:

• success (booleano): si la operación fue exitosa
• message (cadena): Mensaje de estado
• audio_data (cadena, opcional): datos de audio codificados en Base64 (si return_type es 'base64')
• file_path (cadena, opcional): ruta al archivo de audio guardado (si return_type es 'file')

💬 Ejemplos de indicaciones

Una vez conectado a Cursor o Claude Desktop, puede usar indicaciones como:

Listado de voces disponibles:

Generando audio de voz:

⚠️ Solución de problemas

• Problemas con la versión de Python : El paquete MCP requiere Python 3.10 o posterior. Utilice los scripts de configuración proporcionados para crear el entorno correcto.
• Problemas de conexión a la API : Asegúrate de usar el punto de conexión de la API correcto. El punto de conexión de la API de Resemble AI es https://app.resemble.ai/api/v2/ .
• Errores de autenticación : verifique que su clave API sea correcta y no esté vencida.
• Proyectos faltantes : La API requiere al menos un proyecto en tu cuenta de Resemble. Crea un proyecto a través del panel de Resemble AI si es necesario.
• Errores de conexión de Cursor SSE : si Cursor no puede conectarse a través de SSE, asegúrese de lo siguiente:
  • El servidor se está ejecutando en el puerto especificado
  • Estás utilizando el punto final /sse correcto
  • Ningún firewall está bloqueando la conexión
  • Intente reiniciar tanto el servidor como el cursor

📚 Documentación adicional

Para obtener documentación más detallada, consulte los archivos en el directorio docs/ .

📄 Licencia

Instituto Tecnológico de Massachusetts (MIT)