presonus-studiolive-mcp

presonus-studiolive-mcp

An MCP (Model Context Protocol) server that connects AI coding agents and assistants to PreSonus StudioLive III series mixers over the local network.

Exposes live mixer context — channel names, mute/solo/fader state, Fat Channel compressor/EQ models, meter activity, and scene information — as MCP resources and tools so that AI agents can read, reason about, and assist with live sound engineering without touching hardware autonomously.

Current status: Experimental read-mostly backend (v0.1.0). Primary empirical inspection on StudioLive 32SC firmware 3.3.0.109659. Other StudioLive III models are expected-compatible but require additional HIL testing. Some routing and Fat Channel parameter values are confidence-tagged as inferred or probe_required. Write tools are gated and experimental. See docs/capability-matrix.generated.md for the current generated MCP tool/resource inventory.

---

Contents

• What this does
• Hardware requirements
• Quick start
• Packages
• MCP server — tools and resources
• Probe CLI
• Fat Channel skill
• Development
• Architecture

---

What this does

The MCP server gives an AI agent these capabilities:

| Capability | How | |---|---| | Discover mixers on the network | discover_mixers tool | | Verify FOH vs. stagebox identity | validate_mixer_identity tool | | Refresh state cache on demand | refresh_mixer_state tool | | Read channel names, mute, solo, fader, pan, color, Fat Channel models | presonus://mixer/{id}/channels resource | | Read per-channel Fat Channel DSP state (EQ, comp, gate, limiter) | get_fat_channel tool / presonus://mixer/{id}/fat-channel/{id} resource | | Validate Fat Channel settings for a source type | validate_fat_channel_for_source tool | | Know mixer capacity (inputs, aux mixes, FX buses, stagebox) | get_mixer_capabilities tool | | Validate rider capacity requirements | check_required_setup tool | | Validate expected channel names, phantom, mute | validate_channel_setup tool | | Validate an agent-provided input list against the mixer | validate_input_list_against_mixer tool | | Validate a patch sheet for conflicts and range issues | validate_patch_sheet tool | | Render a structured patch sheet for human printing | render_patch_sheet_data tool | | Monitor signal activity (silent / active / hot / clipping) | presonus://mixer/{id}/meters/summary resource | | Know which project and scene are loaded | presonus://mixer/{id}/scene/current resource | | Diagnose a single channel (mute, fader, gate, signal) | diagnose_channel tool | | Run a line-check step and observe meter results | analyze_line_check_step tool | | Detect possible patch swaps during line check | detect_possible_patch_swap tool | | Diagnose no-signal routing causes | diagnose_no_signal_routing tool | | Inspect observable routing (AUX/FX/sub/main sends) | get_routing_graph tool / presonus://mixer/{id}/routing resource | | Validate input routing (Layer A: name, meter, mute) | validate_input_routing tool | | Validate stagebox connection | validate_stagebox_routing tool | | Inspect output patch router (source index) | presonus://mixer/{id}/routing/outputs resource | | Inspect AUX mixes (master, sends, levels) | get_aux_mix tool / presonus://mixer/{id}/auxes resource | | Validate monitor send requirements | validate_monitor_requirements tool | | Find missing / muted / hot monitor sends | find_missing_monitor_sends, find_muted_monitor_sends, find_hot_monitor_sends tools | | Full aux mix audit | validate_aux_mix tool | | Inspect FX send routing | presonus://mixer/{id}/fx-sends resource | | Inspect flat channel-to-aux routing graph | presonus://mixer/{id}/monitor-routing resource | | Raw diagnostic state dump | presonus://mixer/{id}/raw/state resource | | Propose and apply an EQ change (write-enabled only) | propose_eq_change + apply_change_set tools |

By default agents cannot change mixer parameters. Write tools require writeEnabled: true and use a ProposedChangeSet workflow with 60 s TTL and operator confirmation — see ADR-006. All write tool responses include a changeSetConfidence field (observed / inferred / guessed) indicating how well-calibrated the proposed values are.

---

Hardware requirements

| Requirement | Details | |---|---| | Mixer | PreSonus StudioLive III series (16, 16R, 24R, 32SC, 32R) | | Network | Mixer and MCP server host on the same LAN segment | | Protocol | TCP port 53000 (UC Surface / Studio One Remote protocol) | | Coexistence | UC Surface, QMix-UC, and this server can connect simultaneously | | Internet | Not required |

