synthlab-mcp

AI-powered synthesis lab — Compose songs, generate Pure Data & VCV Rack patches, map MIDI controllers, and control live synths through Claude.

---

What is this?

An MCP (Model Context Protocol) server that turns Claude into a full synthesis workstation. 10 tools + 1 prompt, 741 tests, zero runtime dependencies beyond MCP SDK + Zod.

Pure Data — compose full songs from genre descriptions, parse .pd files into typed ASTs, generate patches from specs, analyze signal flow, template 11 instruments, assemble multi-module racks with inter-module wiring, send OSC/FUDI in real time.

VCV Rack — generate .vcv patch files from module + cable specs, with a registry of 19 plugins (~600 modules) auto-scraped from C++ source.

MIDI Controllers — auto-map hardware controls (Korg nanoKONTROL2, Arturia MicroFreak, Roland TR-8S) to rack parameters with absolute, relative, and trigger modes.

"Compose a dark techno track with drums, bass, and an arpeggio — use K2 controller" → complete .pd rack with clock, sequencer, synths, mixer, reverb, and MIDI mapping

"Create a rack with clock, sequencer, saw synth, reverb, and mixer — wire them together" → individual .pd files + combined rack that opens in Pure Data

"Create a VCV Rack patch with VCO → VCF → VCA → AudioInterface2" → .vcv file that loads in VCV Rack 2.x

---

Architecture

+--------------------------------------------------------------------+
|                       Claude / AI Client                           |
+----------------------------+---------------------------------------+
                             | MCP (stdio)
+----------------------------v---------------------------------------+
|                      synthlab-mcp-server                             |
|                                                                    |
|  10 MCP Tools + 1 Prompt                                           |
|  +------------------+  +------------------+  +------------------+  |
|  |   parse_patch    |  |  generate_patch  |  |  analyze_patch   |  |
|  |  validate_patch  |  | create_template  |  |   create_rack    |  |
|  |  send_message    |  | list_vcv_modules |  |   generate_vcv   |  |
|  |  compose_patch   |  |                  |  |                  |  |
|  +--------+---------+  +--------+---------+  +--------+---------+  |
|           |                     |                      |           |
|  +--------v---------------------v----------------------v---------+ |
|  |                       Pd Core Engine                          | |
|  |  Parser (.pd→AST) | Serializer (AST→.pd) | Validator         | |
|  |  Object Registry (~100 Pd-vanilla objects)                    | |
|  +---------------------------------------------------------------+ |
|                                                                    |
|  +---------------------------------------------------------------+ |
|  |            Template Engine (11 templates)                     | |
|  |  synth | seq | drums | reverb | mixer | clock | bridge        | |
|  |  chaos | maths | turing-machine | granular                    | |
|  +---------------------------------------------------------------+ |
|                                                                    |
|  +---------------------------------------------------------------+ |
|  |     Rack Builder + Wiring + MIDI Controllers                  | |
|  |  throw~/catch~ (audio) | send/receive (control)               | |
|  |  K2 (abs+rel+trigger) | MicroFreak (output) | TR-8S (bidir)  | |
|  +---------------------------------------------------------------+ |
|                                                                    |
|  +---------------------------------------------------------------+ |
|  |     Song Composer (genre → wired rack)                        | |
|  |  9 genres | 7 moods | 8 roles | 10 scales | auto-wiring      | |
|  +---------------------------------------------------------------+ |
|                                                                    |
|  +---------------------------------------------------------------+ |
|  |            VCV Rack Generator                                 | |
|  |  19-plugin registry (~600 modules) from C++ source scraping   | |
|  |  Fuzzy port/param resolution | HP positioning | Cable wiring  | |
|  +---------------------------------------------------------------+ |
|                                                                    |
|  +---------------------------------------------------------------+ |
|  |            Network Layer (zero external deps)                 | |
|  |  OSC encoder (binary) | FUDI formatter (text)                 | |
|  |  UDP sender (dgram) | TCP sender (net)                        | |
|  +---------------------------------------------------------------+ |
+--------------------------------------------------------------------+
              |                                 |
    OSC (UDP) / FUDI (TCP)               .vcv file output
              |                                 |
      +-------v-------+               +--------v--------+
      |  Pure Data    |               |  VCV Rack 2.x   |
      |  (running)    |               |                  |
      +---------------+               +-----------------+

