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: Read-only MVP. The MCP server exposes 5 resources + 3 tools. No write tools are implemented (ADR-005). Empirically validated on StudioLive 32SC firmware 3.3.0.109659.

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:

Agents cannot change any mixer parameter yet (write tools are not implemented by design — see ADR-005).

Hardware requirements

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 all 3 tools and 5 resources at startup and runs background discovery.

MCP server — tools and resources

Tools

discover_mixers

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

// Input (all optional)
{ timeoutMs?: number }    // discovery window in ms; default 5000

// Output: JSON array of MixerIdentity
[{ deviceId, serial, model, firmware, role, ipAddress, port }]

refresh_mixer_state

Reconnect to a mixer and refresh its full state cache (including Fat Channel model decoding).

// Input
{ deviceId: string }    // from discover_mixers output

// Output
{ success: boolean, channelCount: number, capturedAt: string }

validate_mixer_identity

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

// Input
{
  deviceId:       string,
  expectedSerial?: string,
  expectedRole?:  "FOH" | "STAGEBOX" | "MONITOR" | "UNKNOWN"
}

// Output
{ valid: boolean, reasons: string[] }

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}/raw/state

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

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

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

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                   │
│  5 resources + 3 tools (read-only MVP)  │
└────────────────┬────────────────────────┘
                 │ 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 — set_fader, set_mute, apply_change_set (ADR-005 gating)

• AVB routing — AudioRouteSchema in domain is a stub

• 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

[Specify your license here]

🎯 Purpose

This repository provides:

• Standards-compliant software lifecycle management (IEEE/ISO/IEC)

• XP practices integration (TDD, Pair Programming, Continuous Integration)

• Phase-specific Copilot instructions with applyTo: patterns

• Spec-driven development templates using GitHub Spec-Kit

• Automated compliance checking and validation

📚 Standards Implemented

🚀 XP Practices Integrated

• Test-Driven Development (TDD) - Write tests first

• Continuous Integration - Integrate frequently

• Pair Programming - Collaborative development

• Simple Design - YAGNI principle

• Refactoring - Continuous improvement

• Collective Code Ownership - Shared responsibility

• User Stories - Effective use cases

📁 Repository Structure

copilot-instructions-template/
├── .github/
│   ├── copilot-instructions.md          # Root Copilot instructions
│   ├── workflows/                        # CI/CD automation
│   └── ISSUE_TEMPLATE/                   # Issue templates
│
├── 01-stakeholder-requirements/
│   ├── .github/copilot-instructions.md   # Phase-specific instructions
│   ├── stakeholders/                     # Stakeholder analysis
│   ├── business-context/                 # Business needs
│   └── templates/                        # Requirements templates
│
├── 02-requirements/
│   ├── .github/copilot-instructions.md
│   ├── functional/                       # Functional requirements
│   ├── non-functional/                   # Quality attributes
│   ├── use-cases/                        # Use case specifications
│   └── user-stories/                     # XP user stories
│
├── 03-architecture/
│   ├── .github/copilot-instructions.md
│   ├── decisions/                        # ADRs (Architecture Decision Records)
│   ├── views/                            # IEEE 42010 architecture views
│   ├── diagrams/                         # C4, UML diagrams
│   └── constraints/                      # Technical constraints
│
├── 04-design/
│   ├── .github/copilot-instructions.md
│   ├── components/                       # Component designs
│   ├── interfaces/                       # API specifications
│   ├── data-models/                      # Data structures
│   └── patterns/                         # Design patterns used
│
├── 05-implementation/
│   ├── .github/copilot-instructions.md
│   ├── src/                              # Source code
│   ├── tests/                            # Test-first XP tests
│   └── docs/                             # Code documentation
│
├── 06-integration/
│   ├── .github/copilot-instructions.md
│   ├── integration-tests/                # Integration test suites
│   ├── ci-config/                        # CI/CD configurations
│   └── deployment/                       # Deployment scripts
│
├── 07-verification-validation/
│   ├── .github/copilot-instructions.md
│   ├── test-plans/                       # IEEE 1012 test plans
│   ├── test-cases/                       # Detailed test cases
│   ├── test-results/                     # Test execution results
│   └── traceability/                     # Requirements traceability
│
├── 08-transition/
│   ├── .github/copilot-instructions.md
│   ├── deployment-plans/                 # Deployment strategies
│   ├── user-documentation/               # End-user guides
│   └── training-materials/               # Training resources
│
├── 09-operation-maintenance/
│   ├── .github/copilot-instructions.md
│   ├── monitoring/                       # Operations monitoring
│   ├── incident-response/                # Incident management
│   └── maintenance-logs/                 # Change logs
│
├── spec-kit-templates/
│   ├── requirements-spec.md              # IEEE 29148 templates
│   ├── design-spec.md                    # IEEE 1016 templates
│   ├── architecture-spec.md              # IEEE 42010 templates
│   ├── test-spec.md                      # IEEE 1012 templates
│   └── user-story-template.md            # XP user story template
│
├── standards-compliance/
│   ├── checklists/                       # Phase-specific checklists
│   ├── reviews/                          # Review reports
│   └── metrics/                          # Quality metrics
│
└── docs/
    ├── lifecycle-guide.md                # Complete lifecycle guide
    ├── xp-practices.md                   # XP implementation guide
    ├── copilot-usage.md                  # How to use Copilot instructions
    └── standards-reference.md            # Standards quick reference

