Synthesizer V Studio 2 MCP Server (mcp-svstudio)

프로덕션 등급의 Model Context Protocol (MCP) 서버로, Dreamtonics Synthesizer V Studio 2 Pro를 위해 설계되어 생성형 AI 및 LLM 에이전트가 공식 Dreamtonics 스크립팅 API를 통해 안전하고 구조적이며 효율적으로 노트, 가사, 음소, 보컬 속성, 파라미터 및 재생 트랜스포트를 조작할 수 있게 합니다.

아키텍처 개요

Synthesize V Studio 2 Pro는 외부 네트워크 소켓 없이 임베디드 Lua 5.4 / Duktape JS 환경에서 스크립트를 실행합니다. 높은 성능, 낮은 지연 시간, C 라이브러리 의존성 제로를 달성하기 위해 이 MCP 서버는 **Atomic File-Mailbox IPC 프로토콜(원자 파일-메일박스 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 프로토콜 주요 특징

• 원자적 파일 이름 변경(Atomic File Renames): <id>.tmp에 작성한 후 <id>.req / <id>.res로 원자적으로 이름을 변경하여 경쟁 상태와 파일 부분 읽기 문제를 방지합니다.

• 고유 요청 ID: 빠르게 연속되는 명령들에서도 요청-응답 쌍이 보장됩니다.

• 즉시 하트비트 활성 감지(Instant Heartbeat Liveness): 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 내에서 나눈 음에 독일어 다중 음절 단어(예: schö-와 -ne)가 syllabic=begin/end로 유지되는 경우가 있는데, 이 원시 음소 텍스트가 가사에 병합됩니다:

• 예상 음 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_ph 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

안전성, Dry Run(시험 실행) 및 롤백 보장

1. dry_run: true: 모든 변경 도구가 dry_run: true를 지원합니다. 서버는 프로젝트 상태를 변경하지 않고 예상 변경 사항과 diff를 반환합니다.

2. 앱 내 원스텝 실행 취소(project.newUndoRecord() ): 모든 변경 MCP 작업은 프로젝트에 실행 취소 레코드를 등록합니다. 사용자는 Synthesizer V Studio 내에서 Cmd+Z / Ctrl+Z를 눌러 즉시 전체 작업을 되돌릴 수 있습니다.

3. 배치에서 트랜잭션 롤백: batch_edit 중 오류가 발생하면 스크립트가 변경 전 상태를 캡처하고 오류를 반환하기 전에수정된 항목을 자동으로 롤백합니다.

4. 경계 및 범위 검증:

   • MIDI 피치: 0 - 127

   • Loudness(라우드니스): -48 dB ~ +12 dB

   • Tension(텐션) / Breathiness(브리트니스) / Gender(젠더): -1.0 ~ +1.0

   • Voicing(보이싱): 0.0 ~ +1.0

   • Pitch Delta(피치 델타): -1200 ~ +1200 cents

   • Vocal Modal(보컬 모드): 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.