---

Features

Parser — Full AST from .pd files

Parses Pure Data's text-based format into a typed Abstract Syntax Tree with support for:

• Objects, messages, number boxes, symbol atoms, comments
• Nested subpatches (recursive canvas stack)
• All connection types (signal and control)
• Escaped semicolons, multi-line statements
• Round-trip fidelity (parse -> serialize -> parse = identical structure)

Patch Generator — From JSON spec to valid .pd

{
  "title": "Simple Sine",
  "nodes": [
    { "name": "osc~", "args": [440] },
    { "name": "*~", "args": [0.1] },
    { "name": "dac~" }
  ],
  "connections": [
    { "from": 0, "to": 1 },
    { "from": 1, "to": 2 },
    { "from": 1, "to": 2, "inlet": 1 }
  ]
}

Produces a .pd file that opens cleanly in Pure Data 0.54+.

Object Registry

Categorized database of ~95 Pd-vanilla objects across math, MIDI, time, audio, control, data, GUI, and subpatch categories. Each entry includes inlet/outlet counts (with variable-count support for objects like select, pack, trigger), aliases, and signal type classification.

Patch Validator — Structural integrity checks

Detects 9 categories of issues: broken connections, duplicate connections, unknown objects, orphan objects, empty subpatches, missing DSP sinks.

Template Engine — 11 parameterized instruments

Modular two-tier system: modules (oscillator, filter, VCA, envelope, delay, reverb) compose into templates via compose() with automatic index offsetting.

Template	Eurorack Analog	Key Parameters
synth	Oscillator + Filter + VCA	waveform, filter, envelope, frequency, cutoff, amplitude
sequencer	Step sequencer	steps, bpm, notes, midiChannel, velocity
drum-machine	Analog drums (3-layer)	voices (bd/sn/hh/cp), tune, decay, tone, per-voice volume
reverb	Spring/plate reverb	variant (schroeder/simple), roomSize, damping, wetDry
mixer	Mixer module	channels (1-16), per-channel mute gates
clock	Master clock	bpm, divisions (e.g. [1,2,4,8])
chaos	Chaos/random CV	outputs (1-3), speed, r (logistic map parameter)
maths	Function generator	channels (1-2), rise, fall, cycle, outputRange
turing-machine	Turing Machine	length, probability, range, offset
granular	Granular sampler	grains, grainSize, pitch, position, freeze, wetDry
bridge	Network receiver	protocol (osc/fudi), port, routes

Rack Builder — Eurorack-style module assembly

Generates individual .pd files per module + a combined _rack.pd with all modules side-by-side.

Inter-module wiring connects modules via Pd bus objects:

• Audio (signal rate): throw~ / catch~
• Control (message rate): send / receive

{
  "modules": [
    { "template": "clock", "params": { "bpm": 140 }, "id": "clock" },
    { "template": "sequencer", "params": { "steps": 8 }, "id": "seq" },
    { "template": "synth", "params": { "waveform": "saw" }, "id": "synth" },
    { "template": "reverb", "id": "reverb" },
    { "template": "mixer", "params": { "channels": 2 }, "id": "mixer" }
  ],
  "wiring": [
    { "from": "clock", "output": "beat_div1", "to": "seq", "input": "clock_in" },
    { "from": "seq", "output": "note", "to": "synth", "input": "note" },
    { "from": "synth", "output": "audio", "to": "reverb", "input": "audio_in" },
    { "from": "reverb", "output": "audio", "to": "mixer", "input": "ch1" }
  ]
}

The wiring system handles connection redirection (no node removal), clock sync for self-clocking modules, audio fan-out, and table name deduplication.

MIDI Controller System — Hardware integration

Auto-maps hardware controls to rack parameters. Generates _controller.pd (MIDI routing) and _k2_config.json (LED feedback).

Three device profiles:

Device	Controls	Direction	Features
Korg nanoKONTROL2	34 (faders, pots, buttons)	Input	Absolute, relative (encoders), trigger/toggle
Arturia MicroFreak	21 parameters	Output only	CC output for display sync
Roland TR-8S	51 parameters	Bidirectional	Send + receive, LED feedback