🎓 How to Use This Template

1. Create New Project from Template

# Create repository from this template on GitHub
# OR clone and customize
git clone https://github.com/YOUR_ORG/copilot-instructions-template.git my-new-project
cd my-new-project

2. Initialize Your Project

# Update project-specific information
# Edit .github/copilot-instructions.md with your project details
# Customize templates in spec-kit-templates/

3. Follow the Lifecycle Phases

Start with Phase 01 and progress through each phase:

1. Stakeholder Requirements - Understand business needs

2. Requirements - Define what to build (IEEE 29148)

3. Architecture - Design system structure (IEEE 42010)

4. Design - Detail component design (IEEE 1016)

5. Implementation - Code with TDD (XP practices)

6. Integration - Continuous integration (XP)

7. Verification & Validation - Test thoroughly (IEEE 1012)

8. Transition - Deploy to production

9. Operation & Maintenance - Monitor and improve

4. Use Copilot with Phase Instructions

GitHub Copilot will automatically load phase-specific instructions based on the folder you're working in:

• Navigate to a phase folder (e.g., 02-requirements/)

• Copilot reads .github/copilot-instructions.md in that folder

• Get context-aware suggestions aligned with standards

5. Leverage Spec-Kit Templates

Use markdown specifications for AI-assisted development:

# Copy template for your feature
cp spec-kit-templates/requirements-spec.md 02-requirements/functional/feature-xyz.md

# Fill in the specification
# Use GitHub Copilot to generate code from spec

🤖 Copilot Instructions Features

ApplyTo Patterns

Copilot instructions use applyTo: patterns to target specific file types:

applyTo:
  - "02-requirements/**/*.md"
  - "02-requirements/**/use-cases/*.md"
  - "02-requirements/**/user-stories/*.md"

Standards Enforcement

Each phase enforces relevant standards:

## Standards Compliance
- IEEE 29148:2018 - Requirements specification format
- Traceability matrix required
- Review checklist completion mandatory

XP Practices Integration

## XP Practices
- Write user stories in Given-When-Then format
- Maintain story point estimates
- Track velocity

🎫 GitHub Issues Workflow

This template uses GitHub Issues as the primary traceability mechanism for all requirements, architecture decisions, and test cases. All artifacts are tracked as issues with bidirectional links.

Issue Types and Labels

Additional labels:

• Phase: phase:01-stakeholder-requirements, phase:02-requirements, etc.

• Priority: priority:critical, priority:high, priority:medium, priority:low

• Test Type: test-type:unit, test-type:integration, test-type:e2e, test-type:acceptance

• Status: status:draft, status:approved, status:implemented, status:verified

Traceability Patterns

All issues must include traceability links:

## Traceability
- Traces to:  #123 (parent StR issue)
- **Depends on**: #45, #67 (prerequisite requirements)
- **Verified by**: #89, #90 (test issues)
- **Implemented by**: #PR-15 (pull request)
- **Refined by**: #234, #235 (child requirements)

Issue Templates

Issue templates are available in .github/ISSUE_TEMPLATE/:

• stakeholder-requirement.yml

• functional-requirement.yml

• non-functional-requirement.yml

• architecture-decision.yml

• architecture-component.yml

• quality-scenario.yml

• test-case.yml

Workflow Examples

1. Create Stakeholder Requirement Issue

# Using GitHub CLI
gh issue create \
  --title "StR-001: User Authentication" \
  --label "type:stakeholder-requirement,phase:01-stakeholder-requirements,priority:critical" \
  --body "$(cat issue-body.md)"

2. Create Functional Requirement from StR

## Traceability
- Traces to:  #1 (StR-001: User Authentication)

## Description
System shall allow users to log in with username and password.

