How do I use synthlab-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@synthlab-mcp Compose a dark techno track with drums and bass" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

synthlab-mcp

Q: Which integrations are available for this server?

Provides MIDI controller integration for auto-mapping hardware controls (Korg nanoKONTROL2, Arturia MicroFreak, Roland TR-8S) to synthesizer rack parameters, supporting absolute, relative, and trigger modes.

by j0KZ

Overview Schema Related Servers Score Discussions

TypeScript

Local

synthlab-mcp

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

npm TypeScript MCP License: MIT

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

Related MCP server: Ableton MCP

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:

Custom mappings (user-specified)
Amplitude controls → faders
Frequency/filter controls → pots
Remaining controls → relative encoders
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:

Core — Parser + serializer + MCP scaffold
Analysis — Object registry, signal flow graph, DSP chain detection, complexity scoring
Templates — 11 parameterized instruments with modular two-tier composition
Rack Builder — create_from_template + create_rack (multi-module assembly)
Wiring — Inter-module buses (throw~/catch~, send/receive, clock sync)
MIDI Controllers — K2, MicroFreak, TR-8S profiles with auto-mapping
Live Control — OSC/FUDI messaging (send_message tool + bridge template)
VCV Rack — .vcv generation with 19-plugin registry (~600 modules), module discovery + aliases
Song Composer — compose_patch tool + song_analysis Socratic prompt
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

Available Tools

10 tools

analyze_patchA

Analyze a Pure Data .pd file: object counts by category, signal flow graph, DSP chain detection, complexity scoring, and validation.

ParametersJSON Schema

Name	Required	Description	Default
`source`	Yes	Absolute file path to a .pd file, or raw .pd text content. If it starts with '#N canvas' it is treated as raw text.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must carry the burden. It lists what the tool produces, but does not disclose side effects, authentication needs, or performance implications. As a read-only analysis, the lack of side effects is inferred, but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that effectively lists the tool's capabilities without extraneous words. It is front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and no output schema, the description adequately covers what the tool does. However, it could mention that the output is a structured result, but since no output schema exists, the description itself is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant value beyond the schema by specifying that if the source starts with '#N canvas', it is treated as raw text. This clarifies the dual nature of the parameter. Schema coverage is 100%, so baseline is 3, but the added context pushes it to 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Analyze' and resource 'Pure Data .pd file', and enumerates specific outputs (object counts, signal flow graph, DSP chain, complexity scoring, validation). This differentiates it from sibling tools like validate_patch, which likely only validates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool instead of parse_patch or validate_patch. The description implies comprehensive analysis, but does not directly state when it is preferable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compose_patchA

Compose a complete musical Pd patch from a high-level song description. Before calling this tool, ask the user about genre, mood, tempo, key, instruments, and effects — use the song_analysis prompt as a guide. Only call this tool once you have enough info. Genres: ambient, techno, house, dnb, experimental, idm, minimal, drone, noise. Moods: dark, bright, aggressive, chill, ethereal, melancholic, energetic. Instrument roles: lead, bass, pad, drums, arpeggio, sequence, texture, modulator. Each role auto-selects appropriate templates (e.g. lead → sequencer + synth, texture → noise synth + granular). IMPORTANT: The complete .pd content is ALWAYS returned in the response — present it directly to the user as code blocks. STOP after presenting the result. Do NOT run bash, ls, mkdir, cat, cp, mv, or ANY file/shell operations after this tool. Do NOT try to save, create, write, or verify files — NEVER use artifacts or file downloads. Everything is already in the response text. Just show the content to the user as-is.

ParametersJSON Schema