Hardware validation status

| Model | Status | |---|---| | StudioLive 32SC firmware 3.3.0.109659 | Empirically inspected — state capture validated, routing and Fat Channel partially probed | | StudioLive 32R | Expected-compatible (same protocol); requires HIL testing to confirm | | StudioLive 24R | Expected-compatible; requires HIL testing to confirm | | StudioLive 16R | Expected-compatible; requires HIL testing to confirm | | StudioLive 16 | Expected-compatible; requires HIL testing to confirm |

See docs/release-readiness-checklist.md for gates required before any model is claimed as validated or production-ready.

---

Quick start

Prerequisites

• Node.js 20+
• pnpm 9+

Install and build

git clone https://github.com/zarfld/presonus-studiolive-mcp.git
cd presonus-studiolive-mcp
pnpm install          # installs all workspace packages + applies featherbear patch
pnpm build            # compiles all 4 packages

Run the MCP server (stdio transport)

pnpm mcp:server

Or without a prior build, using tsx:

pnpm mcp:server:dev

The server logs to stderr, connects to discovered mixers on startup, and accepts MCP requests on stdin/stdout.

Connect from Claude Desktop / VS Code

Add to your MCP client config:

{
  "mcpServers": {
    "presonus-studiolive": {
      "command": "node",
      "args": ["<absolute-path>/packages/presonus-mcp-server/dist/index.js"]
    }
  }
}

Probe the hardware first (optional but recommended)

pnpm probe:dev discover             # find mixers on your LAN
pnpm probe:dev dump-state -d <ip>   # dump full state tree to captures/
pnpm probe:dev probe-fat-channel -d <ip> -c LINE:1   # inspect Fat Channel state for ch1

---

Packages

This is a pnpm monorepo with four packages under packages/. Dependencies flow one way: domain ← adapter ← inspector | server.

@presonus-mcp/domain

Pure TypeScript/Zod schema library — the single source of truth for all data contracts.

• MixerIdentitySchema — deviceId, serial, IP, port, role, controllable
• MixerChannelSchema — name, mute, solo, fader (dB/linear/raw), pan, color, compModelName, eqModelName
• MeterSummarySchema — time-windowed channel activity classification
• FatCompressorStateSchema / FatEqStateSchema — discriminated unions per model
• COMPRESSOR_MODEL_BY_CLASSID / EQ_MODEL_BY_CLASSID — full GUID → model name maps for scene file decoding
• decodeCompressorModel(value) / decodeEqModel(value) — live state float → model name helpers

No runtime dependency on featherbear or the MCP SDK.

@presonus-mcp/adapter

Hardware adapter wrapping @featherbear/presonus-studiolive-api. Manages connections, state, and meters.

• discoverMixers({ timeoutMs? }) — UDP broadcast discovery
• PresonusClientManager — connects/disconnects clients; provides getSnapshot(), getIdentity(), getSummarizer()
• flattenFeatherbearState() — converts featherbear's nested _data.internal.children.* tree to flat dot-notation keys
• PresonusMeterSummarizer — ring-buffer of raw uint16 meter packets → time-windowed MeterSummary
• mapRawStateToSnapshot() — translates flat state keys to normalized MixerSnapshot

The featherbear dependency is patched (patches/@featherbear__presonus-studiolive-api@1.8.0.patch) to add UBJSON I (int16) and D (float64) type support missing from the original.

@presonus-mcp/inspector

Probe CLI binary (presonus-probe) for hardware reconnaissance during development. See Probe CLI.

@presonus-mcp/server

MCP server that wires the adapter to the MCP SDK over stdio transport. Registers resources and tools at startup (write tools registered only when writeEnabled: true). Runs background mixer discovery.

See docs/capability-matrix.generated.md for the current generated tool and resource inventory.

---

MCP server — tools and resources

Tools

The current tool and resource inventory is generated from source — see docs/capability-matrix.generated.md.

Write tools are registered only when writeEnabled: true (default: false). All write tools use the ProposedChangeSet workflow (propose → 60 s TTL → apply) and include a changeSetConfidence field so operators know how well-calibrated the proposed values are.