## Acceptance Criteria
- [ ] User can enter username and password
- [ ] System validates credentials
- [ ] User is redirected to dashboard on success
- [ ] Error message displayed on failure

3. Link Code to Issues

"""
User authentication service.

Implements: #2 (REQ-F-AUTH-001: User Login)
Architecture: #5 (ADR-SECU-001: JWT Authentication)
Verified by: #10 (TEST-AUTH-LOGIN-001)

See: https://github.com/org/repo/issues/2
"""
class AuthenticationService:
    pass

4. Link Tests to Requirements

"""
Test user login functionality.

Verifies: #2 (REQ-F-AUTH-001: User Login)
Test Type: Integration
Priority: P0 (Critical)
"""
def test_user_login_success():
    # Test implementation

5. Link Pull Requests

## Description
Implements user authentication feature

## Related Issues
Fixes #2
Implements #5
Part of #1

## Traceability
- **Requirements**: #2 (REQ-F-AUTH-001)
- **Design**: #5 (ADR-SECU-001)
- **Tests**: #10 (TEST-AUTH-LOGIN-001)

Python Automation Scripts

Available in scripts/:

• generate-traceability-matrix.py - Generate REQ↔TEST↔CODE matrix

• trace_unlinked_requirements.py - Find requirements without tests

• validate-traceability.py - Validate bidirectional links

• scripts/generate-requirement-issues.py - Generate REQ issues from specs

• scripts/generate-test-issues.py - Generate TEST issues from requirements

• scripts/validate-issue-traceability.py - Validate GitHub Issues traceability

Example usage:

# Find requirements without tests
python scripts/trace_unlinked_requirements.py

# Validate traceability
python scripts/validate-traceability.py

# Generate traceability matrix
python scripts/generate-traceability-matrix.py --output-html

CI/CD Integration

GitHub Actions workflows validate traceability:

# .github/workflows/validate-traceability.yml
name: Validate Traceability
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate issue links
        run: python scripts/validate-issue-traceability.py
      - name: Check test coverage
        run: python scripts/validate-trace-coverage.py
      - name: Generate matrix
        run: python scripts/generate-traceability-matrix.py

Best Practices

1. Always create issues before code - No code without linked issue

2. Use bidirectional links - Parent issues list children, children reference parents

3. Link PRs to issues - Use Fixes #N, Implements #N, Part of #N

4. Include issue references in code - Docstrings, comments, commit messages

5. Validate traceability in CI - Block merges if links are missing

6. Keep issues up-to-date - Close when implemented and verified

7. Use labels consistently - Enables automated queries and reports

Querying Issues

# List all functional requirements
gh issue list --label "type:requirement:functional"

# Find requirements without tests
gh issue list --label "type:requirement:functional" --json number,title,labels \
  | jq '.[] | select(.labels | map(.name) | contains(["status:verified"]) | not)'

# Show traceability for requirement #2
gh issue view 2 --json body | jq -r '.body' | grep -A 10 "## Traceability"

# List all open architecture decisions
gh issue list --label "type:architecture:decision" --state open

🔍 Quality Assurance

Automated Checks

• Standards compliance checking via GitHub Actions

• Requirements traceability validation (GitHub Issues API)

• Test coverage enforcement (XP: >80%)

• Documentation completeness checks

• Issue link validation (bidirectional traceability)

Review Gates

Each phase includes:

• ✅ Entry criteria checklist

• ✅ Phase activities checklist

• ✅ Exit criteria validation

• ✅ Standards compliance review

• ✅ Traceability validation (all requirements have tests)

📖 Documentation

• Lifecycle Guide - Complete walkthrough of all phases

• XP Practices Guide - How to apply XP techniques

• Copilot Usage Guide - Maximizing Copilot effectiveness

• Standards Reference - Quick reference to all standards

🛠️ Customization

Adding Custom Phases

1. Create folder: XX-custom-phase/

2. Add .github/copilot-instructions.md

3. Define applyTo patterns

4. Update root copilot-instructions.md

Extending Templates

1. Add templates to spec-kit-templates/

2. Follow Spec-Kit markdown format

3. Include standards references

4. Add examples

🤝 Contributing

This template is designed to be:

• Forked for your organization

• Customized to your processes

• Extended with your practices

• Shared with your teams

📄 License

[Specify your license here]

🔗 References

• GitHub Spec-Kit

• Spec-Driven Development Blog Post

• ISO/IEC/IEEE Standards

• Extreme Programming Explained (Kent Beck)

🚀 Get Started

Ready to build standards-compliant software with AI assistance? Start with Phase 01!