Auto-mapper phases:

1. Custom mappings (user-specified)
2. Amplitude controls → faders
3. Frequency/filter controls → pots
4. Remaining controls → relative encoders
5. Transport/toggle controls → buttons

{
  "modules": [
    { "template": "synth", "params": { "waveform": "saw" }, "id": "synth" },
    { "template": "mixer", "id": "mixer" }
  ],
  "controller": {
    "device": "k2",
    "mappings": [
      { "control": "fader_0", "module": "synth", "parameter": "amplitude" }
    ]
  }
}

Song Composer — Genre-driven rack generation

High-level creative interface: describe a song by genre, mood, tempo, key, and instruments — get a complete wired Pd rack with MIDI controller integration.

9 genres with curated presets:

Genre	Default Tempo	Default Mood	Default Instruments
ambient	70	ethereal	pad, texture
techno	130	dark	drums, bass, lead
house	124	energetic	drums, bass, pad
dnb	174	aggressive	drums, bass, lead
experimental	100	dark	modulator, texture, sequence
idm	140	ethereal	drums, arpeggio, modulator
minimal	125	chill	drums, bass
drone	40	melancholic	pad, pad
noise	120	aggressive	texture, modulator, drums

7 moods adjust synthesis parameters (cutoff, reverb room size, drum tone): dark, bright, aggressive, chill, ethereal, melancholic, energetic.

8 instrument roles map to templates with automatic multi-module expansion:

Role	Expands To	Wiring
lead	synth (ADSR)	seq → note
bass	synth (low octave, ADSR)	seq → note
pad	synth (slow envelope)	—
drums	drum-machine	clock → triggers
arpeggio	sequencer + synth	clock → seq → synth
sequence	sequencer	clock → seq
texture	noise synth + granular	synth → granular
modulator	turing-machine + synth	clock → turing → synth

Auto-wiring engine builds the full signal chain: clock → sequencers → synths → mixer → effects.

10 musical scales (major, minor, dorian, phrygian, mixolydian, pentatonic-major/minor, chromatic, whole-tone, blues) x 12 root notes for sequencer note generation.

The song_analysis MCP prompt guides Claude through Socratic questions to fill the spec before calling compose_patch.

{
  "genre": "dnb",
  "tempo": 175,
  "mood": "aggressive",
  "key": { "root": "E", "scale": "minor" },
  "instruments": [
    { "role": "drums" },
    { "role": "bass" },
    { "role": "arpeggio" }
  ],
  "effects": ["reverb"],
  "controller": { "device": "k2" }
}

Live Control — OSC/FUDI messaging

Send real-time control messages to a running Pd instance. Zero external dependencies — uses Node.js built-in dgram (UDP) and net (TCP).

Protocol	Transport	Default Port	Format
OSC	UDP	9000	Binary (OSC 1.0 spec)
FUDI	TCP	3000	Text (selector args;\n)

Use the bridge template to generate the Pd-side receiver patch:

• OSC: [netreceive -u -b 9000] → [oscparse] → [route /pd] → per-route [send]
• FUDI: [netreceive 3000] → [route] → per-route [send]

VCV Rack Generator — .vcv patch files

Generates VCV Rack v2 patch files (plain JSON .vcv format) from module + cable specifications.

19 plugin registries (~600 modules) with port/param IDs scraped from C++ source:

Plugin	Modules	Source
Core	9	AudioInterface2, MIDIToCVInterface, CV-MIDI, Notes, etc.
Fundamental	35	VCO, VCF, VCA, LFO, ADSR, Mixer, SEQ-3, Scope, etc.
Bogaudio	111	VCO, VCF, ADSR, Mix8, FMOp, Noise, etc.
CountModula	104	Sequencers, gates, logic, quantizers
AudibleInstruments	20	Mutable Instruments clones (Braids, Clouds, Rings, etc.)
ImpromptuModular	29	Clocked, Foundry, Phrase-Seq, etc.
FrozenWasteland	49	QAR (Euclidean), ProbablyNote, Portland Weather, etc.
SubmarineFree	65	Logic gates, comparators, digital utilities
JW-Modules	36	GridSeq, NoteSeq, Patterns, generative sequencers
Befaco	32	EvenVCO, Mixer, Slew, SpringReverb, etc.
Valley	8	Plateau, Dexter, Amalgam, etc.
Stoermelder PackOne	42	STRIP, MIDI-CAT, 8FACE, etc.
ZZC	10	Phaseque, Clock, Divider, FN-3, SH-8
+ 6 more	~60	ML Modules, Prism, GlueTheGiant, OrangeLine, StudioSixPlusOne, VCV Recorder