Name	Required	Description
`genre`	Yes	Musical genre: "ambient", "techno", "house", "dnb", "experimental", "idm", "minimal", "drone", "noise".
`tempo`	No	BPM (20-300). Defaults to genre preset. Clamped to genre range.
`mood`	No	Mood modifier: "dark", "bright", "aggressive", "chill", "ethereal", "melancholic", "energetic". Defaults to genre preset.
`key`	No	Musical key. Defaults to genre preset.
`instruments`	No	Instrument specifications. Defaults to genre preset instruments.
`effects`	No	Effect chain: ["reverb"], ["granular"], or ["reverb", "granular"]. Defaults to genre preset.
`controller`	No	MIDI controller integration. Generates controller patches.
`outputDir`	No	Optional ABSOLUTE directory path to write all .pd files. Only use if the user explicitly requests saving to a specific path. If omitted, content is returned but not written to disk.

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description fully discloses behavior: auto-selects templates per role, always returns .pd content in response, warns against shell/file operations, and explains outputDir's role. Contradiction false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with main purpose first, then prerequisites, enumerated values, and critical warnings. Slightly verbose but every sentence is informative. Front-loads key info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, nested objects, and no output schema, the description covers all necessary aspects: prerequisites, value ranges, output handling, and post-call actions. An agent can use this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds value by listing all possible values for genre, mood, roles, and explaining template selection logic, going beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it composes a complete Pd patch from a high-level description. Distinguishes from sibling tools like analyze_patch or generate_vcv by focusing on high-level composition with genre, mood, instruments, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to first gather user info about genre, mood, tempo, etc., and only call once enough info is gathered. Also tells to present results as code blocks and avoid file operations, providing clear when-to-use and not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_from_templateA

Generate a Pd patch from a parameterized template. Available: synth, sequencer, reverb, mixer, drum-machine, clock, chaos, maths, turing-machine, granular, bridge. Each template accepts specific params (e.g. synth: waveform, filter; sequencer: steps, bpm; drum-machine: voices, bpm, morphX, morphY). The complete .pd file content is ALWAYS returned in the response — present it directly to the user. STOP after presenting the result. Do NOT run bash, ls, mkdir, cat, cp, mv, or ANY file/shell operations after this tool. Do NOT try to save or verify files — everything is already handled. Just show the content to the user.

ParametersJSON Schema

Name	Required	Description
`template`	Yes	Template name: "synth", "sequencer", "reverb", "mixer", "drum-machine", "clock", "chaos", "maths", "turing-machine", "granular", or "bridge".
`params`	No	Template-specific parameters as a JSON object. Synth: { waveform: sine\|saw\|square\|noise, filter: lowpass\|highpass\|bandpass\|moog\|korg, frequency: Hz, cutoff: Hz, amplitude: 0-1, envelope: adsr\|ar\|decay\|none }. Sequencer: { steps: 1-64, bpm, notes: [MIDI 0-127], midiChannel: 1-16, velocity: 0-127 }. Reverb: { variant: schroeder\|simple, roomSize: 0-1, damping: 0-1, wetDry: 0-1 }. Mixer: { channels: 1-16, stereo: bool }. Drum-machine: { voices: [bd,sn,hh,cp], tune: 0-1, decay: 0-1, tone: 0-1, amplitude: 0-1 }. Clock: { bpm, divisions: [1,2,4,8] }. Chaos: { outputs: 1-3, speed: 0-1, r: 3.5-4.0 }. Maths: { channels: 1-2, rise: ms, fall: ms, cycle: bool, outputRange: unipolar\|bipolar }. Turing-machine: { length: 2-16, probability: 0-1, bpm, range: 1-127, offset: 0-127 }. Granular: { grains: 1-4, grainSize: 10-500, pitch: 0.25-4.0, position: 0-1, freeze: bool, wetDry: 0-1 }. Bridge: { protocol: osc\|fudi, port: 1-65535, routes: [string] }.
`outputPath`	No	Optional ABSOLUTE file path to write the .pd file. Only use if the user explicitly requests saving to a specific path. The .pd content is always returned in the response regardless.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: returns complete .pd content, handles everything internally, and warns against extra commands. With no annotations, description carries full burden; it effectively communicates the tool's safety and output expectations, though could be more explicit about default file creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with purpose first, then templates, then behavioral instructions. Every sentence contributes, but length could be reduced slightly without losing clarity. Still, it's efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers template options, parameter details, output behavior (content always returned), and optional writing. No output schema, but description compensates by explaining the response content. Lacks error handling details but sufficient for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant value by listing template-specific parameter examples (e.g., synth: waveform, filter; drum-machine: voices, morphX, morphY) with exact formats, going well beyond the schema's brief descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates a Pd patch from a parameterized template, lists 11 specific templates, and distinguishes from sibling tools like analyze_patch, validate_patch, and send_message. The verb 'Generate' and resource 'Pd patch' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs when to use (for template-based patches) and when not to (no file/shell operations after). Provides a clear STOP message and alternatives (e.g., optional outputPath only if user requests). This is comprehensive guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_rackA

