Synthesizer V Studio 2 MCP Server (mcp-svstudio)

Ein produktionsreifer Model Context Protocol (MCP)-Server für Dreamtonics Synthesizer V Studio 2 Pro, der es generativen KI- und LLM-Agenten ermöglicht, Noten, Texte, Phoneme, Gesangsattribute, Parameter und die Wiedergabesteuerung sicher, strukturiert und effektiv über die offizielle Dreamtonics-Scripting-API zu manipulieren.

Architekturüberblick

Synthesizer V Studio 2 Pro führt Skripte in einer eingebetteten Lua-5.4-/Duktape-JS-Umgebung ohne externe Netzwerk-Sockets aus. Um hohe Leistung, geringe Latenz und null C-Bibliotheks-Abhängigkeiten zu erreichen, verwendet dieser MCP-Server ein atomares Datei-Mailbox-IPC-Protokoll:

+--------------------------------------+
|       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|
+--------------------------------------+

Höhepunkte des IPC-Protokolls

• Atomare Dateiumbenennungen: Schreibt in <id>.tmp und benennt atomar in <id>.req / <id>.res um, um Race Conditions und partielle Dateilesevorgänge zu verhindern.

• Eindeutige Anforderungs-IDs: Garantiert die Zuordnung von Anforderung und Antwort auch bei schnellen sequenziellen Befehlen.

• Sofortiger Heartbeat-Liveness: Das Lua-Skript aktualiziert heartbeat.json alle 500 ms. Der MCP-Server prüft die Heartbeat-Frische und meldet den Offline-Status sofort (<50 ms), anstatt bei Zeitüberschreitungen hängen zu bleiben.

• Automatische Speicherbereinigung: Bereinigt beim Start und während des Abrufens automatisch veraltete temporäre Dateien, die älter als 60 Sekunden sind.

Related MCP server: aviutl2-mcp

Installation & Einrichtung

Voraussetzungen

• Node.js (v18 oder höher; getestet mit v22 & v26)

• Synthesizer V Studio Pro (Version 2.0 oder 2.1+)

1. MCP-Server erstellen

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

2. Lua-Skripte in Synthesizer V Studio installieren

Führen Sie den automatisierten Installer aus:

npm run install-scripts

Oder kopieren Sie die Dateien in sv-scripts/ manuell in Ihren Synthesizer-V-Studio-Skriptordner:

• 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. Server-Handler in Synthesizer V Studio starten

1. Starten Sie Synthesizer V Studio 2 Pro.

2. Öffnen oder erstellen Sie ein Projekt mit Gesangsspuren.

3. Wählen Sie in der oberen Menüleiste: Skripte > MCP > MCP-Server-Anfrage-Handler starten

4. Der Hintergrund-Handler läuft nun und ist betriebsbereit. (Zum Beenden wählen Sie Skripte > MCP > MCP-Server-Anfrage-Handler stoppen).

MCP-Client-Konfiguration

Antigravity (~/.gemini/config/mcp_config.json oder Projektkonfiguration)

{
  "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"]
    }
  }
}

MCP-Tool-Referenz

Phonem-Manipulation & deutscher Mehrsilben-Text-Fix

Das Problem

Beim Importieren von MusicXML aus MuseScore in Synthesizer V Studio werden deutsche mehrsilbige Wörter, die auf mehrere Noten aufgeteilt sind (z. B. schö- und -ne) mit syllabic=begin/end, oft mit rohem Phonemtext im Text zusammengeführt:

• Beabsichtigte Note 1: .sh er

• Beabsichtigte Note 2: .n ax

• Ergebnis in SynthV, wenn in den Text eingefügt: .sh er.n ax (verursacht Aussprachewarnungen und phonetische Fehler).

Die Lösung: Direkte Phonem-Injektion über MCP

Mit diesem MCP-Server setzt das LLM Text und Phoneme direkt über offizielle APIs:

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

Round-Trip-Ausspracheüberprüfung

1. Rufen Sie set_phonemes auf, um die Zielphoneme anzuwenden.

2. Rufen Sie get_computed_phonemes auf, um die internen Synthesizer-Ergebnisse von Synthesizer V erneut abzufragen.

3. Vergleichen Sie die berechneten Phoneme mit der erwarteten Aussprache, um eine exakte Übereinstimmung zu überprüfen.

MuseScore-MCP-Integrationspipeline

[ 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

Sicherheit, Testlauf und Rollback-Garantien

1. dry_run: true: Alle Änderungswerkzeuge unterstützen dry_run: true. Der Server gibt die vorhergesagten Änderungen und die Differenz zurück, ohne den Projektstatus zu ändern.

2. Rückgängig in einem Schritt in der App (project.newUndoRecord()): Jeder ändernde MCP-Vorgang registriert einen Projekt-Rückgängig-Datensatz. Der Benutzer kann in Synthesizer V Studio Cmd+Z / Ctrl+Z drücken, um den gesamten Vorgang sofort rückgängig zu machen.

3. Transaktions-Rollback im Stapel: Wenn während batch_edit ein Fehler auftritt, erfasst das Skript den Zustand vor der Änderung und macht geänderte Elemente automatisch rückgängig, bevor der Fehler zurückgegeben wird.

4. Grenz- und Bereichsvalidierung:

   • MIDI-Tonhöhe: 0 - 127

   • Lautstärke: -48 dB bis +12 dB

   • Spannung / Atmigkeit / Geschlecht: -1.0 bis +1.0

   • Stimmhaftigkeit: 0.0 bis +1.0

   • Tonhöhenabweichung: -1200 bis +1200 Cent

   • Gesangsmodus: 0 bis 150

Referenzen & Einhaltung der offiziellen API

• Offizielles Skripthandbuch: https://resource.dreamtonics.com/scripting/index.html

• Wichtige offizielle APIs:

  • 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()

Lizenz

MIT-Lizenz.