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

{
  "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 }
  ]
}

{
  "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" }
  ]
}

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

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

{
  "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" } }
  ]
}

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

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

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

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

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

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

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