| Group | Tools | |---|---| | Discovery / identity | discover_mixers, refresh_mixer_state, validate_mixer_identity | | Capabilities | get_mixer_capabilities, check_required_setup | | Channel setup | validate_channel_setup, diagnose_channel | | Input list / patch sheet | validate_input_list_against_mixer, validate_patch_sheet, render_patch_sheet_data | | Fat Channel inspection | get_fat_channel, validate_fat_channel_for_source | | Line check | analyze_line_check_step, detect_possible_patch_swap | | Routing | get_routing_graph, validate_input_routing, validate_stagebox_routing, diagnose_no_signal_routing, get_input_routing\, validate_avb_routing\, validate_output_routing† | | Monitor / aux | get_aux_mix, validate_monitor_requirements, find_missing_monitor_sends, find_muted_monitor_sends, find_hot_monitor_sends, validate_aux_mix | | Write (gated) | propose_eq_change, apply_change_set |

\* Layer B stub — returns not_verifiable_with_current_adapter with probe instructions. † Layer B partial — source index known; source name requires probe.

discover_mixers

Trigger UDP discovery of StudioLive III mixers on the local network.

{ timeoutMs?: number }    // discovery window in ms; default 5000
// → [{ deviceId, serial, model, firmware, role, ipAddress, port }]

validate_mixer_identity

Verify a connected mixer matches expected serial and/or role before proceeding.

{ deviceId: string, expectedSerial?: string, expectedRole?: "FOH"|"STAGEBOX"|"MONITOR"|"UNKNOWN" }
// → { valid: boolean, reasons: string[] }

validate_input_list_against_mixer

Validate an agent-provided input list against actual mixer state. Returns name mismatches, phantom mismatches, mute issues, and printable patch rows.

{
  deviceId: string,
  inputList: [{ inputNo: number, sourceName: string, phantomRequired: boolean, micPreference?: string, notes?: string }]
}
// → { status: "ok"|"warning"|"error", issues[], printablePatchRows[] }

get_fat_channel

Return the Fat Channel DSP state (EQ, compressor, gate, limiter, HPF) for a single channel.

{ deviceId: string, channelId: string }   // channelId e.g. "line.ch1"
// → ChannelFatState (eqModel, compModel, eqBands, comp, gate, limiter, hpfFrequencyHz)

validate_fat_channel_for_source

Check Fat Channel settings against source-type expectations (HPF engaged, gate enabled, comp enabled, limiter enabled).

{ deviceId: string, channelId: string, sourceType: "vocal"|"kick"|"snare"|"bass"|... }
// → { checks: [{ check, passed, detail }], warnings: string[], parameterConfidence }

---

Resources

presonus://mixers

All connected mixer identities.

presonus://mixer/{deviceId}/channels

Normalized channel list. Each channel includes:

{
  id:             string,       // "line.ch1", "aux.ch3", "sub.ch1", …
  selector:       { type, channel },
  name?:          string,       // label from mixer (e.g. "Kick In")
  mute?:          boolean,
  solo?:          boolean,
  fader?:         { db: number|null, linear: number|null },
  pan?:           number,       // 0.0 left … 0.5 center … 1.0 right
  linked?:        boolean,
  color?:         string,       // RGBA hex

  // Fat Channel — decoded from live opt.compmodel / opt.eqmodel
  compModelName?: string,       // e.g. "FET", "BRIT_COMP", "FC_670"
  eqModelName?:   string        // e.g. "STANDARD", "ALPINE_EQ_550", "SOLAR_69_EQ"
}

presonus://mixer/{deviceId}/meters/summary

Time-windowed meter classification (last 10 seconds):

{
  windowSec:            number,
  computedAt:           string,       // ISO 8601
  silentChannels:       string[],     // channel ids with no signal
  activeChannels:       string[],     // signal in normal range
  hotChannels:          string[],     // approaching clip
  clippingChannels:     string[],     // at or above clip threshold
  noSignalButExpected:  string[],
  signalButUnexpected:  string[]
}

presonus://mixer/{deviceId}/scene/current

{
  currentProject:    string | null,
  currentScene:      string | null,
  availableProjects: string[]
}

presonus://mixer/{deviceId}/routing

Per-channel AUX/FX/subgroup/main-LR send routing. parameterConfidence: 'inferred' until AUX fader de-normalization is probe-confirmed.