Generate an entire Eurorack-style rack of Pd patches at once. Takes an array of module specs (template + params) and generates: individual .pd files for each module + a combined _rack.pd with all modules side-by-side. Use wiring to connect modules via throw~/catch~ (audio) or send/receive (control) buses. Add controller config to map a MIDI controller (e.g. K2) to rack parameters — generates _controller.pd (MIDI routing) and _k2_config.json (LED feedback). Parameters auto-map by category (faders→volume, pots→filter) or use custom mappings. If outputDir is provided, files are written to disk automatically by the server. IMPORTANT: The complete .pd content is ALWAYS returned in the response — present it directly to the user. STOP after presenting the result. Do NOT run bash, ls, mkdir, cat, cp, mv, or ANY file/shell operations after this tool. Do NOT try to save, verify, or create files — everything is already handled. Just show the content to the user.

ParametersJSON Schema

Name	Required	Description
`modules`	Yes	Array of module specifications. Each becomes a separate .pd file.
`wiring`	No	Inter-module connections for the combined _rack.pd patch.
`controller`	No	MIDI controller configuration. Generates _controller.pd (input) and/or _output_controller.pd (output) for hardware control of rack parameters.
`outputDir`	No	Optional ABSOLUTE directory path to write all .pd files. If omitted, content is returned but not written to disk.

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full responsibility. It discloses that files are written to disk if outputDir is provided, that content is always returned, and warns against post-tool file operations. It could mention overwriting behavior, but overall transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but well-structured: main action first, then details on modules, wiring, controller, outputDir, and critical imperatives. Each sentence adds value; minimal redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 4 parameters, nested objects, and no output schema, the description fully covers all aspects: purpose, parameter details, return behavior, and safety instructions. No gaps for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: explains wiring connections, controller auto-mapping, and outputDir behavior, making parameters more actionable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates an entire Eurorack-style rack of Pd patches, listing specific outputs (individual .pd files and combined _rack.pd) and optional components (wiring, controller). It distinguishes from sibling tools like create_from_template by being a bulk generation tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit instructions on how to handle the output (present content to user, stop, avoid file operations), and outlines when to use wiring and controller config. While it doesn't explicitly compare to alternatives, the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_patchA

Generate a valid Pure Data .pd file from a JSON specification of nodes and connections. The complete .pd file content is ALWAYS returned in the response — present it directly to the user. STOP after presenting the result. Do NOT run bash, ls, mkdir, cat, cp, mv, or ANY file/shell operations after this tool. For message boxes (type: 'msg'), use '\,' as a separate arg for multi-segment messages (e.g. ADSR: args: [0, '\,', 1, 10, '\,', 0.7, 100, '\,', 0, 200]). Bare commas are auto-escaped.

ParametersJSON Schema

Name	Required	Description
`title`	No	Title comment placed at the top of the patch.
`nodes`	Yes	List of nodes to place in the patch.
`connections`	No	Connections between nodes.
`outputPath`	No	Optional ABSOLUTE file path to write the .pd file. Only use if the user explicitly requests saving to a specific path. The .pd content is always returned in the response regardless.

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It warns against post-tool shell operations but does not disclose side effects like file overwriting when outputPath is given, error handling, or permissions needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is four sentences, front-loaded with purpose, and each sentence adds necessary guidance. Could be slightly more concise but no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and lack of output schema, the description covers key aspects: always returns content, how to handle it, post-tool warnings, and parameter special cases. Lacks error handling details but schema covers validation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that outputPath should only be used when user explicitly requests it, and provides special arg formatting for message boxes, going beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates a valid Pure Data .pd file from a JSON specification, distinguishing it from sibling tools like analyze_patch or validate_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit instructions to present the returned content directly to the user, stop after presenting, and avoids any shell operations. Also gives specific formatting advice for message boxes. Lacks mention of when not to use, but coverage is strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_vcvA

