agent-voice-mcp-minus

Versión mejorada de agent-voice-mcp · Servicio local de anuncios por voz MCP que proporciona capacidad de locución del progreso de tareas para asistentes de programación con IA (Trae / Claude Desktop / Cursor, etc.), profundamente adaptado al gran modelo de síntesis de voz 豆包 de 火山引擎 (seed-tts).

Este proyecto es un fork de al96169/agent-voice-mcp (autor Antonio Liang, licencia MIT), sobre el que se han realizado numerosos ajustes probados en entornos reales para la interfaz v3 de 火山引擎 y casos de uso reales. La versión original es el núcleo; este proyecto es el núcleo + mejoras prácticas. Todas las mejoras pueden desactivarse mediante interruptores de configuración para volver a un comportamiento cercano al original.

Características mejoradas (frente a la versión original 1.2.0)

1. Instalación

Requisitos previos

• Node.js ≥ 18 (descargar)

• Windows (la síntesis en la nube es multiplataforma; el respaldo SAPI y el pitido de aviso son exclusivos de Windows; en otras plataformas se degradan automáticamente)

• Cuenta de 火山引擎 (se requiere activar el servicio de gran modelo de síntesis de voz; ver segundo paso)

Paso 1: Configurar el cliente MCP

Opción A · Ejecutar directamente con npx (recomendado, sin clonar)

Añade lo siguiente a la configuración del cliente MCP (en Trae es .trae/mcp.json en el directorio del proyecto; en Claude Desktop es claude_desktop_config.json; en Cursor es .cursor/mcp.json):

{
  "mcpServers": {
    "agent-voice": {
      "command": "npx",
      "args": ["-y", "github:doer1296/agent-voice-mcp-minus"]
    }
  }
}

Opción B · Clonar el repositorio y ejecutar localmente (recomendado para quienes necesitan modificar el código)

git clone https://github.com/doer1296/agent-voice-mcp-minus.git
cd agent-voice-mcp-minus
npm install

Cambia la configuración MCP a conexión directa con node (arranca más rápido y no se ve afectado por el registro npm):

{
  "mcpServers": {
    "agent-voice": {
      "command": "node",
      "args": ["D:/your/path/agent-voice-mcp-minus/dist/index.js"]
    }
  }
}

Tras configurar, reinicia el cliente / abre una nueva sesión. Cuando el servicio MCP se inicie, anunciará «servicio agent-voice iniciado» para indicar que está listo.

Paso 2: Obtener credenciales de 火山引擎

1. Regístrate/inicia sesión en 火山引擎

2. En la consola busca «Tecnología de voz» → activa el servicio «Gran modelo de síntesis de voz» (los nuevos usuarios disponen de cuota gratuita)

3. En la página «Gestión de API Key», crea y obtén la X-Api-Key

4. Aviso: es necesario activar el recurso de modelo correspondiente a la voz utilizada (seed-tts-1.0 o seed-tts-2.0; ver Configuración del gran modelo)

Alternativa gratuita: la versión original incluye el motor Edge TTS (síntesis en línea gratuita de Microsoft, sin API Key, cientos de voces). Basta con establecer engine en "edge-tts" para usarlo; consulta el README original para más detalles.

Paso 3: Crear el archivo de configuración

Copia el config.example.json de este repositorio como:

Windows: C:\Users\<你的用户名>\.agent-voice\config.json
macOS / Linux: ~/.agent-voice/config.json

A continuación, sustituye el campo apiKey por tu X-Api-Key (elige una de las dos opciones):

• Texto plano directo: "apiKey": "你的key"

• Referencia a variable de entorno (recomendado): mantén "${VOLCANO_API_KEY}" y luego define la variable de entorno del sistema VOLCANO_API_KEY=你的key (el archivo de configuración admite la sintaxis ${任意环境变量名} para evitar que la key quede en claro en el disco)

2. Cómo invocarlo (uso desde el agente)

El servicio MCP registra la herramienta speak; el agente puede llamarla para anunciar por voz:

Recomendado: combina con las reglas del proyecto para que el agente anuncie automáticamente el ciclo de vida de las tareas. En .trae/rules/project_rules.md de Trae (o en CLAUDE.md de Claude) añade:

在每次任务中，调用 agent-voice MCP 进行语音播报：
1. 任务开始时 — scene="task_start"
2. 每个子任务完成时 — scene="milestone"
3. 任务全部完成时 — scene="task_complete"
4. 遇到错误时 — scene="task_error"
5. 需要用户确认时 — scene="need_interaction"

Ejemplo de invocación:

speak(text="开始执行任务：重构登录模块", scene="task_start", emotion="calm")
speak(text="任务完成，测试全部通过", scene="task_complete", emotion="happy")

Otras herramientas: stop (detiene el anuncio actual y vacía la cola), get_voices (lista las voces disponibles), get_roles (lista los roles configurados).

3. Cómo configurar el gran modelo (selección de modelo)

En config.json, cloud.resourceId determina el gran modelo de síntesis de voz utilizado:

⚠️ La voz y la versión del modelo deben coincidir: si se usa la voz _moon_bigtts con seed-tts-2.0 (o al revés), se producirá un error HTTP 403 de recurso no autorizado. Al cambiar de modelo, recuerda cambiar también el ID de voz y activar el servicio de modelo correspondiente en la consola de 火山引擎.

Sugerencias de elección: 1.0 es estable, con voces variadas y documentación madura; 2.0 admite nuevas capacidades como la clonación de voz. Todas las optimizaciones de este proyecto se han probado sobre 1.0.

4. Cómo cambiar la voz

Modifica cloud.voice en config.json (así como el campo voice de cada configuración de escena) y asegúrate de que coincide con la versión de resourceId:

seed-tts-1.0 示例：
  zh_female_daimengchuanmei_moon_bigtts   呆萌川妹（甜美女声，本项目默认）
  zh_female_qingxinnvsheng_mars_bigtts    清新女声

seed-tts-2.0 示例：
  zh_female_vv_uranus_bigtts              温柔女声
  zh_male_*.uranus_bigtts                 男声系列

La lista completa de voces está en la documentación de la biblioteca de voces de 火山引擎.

5. Cómo ajustar volumen / velocidad

Volumen volume (por defecto 1.3):

• Relación de mapeo: loudness_rate = (volume − 1) × 100, es decir, 1.0 = sonoridad original, 1.3 = +30 % (ganancia RMS medida de aproximadamente +29 %, casi lineal)

• Rango de valores recomendado: 0.5 – 2.0; 2.0 = +100 % (límite del servidor)

• El valor global por defecto está en el nivel superior volume; cada escena puede sobrescribirlo (scenes.*.volume)

Velocidad rate (por defecto 200):

• Relación de mapeo: speech_rate = (rate / 200 − 1) × 100, es decir, 200 = velocidad original, 220 = +10 %, 180 = −10 %

• Gradiente predeterminado por escena (recomendado según pruebas de este proyecto): inicio 190 → interacción 200 → hito/error 210 → finalización 220

6. Silencio inicial para Bluetooth (importante)

cloud.leadingSilence (por defecto 1500, es decir, 1,5 segundos):

Este parámetro está diseñado para usuarios de auriculares Bluetooth. El enlace de audio Bluetooth tarda entre 1 y 2 segundos en establecerse; al iniciar el anuncio, los auriculares suelen estar aún sin conectar, por lo que la primera palabra queda tapada por el ruido de conexión. Este parámetro inserta un silencio total de los milisegundos indicados al principio de los datos de voz, de modo que la voz solo comienza cuando el enlace Bluetooth está listo.

• Usuarios de auriculares Bluetooth: mantén 1500 (si aún se pierde la primera palabra, puedes aumentarlo a 2000)

• Usuarios de auriculares con cable / altavoces: cámbialo a 0; el anuncio será más compacto

• El tono de aviso previo al anuncio también es una salida de audio que activa el enlace Bluetooth con antelación, funcionando en sinergia con este parámetro

7. Tabla completa de parámetros