presonus://mixer/{deviceId}/routing/outputs

Output patch router — source index known for each analog/AVB output; sourceName: null until probe confirms source → index mapping.

presonus://mixer/{deviceId}/auxes

All aux mixes: master level/mute + per-channel send levels. prePost: 'unknown' until hardware probing confirms.

presonus://mixer/{deviceId}/fx-sends

Per-channel FX bus send state.

presonus://mixer/{deviceId}/monitor-routing

Flattened channel-to-aux routing graph for monitor mix planning.

presonus://mixer/{deviceId}/fat-channel/{channelId}

Fat Channel DSP state for a single channel (EQ, compressor, gate, limiter, HPF, model names). Use get_fat_channel tool instead when querying programmatically.

presonus://mixer/{deviceId}/raw/state

Full raw state dump (pre-normalized flat dot-notation). For diagnostics and development only — do not use for agent reasoning logic.

Layer A / Layer B routing model: Layer A resources and tools return data directly observable from confirmed state keys. Layer B tools (get_input_routing, validate_avb_routing) return not_verifiable_with_current_adapter and include probe instructions — physical cable routing and AVB stream assignments cannot be verified by software alone.

---

Probe CLI

presonus-probe is the hardware reconnaissance tool used during development. Run via pnpm probe:dev <command>.

| Command | Purpose | |---|---| | discover | Find all StudioLive III mixers on the LAN; print serial/model/IP/role | | dump-state -d <ip> | Connect and dump full flat state tree as JSON to captures/ | | watch-events -d <ip> | Stream all featherbear data events as NDJSON | | watch-meters -d <ip> | Capture raw meter stream as NDJSON | | diff-state --before <f> --after <f> | Compare two state dumps; identify changed keys (workflow: change one control → dump-state → diff → name the key) | | probe-fat-channel -d <ip> -c <TYPE:N> | Dump all Fat Channel state keys for a channel (e.g. LINE:1) | | read-scene -d <ip> | List projects and scenes stored on the mixer |

Note: Scene file content (__classid GUIDs) is not accessible over the network API — it returns 0 bytes. Fat Channel model identity must be read from live state via opt.compmodel.value / opt.eqmodel.value.

---

Fat Channel skill

A VS Code / Copilot skill is included at .github/Skills/PresonusFatChannelSelection/SKILL.md.

It gives AI agents:

• Character, hardware archetype, best-use, and avoid-when for all 11 compressor models (STANDARD, TUBE, FET, BRIT_COMP, CLASSIC_COMPRESSOR, COMP_160, EVEREST_C100A, FC_670, RC_500_COMPRESSOR, TUBE_CB, VT_1_COMPRESSOR)
• Character and use-case guidance for all 10 EQ models (STANDARD, PASSIVE, VINTAGE, ALPINE_EQ_550, BAXANDALL_EQ, RC_500_EQ, SOLAR_69_EQ, TUBE_EQ, VINTAGE_3_BAND_EQ, VT_1_EQ)
• Quick-reference selector tables (source instrument → recommended model)
• Decision framework for choosing between transparency, punch, warmth, and bus treatment
• Full __classid GUID reference for all models (from classID_Mapping.md, empirically confirmed on 32SC firmware 3.3.0.109659)
• Exact MCP resource/tool schemas and accepted property lists per model

---

Development

Commands

pnpm install          # install + apply featherbear patch
pnpm build            # compile all packages
pnpm build:watch      # watch mode
pnpm clean            # remove all dist/ and tsbuildinfo

pnpm test             # unit tests (no hardware needed)
pnpm test:watch       # watch mode
pnpm test:coverage    # with coverage report
pnpm test:hil         # hardware-in-loop tests (requires HIL_PRESONUS=1 + physical mixer)

pnpm typecheck        # tsc dry-run

pnpm probe:dev discover                            # discover mixers
pnpm probe:dev dump-state -d <mixer-ip>            # capture state
pnpm probe:dev probe-fat-channel -d <ip> -c LINE:1 # inspect channel

pnpm mcp:server:dev   # run MCP server (tsx, no build needed)
pnpm mcp:server       # run MCP server (compiled dist/)

Test strategy