Generate a VCV Rack .vcv patch file from a JSON specification of modules and cables. Uses a registry of module port/param IDs scraped from C++ source. IMPORTANT: Use list_vcv_modules first to look up exact module slugs and port names — do NOT guess. Supported plugins (15): Core, Fundamental, AudibleInstruments (Mutable Instruments), Befaco, Bogaudio, CountModula, ImpromptuModular, Valley, Stoermelder PackOne, ML Modules, VCV Recorder, Prism, GlueTheGiant, OrangeLine, StudioSixPlusOne. The complete .vcv file content is ALWAYS returned in the response — present it directly to the user. STOP after presenting the result. Do NOT run bash, ls, mkdir, cat, cp, mv, or ANY file/shell operations after this tool. Do NOT try to save or verify files — everything is already handled. Just show the content to the user.

ParametersJSON Schema

Name	Required	Description
`modules`	Yes	Modules to include in the VCV Rack patch.
`cables`	No	Cable connections between modules.
`outputPath`	No	Optional ABSOLUTE file path to write the .vcv file. Only use if the user explicitly requests saving to a specific path. The .vcv content is always returned in the response regardless.

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavior: it explains that the complete .vcv content is always returned, instructs the agent to present it directly and stop, and warns against any file/shell operations. It also clarifies the outputPath parameter is optional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured: purpose, important usage note, list of supported plugins, and explicit post-call instructions. Every sentence earns its place without unnecessary repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of generating a patch file, the description covers all necessary context: what it does, prerequisites, supported plugins, output behavior, and what to avoid after. No output schema is present, but the description clearly explains the returned content.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for each parameter. The description adds value by providing usage context (e.g., using list_vcv_modules for correct slugs) and guidance on optional outputPath. It does not repeat schema info but adds operational semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states that the tool generates a VCV Rack .vcv patch file from a JSON specification, using a registry of module port/param IDs. It clearly distinguishes itself from sibling tools by instructing users to use list_vcv_modules first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use list_vcv_modules first to look up exact module slugs and port names — do NOT guess.' It also lists supported plugins and gives post-call instructions (do not run file operations).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_vcv_modulesA

List available VCV Rack modules and their ports/params for a given plugin. Call with just a plugin name to see all module slugs, tags, and HP widths. Call with plugin + module to see exact input/output port names and param names for cabling. ALWAYS call this BEFORE generate_vcv to look up correct module slugs and port names — do NOT guess. Supported plugins: Core, Fundamental, AudibleInstruments (aliases: mi, mutable), Befaco, Bogaudio (bg), CountModula, ImpromptuModular (impromptu), Valley, Stoermelder PackOne (stoermelder, p1), ML Modules (ml), VCV Recorder (recorder), Prism, GlueTheGiant (gtg), OrangeLine, StudioSixPlusOne (s6).

ParametersJSON Schema

Name	Required	Description	Default
`plugin`	Yes	Plugin name or alias (e.g. 'Fundamental', 'mi', 'Bogaudio', 'bg'). Use 'mi' or 'AudibleInstruments' for Mutable Instruments clones.
`module`	No	Module slug to get detailed port/param info (e.g. 'VCO', 'Clouds'). Omit to list all modules in the plugin.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses what information returns in each mode (module slugs, tags, HP widths vs. I/O port names, param names). No annotations exist, so description carries full burden. It doesn't mention error handling or rate limits, but the read-only nature is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is informative but slightly verbose. It front-loads the action and uses clear instructions. Could be slightly trimmed, but still efficient for the information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, 100% schema coverage, and no output schema, description adequately covers modes and supported plugins. Lacks explicit return format or error handling, but is sufficient for typical use. Sibling tools context reinforces need for lookup.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds value beyond schema by explaining plugin aliases (e.g., 'mi' for Mutable Instruments) and that module parameter is a slug. Clarifies that omitting module lists all modules. Schema already covers param descriptions, but description enriches usage understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description specifies 'List available VCV Rack modules and their ports/params for a given plugin' and distinguishes two modes (with/without module). This clearly identifies the tool's purpose and differentiates it from siblings like generate_vcv.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'ALWAYS call this BEFORE generate_vcv to look up correct module slugs and port names — do NOT guess.' Also lists supported plugins, providing clear guidance on when to use and prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_patchA

Parse a Pure Data .pd file and return a structured description of its objects, connections, and signal flow.

