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

Related MCP server: OSC MCP Server

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.

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.

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

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:

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.