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). Verified on StudioLive 32SC (firmware 3.3.0.109659 and 3.4.0.111374) and StudioLive 32R (firmware 3.4.0.111374) — read-only baseline observed on both. Channel mute write is HIL-verified on 32SC only. Other StudioLive III models are unverified/experimental. Some routing and Fat Channel parameter values are confidence-tagged as inferred or probe_required. Write tools are disabled by default.

>

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:

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

Hardware validation status

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

v0.1 capability matrix

Confidence labels follow the repository vocabulary: observed = confirmed from live hardware; calibrated_inferred = formula calibrated on at least one device but not independently confirmed on this model; inferred = derived from code/pattern without calibration; probe_required = requires targeted hardware probe before promotion.

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 --frozen-lockfile   # installs all workspace packages
pnpm build                       # compiles all 4 packages

Configure your mixer

Set environment variables before starting the server:

# The mixer's IP address (required)
export PRESONUS_IP=192.168.1.50

# TCP port (default: 53000 — same as UC Surface)
export PRESONUS_PORT=53000

# Strongly recommended: serial number to lock identity
# Run `pnpm probe:dev discover` to find the serial for your mixer
export PRESONUS_SERIAL=<id.hidden>

# Optional: expected role (FOH | STAGEBOX | MONITOR | UNKNOWN)
export PRESONUS_ROLE=FOH

On Windows PowerShell:

$env:PRESONUS_IP="192.168.1.50"
$env:PRESONUS_PORT="53000"
$env:PRESONUS_SERIAL="<id.hidden>"
$env:PRESONUS_ROLE="FOH"

Setting PRESONUS_SERIAL is strongly recommended. It prevents the server from silently using a different mixer if discovery returns multiple devices or the IP changes.

Connect from Claude Desktop (primary tested MCP client)

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "presonus-studiolive": {
      "command": "node",
      "args": ["<absolute-path-to-repo>/packages/presonus-mcp-server/dist/index.js"],
      "env": {
        "PRESONUS_IP": "192.168.1.50",
        "PRESONUS_SERIAL": "<id.hidden>"
      }
    }
  }
}

Replace <absolute-path-to-repo> with the actual path. Claude Desktop launches the server via stdio on startup.

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "presonus-studiolive": {
      "type": "stdio",
      "command": "node",
      "args": ["<absolute-path-to-repo>/packages/presonus-mcp-server/dist/index.js"],
      "env": {
        "PRESONUS_IP": "192.168.1.50",
        "PRESONUS_SERIAL": "<id.hidden>"
      }
    }
  }
}

Read-only workflow

Once connected, an AI agent can follow this sequence:

discover_mixers                      → find mixer on LAN (or use configured fallback)
validate_mixer_identity              → confirm expected serial matches
refresh_mixer_state                  → force fresh state from mixer
presonus://mixer/{deviceId}/channels → read channel names, mute, fader, Fat Channel models
get_mixer_capabilities               → know mixer capacity (inputs, aux mixes, FX buses)

Write opt-in (32SC channel mute only — disabled by default)

⚠️ Writes are disabled by default. Enabling writes allows the server to change real mixer state. v0.1 supported mutation: channel mute on StudioLive 32SC only. Do not enable writes during live performance unless you understand the change workflow.

Enable writes by setting:

export PRESONUS_WRITE=1

In your MCP client config env block:

"env": {
  "PRESONUS_IP": "192.168.1.50",
  "PRESONUS_SERIAL": "<id.hidden>",
  "PRESONUS_WRITE": "1"
}

Supported write workflow:

prepare_mute_change_set              → propose mute state change (no mixer write yet)
validate_change_set                  → confirm proposal is valid and not expired
apply_change_set (dryRun: true)      → preview without writing
apply_change_set (confirmationNote)  → apply to hardware; returns fresh state + rollbackHint

The change set expires after 60 seconds. Only one proposal per channel is active at a time. Every applied change is written to the audit log on stderr.

Probe the hardware (optional but recommended for first use)

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

Uses @featherbear/presonus-studiolive-api 1.9.1. No active patch — 1.9.1 includes I (int16) UBJSON type support natively. The stale patches/@[email protected] artifact remains in the repository for historical reference but is not applied.

@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](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.

\* 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>.

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 workspace packages
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

#### 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. <id.hidden>

# 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:

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 1.9.1 as hardware adapter (no active patch; v1.8.0 patch artifact in patches/ is stale)
• ADR-005 — Read-only-first; write operations require a ProposedChangeSet + audit log + confirmation flow before being enabled

Known gaps / future work

• Write tools (v0.1) — prepare_mute_change_set + apply_change_set are available when PRESONUS_WRITE=1. Only channel mute is HIL-verified on 32SC. EQ, fader, and Fat Channel writes are hard-disabled pending calibration.
• 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.