Synthesizer V Studio 2 MCP Server (mcp-svstudio)

一个面向 Dreamtonics Synthesizer V Studio 2 Pro 的生产级 Model Context Protocol (MCP) 服务器，使生成式 AI 和 LLM 代理能够通过官方 Dreamtonics 脚本 API 安全、结构化且高效地操作音符、歌词、音素、歌声属性、参数和播放走带。

架构概述

Synthesizer V Studio 2 Pro 在嵌入式 Lua 5.4 / Duktape JS 环境中执行脚本，且没有外部网络套接字。为了实现高性能、低延迟和零 C 库依赖，此 MCP 服务器使用了一种原子文件邮箱 IPC 协议：

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

IPC 协议亮点

• 原子文件重命名：写入 <id>.tmp 并原子重命名为 <id>.req / <id>.res，以防止竞态条件和部分文件读取。

• 唯一请求 ID：即使在快速连续命令期间也能保证请求-响应配对。

• 即时心跳活性检测：Lua 脚本每 500ms 更新一次 heartbeat.json。MCP 服务器检查心跳的新鲜度，并立即报告离线状态（<50ms），而不是因超时而挂起。

• 自动垃圾回收：在启动时和轮询期间自动清理超过 60 秒的过期临时文件。

Related MCP server: aviutl2-mcp

安装与设置

前提条件

• Node.js（v18 或更高版本；已在 v22 和 v26 上测试）

• Synthesizer V Studio Pro（2.0 或 2.1+ 版本）

1. 构建 MCP 服务器

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

2. 将 Lua 脚本安装到 Synthesizer V Studio

运行自动安装程序：

npm run install-scripts

或者手动将 sv-scripts/ 中的文件复制到你的 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. 在 Synthesizer V Studio 中启动服务器处理器

1. 启动 Synthesizer V Studio 2 Pro。

2. 打开或创建一个包含歌声轨道的项目。

3. 在顶部菜单栏中，选择： Scripts > MCP > Start MCP Server Request Handler

4. 后台处理器现已运行并保持响应。（要停止它，请选择 Scripts > MCP > Stop MCP Server Request Handler）。

MCP 客户端配置

Antigravity（~/.gemini/config/mcp_config.json 或项目配置）

{
  "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 工具参考

音素操作与德语多音节歌词修复

问题

当从 MuseScore 将 MusicXML 导入 Synthesizer V Studio 时，带有 syllabic=begin/end 的跨音符拆分的德语多音节单词（例如 schö- 和 -ne）常常会与歌词中的原始音素文本合并：

• 预期音符 1：.sh er

• 预期音符 2：.n ax

• 如果放入歌词中，SynthV 中的结果：.sh er.n ax（导致发音警告和音素错误）。

解决方案：通过 MCP 直接注入音素

使用此 MCP 服务器，LLM 通过官方 API 直接设置歌词和音素：

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

往返发音验证

1. 调用 set_phonemes 应用目标音素。

2. 调用 get_computed_phonemes 重新查询 Synthesizer V 的内部合成器引擎。

3. 将计算出的音素与预期发音进行比较，以验证完全匹配。

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

安全性、试运行与回滚保证

1. dry_run: true： 所有修改工具都支持 dry_run: true。服务器返回预测的更改和差异，而不修改项目状态。

2. 应用内一步撤销（project.newUndoRecord()）： 每个修改性的 MCP 操作都会注册一个项目撤销记录。用户可以在 Synthesizer V Studio 中按 Cmd+Z / Ctrl+Z 立即还原整个操作。

3. 批处理中的事务回滚： 如果在 batch_edit 期间发生错误，脚本会捕获修改前的状态，并在返回错误之前自动回滚已修改的项目。

4. 边界与范围验证：

   • MIDI 音高：0 - 127

   • 响度：-48 dB 到 +12 dB

   • 张力 / 气声 / 性别：-1.0 到 +1.0

   • 发声：0.0 到 +1.0

   • 音高偏移：-1200 到 +1200 音分

   • 歌声模式：0 到 150

参考与官方 API 合规性

• 官方脚本手册：https://resource.dreamtonics.com/scripting/index.html

• 使用的主要官方 API：

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

许可证

MIT License.