Features:

• Fuzzy port/param resolution (by label, name, partial match, or ID)
• Plugin aliases ("vcv" → Fundamental, "mi" → AudibleInstruments, "bg" → Bogaudio)
• Left-to-right HP positioning with module adjacency chain
• Cable color cycling (5-color palette) or custom hex colors
• Param overrides with default values from registry
• Duplicate input port validation
• Path sanitization for file output

{
  "modules": [
    { "plugin": "Fundamental", "model": "VCO" },
    { "plugin": "Fundamental", "model": "VCF", "params": { "Frequency": 2.0 } },
    { "plugin": "Fundamental", "model": "VCA" },
    { "plugin": "Core", "model": "AudioInterface2" }
  ],
  "cables": [
    { "from": { "module": 0, "port": "Saw" }, "to": { "module": 1, "port": "Audio" } },
    { "from": { "module": 1, "port": "Lowpass" }, "to": { "module": 2, "port": "Channel 1" } },
    { "from": { "module": 2, "port": "Channel 1" }, "to": { "module": 3, "port": "Audio 1" } }
  ]
}

Patch Analyzer — Deep structural analysis

• Object counts by category (audio, control, MIDI, math, etc.)
• Signal flow graph — adjacency list with topological sort (Kahn's algorithm), cycle detection
• DSP chain detection — DFS from audio sources (osc~, noise~, adc~) to sinks (dac~, writesf~)
• Complexity scoring — 0-100 weighted score based on object count, connection density, subpatch depth, audio chains, and object variety

---

Quick Start

1. Clone and build

git clone https://github.com/j0KZ/synthlab-mcp-server.git
cd synthlab-mcp-server
npm install
npm run build

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "synthlab": {
      "command": "npx",
      "args": ["synthlab-mcp-server"]
    }
  }
}

Or from a local clone:

{
  "mcpServers": {
    "synthlab": {
      "command": "node",
      "args": ["/absolute/path/to/synthlab-mcp-server/dist/index.js"]
    }
  }
}

3. Use it

Open Claude Desktop and ask:

"Parse the file /path/to/my-patch.pd and explain what it does"

"Create a rack with clock, sequencer, saw synth, reverb, and mixer — wire clock to sequencer, sequencer to synth, synth through reverb to mixer"

"Create a VCV Rack patch with Fundamental VCO, VCF, and AudioInterface2 — saw output through lowpass filter to audio"

"Compose a dark techno track with drums, bass, and arpeggio"

"Send /pd/tempo 140 to my running Pd instance"

---

MCP Tools

parse_patch

Parse a .pd file and return a structured description.

Parameter	Type	Description
source	string	File path or raw .pd text

generate_patch

Generate a valid .pd file from a JSON specification of nodes and connections.

Parameter	Type	Description
title	string?	Comment at the top
nodes	array	Objects, messages, atoms
connections	array	Wiring between nodes
outputPath	string?	Write to file (optional)

validate_patch

Validate structural integrity (broken connections, orphans, missing sinks).

Parameter	Type	Description
source	string	File path or raw .pd text

analyze_patch

Object counts, signal flow graph, DSP chains, complexity score.

Parameter	Type	Description
source	string	File path or raw .pd text

create_from_template

Generate a patch from a parameterized template (11 available).

Parameter	Type	Description
template	string	Template name (see table above)
params	object?	Template-specific parameters
outputPath	string?	Write to file (optional)

create_rack

Assemble multiple modules into a rack with inter-module wiring and MIDI controller integration.

Parameter	Type	Description
modules	array	Module specs: { template, params?, id?, filename? }
wiring	array?	Connections: { from, output, to, input }
controller	object?	MIDI controller: { device, midiChannel?, mappings? }
outputDir	string?	Directory to write all files