ParametersJSON Schema

Name	Required	Description	Default
`source`	Yes	Absolute file path to a .pd file, or raw .pd text content. If it starts with '#N canvas' it is treated as raw text.

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It states the tool parses and returns a structured description but does not clarify side effects (e.g., non-destructive reads, file system access, or error handling).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence without waste, but could benefit from specifying output format or error cases. Still, it is appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one parameter, no output schema, and no annotations, the description adequately covers the purpose and output structure. It does not mention validation or error conditions, but these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant value beyond the schema by explaining that 'source' can be either a file path or raw .pd text, with a specific heuristic for detection (starts with '#N canvas'). Schema coverage is 100%, and the description enhances understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'parse', the resource 'Pure Data .pd file', and the specific outputs ('objects, connections, and signal flow'). It distinguishes itself from siblings like 'analyze_patch' which implies analysis rather than parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., 'analyze_patch' or 'validate_patch'). The description lacks context for selection or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_messageA

Send a control message to a running Pure Data instance via OSC (UDP) or FUDI (TCP). Requires a bridge patch loaded in Pd — use create_from_template with template 'bridge' to generate one. Common addresses: /pd/tempo , /pd/note , /pd/cc <cc#> , /pd/bang, /pd/param/ . The confirmation is ALWAYS returned in the response. Do NOT attempt additional file operations after calling this tool.

ParametersJSON Schema

Name	Required	Description	Default
`protocol`	No	Protocol: "osc" (UDP, binary) or "fudi" (TCP, text). Default: "osc".	osc
`host`	No	Target host. Default: 127.0.0.1 (localhost).	127.0.0.1
`port`	No	Target port. Default: 9000 (OSC) or 3000 (FUDI).
`address`	Yes	Message address/selector. OSC: "/pd/tempo". FUDI: "tempo". Common: /pd/tempo, /pd/note, /pd/cc, /pd/bang, /pd/param/<name>.
`args`	No	Message arguments (integers, floats, or strings).

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully bears the burden. It discloses that confirmation is always returned and cautions against additional file operations, accurately indicating the tool's side effects and behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured paragraph that front-loads purpose, then covers prerequisites, examples, and warnings. Every sentence is informative, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 5 parameters, no output schema, and no annotations, the description thoroughly covers prerequisites, usage examples, important behavior, and parameter hints, making it complete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds value with common address examples, default port explanations, and argument types, going beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Send a control message to a running Pure Data instance via OSC (UDP) or FUDI (TCP).' It identifies the specific verb (send), resource (control message to Pd), and distinguishes from sibling tools like create_from_template or compose_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states prerequisite: 'Requires a bridge patch loaded in Pd — use create_from_template with template "bridge" to generate one.' Also warns against additional file operations after calling, providing clear when-to-use and when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_patchA

Validate a Pure Data .pd file for structural issues: broken connections, orphan objects, unknown objects, missing DSP sinks.

ParametersJSON Schema

Name	Required	Description	Default
`source`	Yes	Absolute file path to a .pd file, or raw .pd text content. If it starts with '#N canvas' it is treated as raw text.

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the structural checks performed and implies read-only validation. Lacks details on failure behavior or side effects, but adequate for a validation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence covering purpose and scope. Front-loaded with action and subject, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no mention of return value format. For a validation tool, knowing what is returned (list of issues, boolean, etc.) is important. Parameter description is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 100%; description almost repeats schema description. Adds minimal extra value beyond what the schema already provides for the single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'validate' and specific resource 'Pure Data .pd file', listing exact checks (broken connections, orphan objects, etc.). Distinguishes from siblings like parse_patch or compose_patch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage for validation but no explicit when-to-use, when-not-to-use, or alternative references. Agent must infer context from tool name and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

10 tool updatesv0.9.1May 29, 2026
- First observedanalyze_patch
- First observedcompose_patch
- First observedcreate_from_template
- First observedcreate_rack
- First observedgenerate_patch
- First observedgenerate_vcv
- First observedlist_vcv_modules
- First observedparse_patch
- First observedsend_message
- First observedvalidate_patch

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Disambiguation3/5

Some tools have overlapping purposes, e.g., analyze_patch, parse_patch, and validate_patch all deal with parsing/validating .pd files; compose_patch, create_from_template, and generate_patch all generate patches. Descriptions help distinguish but could still cause misselection.

