Synthesizer V Studio 2 MCP Server (mcp-svstudio)

Un servidor Model Context Protocol (MCP) de grado de producción para Dreamtonics Synthesizer V Studio 2 Pro, que permite a agentes de IA generativa y LLM manipular de forma segura, estructural y efectiva notas, letras, fonemas, atributos vocales, parámetros y el transporte de reproducción mediante la API oficial de scripting de Dreamtonics.

Descripción general de la arquitectura

Synthesizer V Studio 2 Pro ejecuta scripts dentro de un entorno embebido de Lua 5.4 / Duktape JS sin sockets de red externos. Para lograr alto rendimiento, baja latencia y cero dependencias de bibliotecas C, este servidor MCP utiliza un Protocolo IPC de buzón de archivos atómico:

+--------------------------------------+
|       LLM / MCP Client               |
|   (Antigravity / Claude / Cursor)    |
+------------------+-------------------+
                   | JSON-RPC over Stdio
                   v
+--------------------------------------+
|       Node.js MCP Server             |
|  - Tool Schema & Validation (Zod)    |
|  - Stable Note Locator Resolver      |
|  - Safe Diff & Dry Run Engine        |
|  - Mailbox IPC Client                |
+------------------+-------------------+
                   | Atomic Mailbox IPC (.req / .res)
                   | Live Heartbeat Monitor (heartbeat.json)
                   v
+--------------------------------------+
|  Synthesizer V Studio 2 Pro (Lua 5.4)|
|  `StartMCPServerRequestHandler.lua`  |
|  - Non-blocking SV:setTimeout loop   |
|  - Dreamtonics Official Scripting API|
|  - Automatic Snapshot Rollback & Undo|
+--------------------------------------+

Aspectos destacados del protocolo IPC

• Renombrados atómicos de archivos: Escribe en <id>.tmp y renombra atómicamente a <id>.req / <id>.res para evitar condiciones de carrera y lecturas parciales de archivos.

• IDs de solicitud únicos: Garantiza el emparejamiento solicitud-respuesta incluso durante comandos secuenciales rápidos.

• Latido instantáneo de actividad: El script Lua actualiza heartbeat.json cada 500 ms. El servidor MCP comprueba la frescura del latido e informa inmediatamente del estado sin conexión (<50 ms) en lugar de quedarse colgado en tiempos de espera.

• Recolección automática de basura: Limpia automáticamente archivos temporales obsoletos de más de 60 segundos al inicio y durante el sondeo.

Related MCP server: aviutl2-mcp

Instalación y configuración

Requisitos previos

• Node.js (v18 o superior; probado en v22 y v26)

• Synthesizer V Studio Pro (Versión 2.0 o 2.1+)

1. Compilar el servidor MCP

git clone https://github.com/shotarokawade/SV-MCP.git
cd SV-MCP
npm install
npm run build

2. Instalar los scripts Lua en Synthesizer V Studio

Ejecute el instalador automatizado:

npm run install-scripts

O copie manualmente los archivos de sv-scripts/ a su carpeta de scripts de Synthesizer V Studio:

• macOS: ~/Library/Application Support/Dreamtonics/Synthesizer V Studio 2/scripts/MCP/

• Windows: %APPDATA%\Dreamtonics\Synthesizer V Studio 2\scripts\MCP\

• Linux: ~/.local/share/Dreamtonics/Synthesizer V Studio 2/scripts/MCP/

3. Iniciar el manejador del servidor en Synthesizer V Studio

1. Inicie Synthesizer V Studio 2 Pro.

2. Abra o cree un proyecto con pistas vocales.

3. En la barra de menú superior, seleccione: Scripts > MCP > Start MCP Server Request Handler

4. El manejador en segundo plano ahora está en ejecución y responde. (Para detenerlo, seleccione Scripts > MCP > Stop MCP Server Request Handler).

Configuración del cliente MCP

Antigravity (~/.gemini/config/mcp_config.json o configuración del proyecto)

