SV1 Agent Bridge

A local MCP server that lets Codex (or any MCP client) inspect and control Synthesizer V Studio 1.x through its public Lua scripting API.

Inspired by zhoupengjie/synthv-agent-bridge (which targets Synthesizer V Studio 2 Pro). This version targets Studio 1.x (e.g. 1.11.2) and reuses the same proven pattern: a persistent Lua script that polls JSON request files written by a stdio MCP server.

Codex (stdio MCP)  --JSON-RPC-->  Node MCP server  --file IPC-->  SV1AgentBridge.lua (in SV1)  --SV API-->  project

No network ports, no .svp parsing, no AI calls. All project mutations run inside Synthesizer V through its scripting object model and create undo records.

Layout

• synthv/SV1AgentBridge.lua persistent Lua bridge (install into SV1 Scripts folder)

• synthv/StopSV1AgentBridge.lua stops a running bridge

• src/server.mjs zero-dependency stdio MCP server (Node >= 18)

• ipc/ request/response/status files (auto-created)

Install

1. Copy synthv/SV1AgentBridge.lua and synthv/StopSV1AgentBridge.lua into your Synthesizer V Studio 1 Scripts directory (e.g. Documents\Synthesizer V Studio\Scripts or the app's Scripts folder).

2. Keep src/server.mjs here. Node >= 18 is required (no npm install needed).

Run

1. In Synthesizer V Studio 1, open a project, then run SV1 Agent Bridge from the Scripts menu. A message box confirms it started and shows the IPC dir.

2. Register the MCP server with Codex (see below), then ask Codex to use it.

MCP config

Codex CLI - add to ~/.codex/config.toml (or the app's MCP settings):

[mcp_servers.sv1-agent-bridge]
command = "node"
args = ["E:/AI/MCP/sv1-agent-bridge/src/server.mjs"]

Or via CLI: codex mcp add sv1-agent-bridge node E:/AI/MCP/sv1-agent-bridge/src/server.mjs

Claude Code - one command:

claude mcp add sv1-agent-bridge -- node E:/AI/MCP/sv1-agent-bridge/src/server.mjs

Cursor, Windsurf, Cline, and generic stdio - see docs/MCP-CONFIG.md.

Optional: set a custom IPC directory with the env var SV1_BRIDGE_IPC on both sides (the Lua script reads the same env var).

Tools (29 total)

Project / structure sv1_ping, sv1_read_project, sv1_create_track, sv1_create_note_group, sv1_add_group_reference, sv1_set_tempo, sv1_set_time_signature

Notes sv1_read_notes, sv1_get_note_details, sv1_set_lyrics, sv1_edit_note, sv1_edit_notes, sv1_add_note, sv1_add_notes, sv1_delete_note, sv1_transpose_notes, sv1_set_musical_type, sv1_refresh_phonemes

Editor / selection sv1_set_current_track, sv1_set_current_group, sv1_get_selection, sv1_select_notes, sv1_clear_selection

Playback sv1_play, sv1_stop, sv1_pause, sv1_seek, sv1_set_loop, sv1_get_state

All track/group/note indices are 1-based. Time values are in blicks (SV's internal unit; SV.QUARTER = 705600000 blicks per quarter note). Tools that return notes also include seconds via the project time axis. sv1_add_notes accepts an optional unit of quarters or blicks. edit_note/edit_notes/add_note/add_notes accept an optional musicalType ("sing" or "rap").

Known limitation: voice assignment

SV1 1.11.2 scripting cannot assign or copy a voice database to a group reference: getVoice() returns an empty table, setVoice() crashes the host, and there is no voice-database enumeration API. New groups created via sv1_create_note_group + sv1_add_group_reference have no voice and will not render until you assign one manually in the SV1 UI (select the group, choose a voice database). Writing notes to a group that already has a voice (assigned in the UI) works normally.

Documentation

• AGENTS.md - usage manual for any agent driving SV1 through this bridge

• docs/DEVELOPING.md - architecture, IPC protocol, how to add tools, SV1 API gotchas

• docs/MCP-CONFIG.md - MCP server config for Claude Code, Cursor, Windsurf, Cline, etc.

Status

Experimental. Test on a copy of important projects. Write tools create one Synthesizer V undo record each, so you can undo any change from the editor.

How the SV1 vs SV2 gap was handled

Studio 1.x lacks Studio 2 features (Vocal Modes, Smart Pitch, automation curves, native sidebar). The core scripting model (SV:getProject/getPlayback/getMainEditor, setTimeout polling, io file access, Project/Track/GroupReference/NoteGroup/Note) is present and nearly identical, so the bridge exposes note lyrics/pitch/timing/phonemes + playback.