compose_patch

Generate a complete wired Pd rack from a high-level song description (genre, mood, tempo, key, instruments, effects, controller).

Parameter	Type	Description
genre	string	Genre preset (ambient, techno, house, dnb, experimental, idm, minimal, drone, noise)
tempo	number?	Override BPM (clamped to genre range)
mood	string?	Mood adjustment (dark, bright, aggressive, chill, ethereal, melancholic, energetic)
key	object?	Musical key: { root: NoteName, scale: ScaleType }
instruments	array?	Instrument specs: { role, id?, template?, params? }
effects	array?	Effect chain: ["reverb", "granular"]
controller	object?	MIDI controller: { device, midiChannel?, mappings? }

send_message

Send a control message to a running Pd instance via OSC or FUDI.

Parameter	Type	Description
protocol	"osc" | "fudi"	Transport protocol (default: "osc")
host	string?	Target host (default: "127.0.0.1")
port	number?	Target port (default: 9000 OSC / 3000 FUDI)
address	string	Message address (e.g. /pd/tempo)
args	array?	Message arguments (numbers or strings)

list_vcv_modules

Discover available VCV Rack modules, ports, and params before building a patch.

Parameter	Type	Description
plugin	string	Plugin name or alias ("Fundamental", "mi", "bg")
module	string?	Module slug for detailed port/param info. Omit to list all modules

Call with just plugin to get all module slugs with tags and HP. Call with plugin + module to get exact input/output port names and param names for cabling. Includes plugin version for freshness tracking.

generate_vcv

Generate a VCV Rack .vcv patch file from module and cable specifications.

Parameter	Type	Description
modules	array	Module specs: { plugin, model, params? }
cables	array?	Cable connections: { from: {module, port}, to: {module, port}, color? }
outputPath	string?	Write .vcv file (optional)

Supports 19 plugins with aliases: "vcv" → Fundamental, "mi" → AudibleInstruments, "bg" → Bogaudio, "fw" → FrozenWasteland, "jw" → JW-Modules, "sub" → SubmarineFree, etc.

MCP Prompts

song_analysis

Guided Socratic conversation to design a song step by step (genre → mood → tempo → key → instruments → effects → controller) then call compose_patch.

---

Project Structure