{
  "mcpServers": {
    "synthv": {
      "command": "node",
      "args": ["/absolute/path/to/SV-MCP/build/index.js"],
      "env": {
        "MCP_SVSTUDIO_IPC_DIR": "/absolute/path/to/.mcp-svstudio/ipc"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "synthv": {
      "command": "node",
      "args": ["/path/to/SV-MCP/build/index.js"]
    }
  }
}

Referencia de herramientas MCP

Manipulación de fonemas y corrección de letras alemanas multisilábicas

El problema

Al importar MusicXML desde MuseScore a Synthesizer V Studio, las palabras alemanas multisilábicas divididas entre notas (por ejemplo, schö- y -ne) con syllabic=begin/end a menudo se fusionan con el texto de fonemas crudo en las letras:

• Nota 1 prevista: .sh er

• Nota 2 prevista: .n ax

• Resultado en SynthV si se coloca en las letras: .sh er.n ax (causando advertencias de pronunciación y errores fonéticos).

La solución: Inyección directa de fonemas mediante MCP

Usando este servidor MCP, el LLM establece letras y fonemas directamente mediante las API oficiales:

{
  "trackIndex": 0,
  "groupIndex": 0,
  "assignments": [
    { "noteIndex": 0, "phonemes": ".sh er" },
    { "noteIndex": 1, "phonemes": ".n ax" }
  ]
}

Verificación de pronunciación de ida y vuelta

1. Llame a set_phonemes para aplicar los fonemas objetivo.

2. Llame a get_computed_phonemes para volver a consultar el motor sintetizador interno de Synthesizer V.

3. Compare los fonemas calculados con la pronunciación esperada para verificar la coincidencia exacta.

Pipeline de integración con MuseScore MCP

[ MuseScore MCP ]
       │ 1. Extract note pitches, onset blicks, measure positions, and lyric syllables
       ▼
[ LLM Agent ]
       │ 2. Perform German grapheme-to-phoneme (G2P) conversion to Synthesizer V phonemes
       │    (e.g., "Freude" -> [".f r oy", "d ax"])
       ▼
[ Synthesizer V MCP ]
       │ 3. `find_notes` or `get_notes` matching onset and measure range
       │ 4. `batch_edit` with `dry_run: true` to inspect diff
       │ 5. `batch_edit` with `dry_run: false` to apply notes and `set_phonemes`
       │ 6. `get_computed_phonemes` to verify synthesis pronunciation

Garantías de seguridad, ejecución en seco y reversión

1. dry_run: true: Todas las herramientas de mutación soportan dry_run: true. El servidor devuelve los cambios previstos y la diferencia sin modificar el estado del proyecto.

2. Deshacer en un solo paso dentro de la aplicación (project.newUndoRecord()): Cada operación MCP que muta registra un registro de deshacer del proyecto. El usuario puede pulsar Cmd+Z / Ctrl+Z dentro de Synthesizer V Studio para revertir instantáneamente toda la operación.

3. Reversión de transacción en lote: Si se produce un error durante batch_edit, el script captura el estado anterior a la mutación y revierte automáticamente los elementos modificados antes de devolver el error.

4. Validación de límites y rangos:

   • Tono MIDI: 0 - 127

   • Volumen: -48 dB a +12 dB

   • Tensión / Respiración / Género: -1.0 a +1.0

   • Sonoridad: 0.0 a +1.0

   • Desviación de tono: -1200 a +1200 cents

   • Modo vocal: 0 a 150

Referencias y cumplimiento de la API oficial

• Manual oficial de scripting: https://resource.dreamtonics.com/scripting/index.html

• APIs oficiales clave utilizadas:

  • Note.getPhonemes() / Note.setPhonemes(phonemes)

  • SV.getPhonemesForGroup(groupRef)

  • SV.getComputedAttributesForGroup(groupRef) (SynthV 2.1.1+)

  • Note.getAttributes() / Note.setAttributes(attributes)

  • NoteGroupReference.getVoice() / NoteGroupReference.setVoice(voice)

  • NoteGroup.getParameter(name) / Automation

  • PlaybackControl (play, pause, stop, seek, loop, getPlayhead)

  • Project.newUndoRecord()

Licencia

Licencia MIT.