Canal de anuncio de respaldo (watcher, opcional)

watcher/voice-watcher.mjs es un listener residente que no depende de la conexión MCP: sondea ~/.trae-cn/work/.voice-reader/pending.txt y, al detectar contenido marcado, reproduce el anuncio usando el mismo motor en la nube que el servicio principal (configuración, voz y volumen provienen en tiempo real de la misma fuente; si falla la nube, también recurre a SAPI).

Uso: cuando las herramientas MCP no están disponibles en la sesión del agente (por ejemplo, cambio de modelo o caída del servicio MCP), aún se puede escribir una marca en ese archivo para activar el anuncio, formando un canal de respaldo:

[VOICE_READER_START:success]
要播报的文本
[VOICE_READER_END]

Los tipos admitidos son info / success / error / warning, que se asignan respectivamente a los parámetros de escena task_start / task_complete / task_error / need_interaction.

Cómo activarlo: en config.json define "watcher": { "enabled": true }. Al iniciar, el servicio MCP principal lo levanta automáticamente como subproceso y lo recoge al salir (guardia de instancia única TCP 47613; con varias sesiones solo se ejecuta una instancia). También puede ejecutarse de forma independiente: node watcher/voice-watcher.mjs.

Rutas portables: todas las rutas se derivan de forma relativa o se construyen con os.homedir(), sin rutas absolutas fijas. Las variables de entorno pueden sobrescribirlas: AGENT_VOICE_CONFIG (ruta del archivo de configuración), AGENT_VOICE_PENDING_DIR (directorio donde se encuentra pending.txt; por defecto ~/.trae-cn/work/.voice-reader, adaptable a otros clientes MCP).

Notas

1. La configuración se carga una vez al arrancar MCP. Tras modificar config.json, hay que reiniciar el cliente / abrir una nueva sesión para que surta efecto (no se vuelve a leer en cada anuncio).

2. Frecuencia de muestreo y canales: las pruebas muestran que el ancho de banda real de esta voz es ≤ 12kHz; solicitar 32/44.1/48kHz solo produce un sobremuestreo por interpolación, sin ganancia de calidad (verificado mediante análisis de bandas de frecuencia FFT de múltiples ventanas). La API solo admite mono; al reproducir, el sistema mezcla automáticamente a ambos oídos. Mantener 24000 es óptimo.

3. La emoción está implementada en el cliente: la interfaz v3 de seed-tts-1.0 no admite el parámetro emotion en el servidor (en las pruebas se envió y se ignoró silenciosamente). Este proyecto expresa seis emociones mediante la combinación de tono (pitch ±12) + desplazamientos de velocidad/volumen; emotionIntensity controla la intensidad.

4. No actives SSML: la etiqueta de pausa <break> de SSML, probada con la interfaz de streaming 1.0 + v3, trunca el audio (solo sintetiza la primera frase). Las pausas en textos largos ya están implementadas con la solución del cliente; no se necesita SSML.

5. Cuota y facturación: 火山引擎 factura por caracteres; se recomienda que los mensajes de anuncio de tareas sean breves (el truncado predeterminado de 200 caracteres de este proyecto se debe en parte a esto). Cuando se agota la cuota, se degrada automáticamente a la voz local SAPI (el timbre cambia, es normal).

6. Dependencia de Windows: el tono de aviso usa System.Console::Beep y la reproducción de voz usa PowerShell Media.SoundPlayer; ambas vienen con Windows, pero si PowerShell está deshabilitado por directiva de grupo, las funciones correspondientes se degradan.

7. Directorio de salida: el audio sintetizado se escribe en el directorio temporal del sistema y se limpia automáticamente después de reproducirse; no deja residuos.

Agradecimientos

• agent-voice-mcp y su autor original, Antonio Liang — este proyecto es una mejora basada en su código de código abierto MIT; el diseño central, como los roles de voz y la arquitectura multi-motor, proviene de la versión original

• 火山引擎 · Gran modelo de síntesis de voz 豆包

Licencia

MIT (hereda el protocolo del proyecto original y conserva la atribución al autor original)