src/                            # ~9,500 lines (+ 42,800 registry data)
  index.ts                      # MCP server — 10 tools + 1 prompt, stdio transport
  types.ts                      # PdPatch, PdCanvas, PdNode, PdConnection
  constants.ts                  # Format constants, layout defaults
  core/
    parser.ts                   # .pd text -> AST
    serializer.ts               # AST -> .pd text + buildPatch()
    object-registry.ts          # ~100 Pd-vanilla objects with port counts
    validator.ts                # 9 structural checks
  composer/
    types.ts                    # SongSpec, Genre, Mood, InstrumentRole types
    presets.ts                  # 9 genre presets (tempo, instruments, key, mood)
    moods.ts                    # 7 mood adjustments (cutoff, reverb, drum tone)
    scales.ts                   # Scale generator (10 scales × 12 keys → MIDI notes)
    wiring-rules.ts             # Auto-wiring engine (clock→seq→synth→mixer→fx)
    song-mapper.ts              # SongSpec → CreateRackInput mapper
  schemas/
    patch.ts                    # Zod schemas for parse/generate
    analyze.ts                  # Zod schemas for validate/analyze
    template.ts                 # Zod schema for create_from_template
    rack.ts                     # Zod schema for create_rack
    control.ts                  # Zod schema for send_message
    compose.ts                  # Zod schema for compose_patch
    vcv.ts                      # Zod schemas for list_vcv_modules + generate_vcv
  templates/
    index.ts                    # Template registry + dispatcher (11 templates)
    port-info.ts                # PortInfo, RackableSpec types for wiring
    validate-params.ts          # Runtime param validation
    synth.ts                    # Oscillator -> filter -> VCA -> dac~
    sequencer.ts                # MIDI step sequencer
    drum-machine.ts             # 4 analog drum voices — 3-layer (voices/filter/mix)
    reverb-template.ts          # adc~ -> reverb -> wet/dry -> dac~
    mixer.ts                    # N-channel mixer with mute gates
    clock.ts                    # Master clock with divided outputs
    chaos.ts                    # Logistic map chaos generator
    maths.ts                    # Function generator (rise/fall envelopes)
    turing-machine.ts           # Shift register random sequencer
    granular.ts                 # Granular synthesis sampler
    bridge.ts                   # OSC/FUDI network receiver
    modules/
      compose.ts                # Module composition with index offsetting
      oscillator.ts             # 4 variants: sine, saw, square, noise
      filter.ts                 # 5 variants: lowpass, highpass, bandpass, moog, korg
      vca.ts                    # VCA module (*~)
      envelope.ts               # 3 variants: adsr, ar, decay
      delay.ts                  # 2 variants: simple, pingpong
      reverb.ts                 # 2 variants: schroeder, simple
  controllers/
    auto-mapper.ts              # 4-phase auto-mapping (custom -> amp -> freq -> rest)
    pd-controller.ts            # Input controller patch builder
    pd-output-controller.ts     # Output controller (ctlout feedback)
    param-injector.ts           # Parameter bus injection
    k2-deck-config.ts           # K2 LED configuration generator
  devices/
    index.ts                    # Device registry
    k2.ts                       # Korg nanoKONTROL2 (34 controls)
    microfreak.ts               # Arturia MicroFreak (21 outputs)
    tr8s.ts                     # Roland TR-8S (51 bidirectional)
  network/
    osc-encoder.ts              # OSC 1.0 binary encoder (4-byte aligned)
    fudi-formatter.ts           # FUDI text formatter
    udp-sender.ts               # UDP fire-and-forget (dgram)
    tcp-sender.ts               # TCP send/receive (net)
  vcv/
    types.ts                    # Registry, spec, and serialization types
    generator.ts                # Module resolution, cables, positioning
    positioner.ts               # Left-to-right HP layout
    registry.ts                 # Plugin lookup with aliases + fuzzy matching
    validate-vcv-params.ts      # Claude Desktop quirk coercion
    registry/                   # 15 auto-generated plugin registries
      core.ts                   # 9 modules (manual — complex ENUMS)
      fundamental.ts            # 35 modules
      bogaudio.ts               # 111 modules
      audibleinstruments.ts     # 20 modules
      befaco.ts                 # 32 modules
      countmodula.ts            # 50+ modules
      impromptumodular.ts       # 30+ modules
      valley.ts                 # 9 modules
      stoermelder-packone.ts    # 42 modules
      + 6 more                  # ml-modules, orangeline, prism, etc.
  tools/
    parse.ts                    # parse_patch tool handler
    generate.ts                 # generate_patch tool handler
    validate.ts                 # validate_patch tool handler
    analyze.ts                  # analyze_patch tool handler
    template.ts                 # create_from_template tool handler
    rack.ts                     # create_rack + combined patch builder
    compose.ts                  # compose_patch tool handler
    control.ts                  # send_message tool handler
    list-vcv.ts                 # list_vcv_modules tool handler (discovery)
    vcv.ts                      # generate_vcv tool handler
  wiring/
    bus-injector.ts             # Inter-module wiring (throw~/catch~, send/receive)
  utils/
    resolve-source.ts           # File-path vs raw-text resolver

scripts/                        # ~700 lines
  build-vcv-registry.ts         # Clone repos -> parse C++ -> generate .ts
  parse-cpp-enums.ts            # C++ enum parser (ParamIds, InputIds, etc.)
  parse-svg-width.ts            # SVG panel width -> HP conversion
  update-readme-stats.ts        # Auto-update README tool/test counts