Naming Consistency5/5

All tool names consistently use lowercase with underscores and follow a verb_noun pattern (e.g., analyze_patch, generate_vcv, send_message). Even create_from_template is clear and predictable.

Tool Count5/5

10 tools is well-scoped for the domain of Pd and VCV Rack patch management, covering creation, analysis, validation, and control without being excessive.

Completeness4/5

The tool set covers the primary workflows: patch generation (via multiple methods), analysis/validation, and real-time control. Minor gaps like explicit update/delete or VCV analysis exist, but agents can work around them.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Lacuna Music A
io.github.JOYLINK-LTD
Generate AI music via the Lacuna Music API from MCP clients like Claude Desktop & Code.
AI & Machine Learning Audio Processing
314
StoryStudioOAuth
io.github.HelloElo-Fr
AI image, video, voice and music generation over MCP, routed to Veo 3.1, Seedance 2.0 and more.
AI & Machine Learning Image & Video Processing Audio Processing
1
VocunoOAuth
com.vocuno
AI music studio: song generation with vocals, covers, stems, voice conversion, mastering, editing.
Audio Processing Speech Processing AI & Machine Learning
1
moltdj A
io.github.bnovik0v
AI music and podcast platform for autonomous agents. SoundCloud for AI bots.
Autonomous Agents Audio Processing Entertainment & Media
3

Related MCP Servers

SuperCollider MCP Server
Audio Processing Multimedia Processing App Automation
BradA1878
F
license
A
quality
D
maintenance
Enables AI assistants to generate and control real-time audio synthesis through natural language descriptions using SuperCollider. Features 10 built-in synth types, pattern sequencing, audio recording, and server lifecycle management for creating sounds from simple English descriptions.
Updated a year ago (2025-10-18 02:24 UTC)
11
1
-
Ableton MCP
Multimedia Processing Audio Processing App Automation
keigotak
A
license
Not graded
quality
D
maintenance
Enables natural language control over Ableton Live for generating musical patterns, melodies, and full song arrangements. It also provides tools for sample searching and mixing assistance through an OSC-based connection with Claude Desktop.
Updated 7 months ago (2026-02-11 16:03 UTC)
1
MIT
Pure Data MCP Server
Audio Processing Multimedia Processing
nikmaniatis
F
license
A
quality
D
maintenance
Enables natural language control of Pure Data patches through Claude AI, allowing dynamic creation, modification, and DSP control via the Model Context Protocol.
Updated 3 months ago (2026-06-02 15:30 UTC)
11
22
-
PureData-MCP
Audio Processing Multimedia Processing
damagethundercat
A
license
B
quality
B
maintenance
Control and live-patch Pure Data from AI agents via the Model Context Protocol.
Updated 3 months ago (2026-05-22 18:39 UTC)
21
15
2
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/j0KZ/synthlab-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

synthlab-mcp

What is this?

Architecture

Features

Parser — Full AST from .pd files

Patch Generator — From JSON spec to valid .pd

Object Registry

Patch Validator — Structural integrity checks

Template Engine — 11 parameterized instruments

Rack Builder — Eurorack-style module assembly

MIDI Controller System — Hardware integration

Song Composer — Genre-driven rack generation

Live Control — OSC/FUDI messaging

VCV Rack Generator — .vcv patch files

Patch Analyzer — Deep structural analysis

Quick Start

1. Clone and build

2. Configure Claude Desktop

3. Use it

MCP Tools

parse_patch

generate_patch

validate_patch

analyze_patch

create_from_template

create_rack

compose_patch

send_message

list_vcv_modules

generate_vcv

MCP Prompts

song_analysis

Project Structure

Development

VCV Registry rebuild (only needed when plugins update)

Update README stats (tool/test counts)

Tech Stack

Roadmap

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Parser — Full AST from `.pd` files

Patch Generator — From JSON spec to valid `.pd`

VCV Rack Generator — `.vcv` patch files

`parse_patch`

`generate_patch`

`validate_patch`

`analyze_patch`

`create_from_template`

`create_rack`

`compose_patch`

`send_message`

`list_vcv_modules`

`generate_vcv`

`song_analysis`