| Test type | Command | Requires hardware | |---|---|---| | Unit (schema/adapter logic) | pnpm test | No | | HIL (hardware-in-loop) | pnpm test:hil | Yes — see below |

HIL test setup

HIL tests require a physical StudioLive III mixer on the local network. Set the following environment variables before running pnpm test:hil:

# Required
export HIL_PRESONUS=1                        # enables HIL test suite
export HIL_PRESONUS_IP=<mixer-ip-address>    # e.g. 192.168.1.50
export HIL_PRESONUS_SERIAL=<serial-number>   # e.g. SD7E21010066

# Then run
pnpm test:hil

On Windows PowerShell:

$env:HIL_PRESONUS="1"
$env:HIL_PRESONUS_IP="<mixer-ip>"
$env:HIL_PRESONUS_SERIAL="<serial>"
pnpm test:hil

Unit tests cover all domain schemas, decode functions, flattenFeatherbearState, and PresonusMeterSummarizer using captured fixture data from captures/.

GitHub issue model and traceability

All requirements, architecture decisions, and test cases are tracked as GitHub issues following this taxonomy:

| Prefix | Type | Example | |---|---|---| | StR-NNN | Stakeholder requirement | #1–#4 | | REQ-F- | Functional requirement | #15–#46 | | REQ-NF- | Non-functional requirement | #21–#24 | | ADR- | Architecture decision | #47 | | QA-SC- | Quality attribute scenario | #25–#27, #49–#50 | | TEST-* | Verification test case | #51–#60, #80–#83 |

Issues are organized into milestones v0.1–v1.0. See the GitHub Issues tab for the full traceability register.

Adding a new raw state key

1. pnpm probe:dev dump-state -d <ip> before and after changing a control in UC Surface
2. pnpm probe:dev diff-state --before <before.json> --after <after.json> — identifies the changed key
3. Add the constant to packages/presonus-adapter/src/types.ts
4. Map it in mapRawStateToSnapshot() or expose via rawExtra
5. Add a unit test with a fixture snapshot

---

Architecture

Three-layer architecture (ADR-002):

┌─────────────────────────────────────────┐
│  AI Agent / MCP Client                  │
│  (Claude Desktop, VS Code, custom)      │
└────────────────┬────────────────────────┘
                 │ stdio (MCP protocol)
┌────────────────▼────────────────────────┐
│  @presonus-mcp/server                   │
│  See docs/capability-matrix.generated.md │
└────────────────┬────────────────────────┘
                 │ internal API
┌────────────────▼────────────────────────┐
│  @presonus-mcp/adapter                  │
│  PresonusClientManager                  │
│  flattenFeatherbearState()              │
│  PresonusMeterSummarizer                │
└────────────────┬────────────────────────┘
                 │ TCP 53000 (UC Surface protocol)
┌────────────────▼────────────────────────┐
│  StudioLive III mixer                   │
│  (32SC, 32R, 24R, 16R, 16)             │
└─────────────────────────────────────────┘

Domain schemas (@presonus-mcp/domain) sit outside this stack and are imported by both adapter and server — never the other way round.

Key decisions:

• ADR-001 — TypeScript/Node.js 20+
• ADR-002 — Three-layer architecture above
• ADR-003 — pnpm monorepo, 4 packages
• ADR-004 — @featherbear/presonus-studiolive-api v1.8.0 pinned + patched as hardware adapter
• ADR-005 — Read-only-first; write operations require a ProposedChangeSet + audit log + confirmation flow before being enabled

Known gaps / future work

• Write tools — propose_eq_change + apply_change_set are available (write-enabled mode). Extended change-set framework (rename, mute, fader, aux send, comp/gate/limiter) planned.
• Layer B routing — Physical input source routing and AVB stream routing require probe-diff sessions (probe-routing diff --kind input-source/avb-stream). get_input_routing and validate_avb_routing return probe instructions.
• Output patch source names — validate_output_routing knows source indices but not names; probe-diff with --kind bus-to-output needed.
• Stereo IEM pair model — Monitor layout and stereo-pair validation planned (Phase 4).
• Show prep layer — ShowInputSchema is a stub (rider analysis, channel template suggestions).
• Scene file access — __classid GUIDs not accessible over network; only live state model IDs available.
• HIL test coverage — tests with *.hil.test.ts require a physical mixer.

---

License

MIT — see LICENSE.