tests/                          # 741 tests, ~6,500 lines
  parser.test.ts                # 14 — parsing, subpatches, arrays, edge cases
  serializer.test.ts            # 8 — round-trip, spec builder, escaping
  object-registry.test.ts       # 37 — port counts, aliases, variable objects
  validator.test.ts             # 20 — each check type + fixtures
  analyze.test.ts               # 29 — counts, flow, DSP chains, complexity, formatting
  composer/
    composer.test.ts            # 42 — scales, presets, moods, wiring, mapper, validation
  controllers/
    controller.test.ts          # 80 — auto-mapper, controller patches, device profiles
  templates/
    compose.test.ts             # 8 — module composition, wiring, autoLayout
    modules.test.ts             # 17 — all module variants
    templates.test.ts           # 46 — complete template round-trips
    edge-cases.test.ts          # 106 — param validation, coercion, boundaries
    bridge.test.ts              # 3 — OSC/FUDI bridge variants
  network/
    osc-encoder.test.ts         # 8 — binary encoding, padding, type inference
    fudi-formatter.test.ts      # 3 — text formatting
    udp-sender.test.ts          # 3 — UDP send, socket error mock
    control.test.ts             # 6 — mock UDP/TCP servers, end-to-end
  tools/
    rack.test.ts                # 13 — rack assembly, layout, file writing
    rack-wiring.test.ts         # 13 — wiring integration, bus injection
    compose.test.ts             # 14 — compose_patch tool, genres, validation, coercion
    list-vcv.test.ts            # 9 — discovery tool, aliases, coercion
    vcv.test.ts                 # 8 — tool handler, format, sanitization
  utils/
    resolve-source.test.ts      # 5 — raw text vs file path resolution
  vcv/
    generator.test.ts           # 15 — modules, cables, positions, errors
    registry.test.ts            # 71 — 19 plugins, module aliases, fuzzy resolution, formatting
    positioner.test.ts          # 5 — HP layout, adjacency chain
    validate-vcv-params.test.ts # 8 — coercion, empty arrays, booleans
  scripts/
    parse-cpp-enums.test.ts     # 30 — enums, ENUMS macro, removed, labels, preprocessor, expressions
    parse-svg-width.test.ts     # 4 — mm/px to HP conversion
  wiring/
    bus-injector.test.ts        # 17 — connection helpers, validation
  fixtures/
    hello-world.pd              # Minimal: osc~ -> *~ -> dac~
    midi-sequencer.pd           # 4-step sequencer with noteout
    subpatch.pd                 # Nested canvas with inlet~/outlet~
    broken-connections.pd       # Invalid connections for validator
    orphan-objects.pd           # Disconnected objects
    complex-patch.pd            # Multi-chain audio + control + subpatch

---

Development

npm run build        # Compile with tsup (ESM + declarations)
npm run dev          # Watch mode
npm run test         # Run vitest (741 tests)
npm run lint         # Type-check with tsc --noEmit
npm run inspect      # Test server with MCP Inspector

VCV Registry rebuild (only needed when plugins update)

npm run vcv:build-registry   # Clone repos -> parse C++ -> regenerate src/vcv/registry/*.ts
npm run build                # Rebundle

Update README stats (tool/test counts)

npm run update-stats         # Patches README with actual tool + test counts

---

Tech Stack

Technology	Purpose
TypeScript (strict mode)	Type-safe parser and serializer
MCP SDK (@modelcontextprotocol/sdk)	Protocol implementation
Zod	Runtime input validation
Vitest	Test runner (741 tests)
tsup	Bundler (ESM output, 1.04 MB)
tsx	TypeScript execution for build scripts
Zero runtime deps beyond MCP SDK + Zod	OSC via dgram, FUDI via net

---

Roadmap

All phases complete. Recent improvements:

1. Core — Parser + serializer + MCP scaffold
2. Analysis — Object registry, signal flow graph, DSP chain detection, complexity scoring
3. Templates — 11 parameterized instruments with modular two-tier composition
4. Rack Builder — create_from_template + create_rack (multi-module assembly)
5. Wiring — Inter-module buses (throw~/catch~, send/receive, clock sync)
6. MIDI Controllers — K2, MicroFreak, TR-8S profiles with auto-mapping
7. Live Control — OSC/FUDI messaging (send_message tool + bridge template)
8. VCV Rack — .vcv generation with 19-plugin registry (~600 modules), module discovery + aliases
9. Song Composer — compose_patch tool + song_analysis Socratic prompt
10. Drum Machine v2 — 3-layer architecture (voices/filter/mix), sub-bass kick, bob~ warmth, metallic hi-hat, 808-style clap, per-voice volume control

---

License

MIT