Salban Server

This is the official Model Context Protocol (MCP) server for the SAL BAN Monolith Engine, a powerful, cutting-edge in-browser synthesizer and groovebox.

This MCP server acts as a local WebSocket bridge, allowing agentic AI coding assistants (such as Claude Desktop, Cursor, or Antigravity) to directly program sequences, tweak synthesizer parameters, load audio samples, and interact with the Monolith Engine in real-time.

---

🎛️ The Monolith Engine Modules & MCP Integration

While this repository focuses on the secure MCP WebSocket Server, here is a brief overview of the Monolith Engine modules that you can control. You can experience the complete interactive synthesizer live on salban.de.

What makes the MCP Integration so unique?

Traditional music software relies on complex MIDI mappings, local file transfers, or closed scripting languages. The SAL BAN MCP integration breaks these barriers by exposing the entire synth state and sequencer controls as natural language tools to AI models. This allows an AI agent to:

• Code complex arpeggios, Goa trance rolling basslines, or syncopated breaks on the fly using standard programming loops.
• Programmatically synthesize new raw waveforms in Node.js and load them directly into the browser's audio buffer (e.g., custom drums or sweeps).
• Tweak synthesis knobs (cutoff, resonance, LFO speed) dynamically based on natural language commands (e.g., "make it squelchier" or "slow down the tempo").

---

Core Synthesizer Modules

🎹 Synth Voices Block Dual-voice synthesizer consisting of a dedicated Bassline and Lead synth engine, utilizing sawtooth, square, triangle, sine, and custom wavetable waveforms with resonant filters.	🥁 Drum Voices Block Dedicated analog-style drum synthesizers for Kick, Snare, and Hat with fine-tunable pitch, decay, and accent parameters.
🎙️ Phrase & One-Shot Samplers An 8-pad sampler featuring phrase looping and one-shot playback capabilities. Supports real-time sample loading via Base64 injection from the AI client.	🎛️ LFO Modulation Matrix A multi-slot LFO matrix permitting routing of sine, triangle, saw, square, and sample-and-hold modulators to filter cutoffs, levels, fuzz, or panning.
🎚️ Mixer & Studio FX Control A multi-channel mixer with levels, panning, and aux sends routing into studio-grade return effects (Fuzz distortion, Delay, and Reverb).	🎼 Step Sequencer & Patch Center A 16-step sequencer pattern grid for all drums, synths, and samplers, backed by preset patch loading and real-time transport sync.
🥁 One-Shot Sampler & Editor An 8-pad One-Shot Sampler featuring custom sample recording, local file uploading, and a precision waveform editor to adjust pitch, reverse playback, volume, and trigger sequences.	🎼 Song Mode (Song Preset Sequencer) A multi-pad Song Preset Sequencer allowing users or the AI to capture live groove states, assign custom repeat counts, and automate structured song arrangements using Auto-Chain playback directions (Forward, Reverse, Ping-Pong, and Random).
🎹 Clip Launcher & Piano Roll A full DAW-style Clip Launcher with 3 tracks × 5 scenes and a built-in Piano Roll for polyphonic MIDI note editing. Supports real-time recording in Overdub and Replace modes, chord input, note quantization, and clip length settings in bars and beats.	🥁 Drum Auto-Tune Intelligent pitch-tracking for all drum voices: Kick, Snare, and Hat can automatically follow the pitch of the Bassline, Lead, or Morph32 sequences in real-time using a per-voice frequency folding formula (Snare: 10th overtone → 2000–5000 Hz).
🎛️ Morph32 Polyphonic Synthesizer An 8-voice polyphonic synthesizer with dual oscillators (sawtooth, square, triangle, sine, noise, wavetable), a main resonant filter, a stereo dual-filter matrix with key-tracking and spacing modulation, full ADSR amplitude and filter envelopes, ring modulation, portamento, and a polyphonic step sequencer that supports chord input per step.

---

📐 Architecture & Data Flow

The integration runs entirely on the user's local machine, establishing a secure loopback connection between the browser, the sandboxed Docker container, and the AI client.

graph TD
    subgraph Browser ["Web Browser (User's System)"]
        Site["https://salban.de (Monolith Engine)"]
        JS["Web Audio API & Sequencer UI"]
    end

    subgraph local_mcp ["Local Docker Sandbox (USER node)"]
        WS["WebSocket Server (port 8080)"]
        Verify["Strict verifyClient: Origin Check / Max Conn Limit / Optional Token"]
    end

    subgraph LLM_Client ["AI Client (e.g. Claude Desktop, Cursor)"]
        Agent["LLM Coding Assistant"]
        Stdio["Stdio Transport Connection"]
    end

    %% Data Flow Connections
    Site <-->|WS Local Loopback: localhost:8080| Verify
    Verify <-->|Secure Channel| WS
    WS <-->|JSON-RPC via Stdio| Stdio
    Stdio <-->|Tools Interface| Agent
    
    %% Styling
    classDef browser fill:#051d36,stroke:#00e5ff,stroke-width:2px,color:#fff;
    classDef docker fill:#1f2937,stroke:#00e5ff,stroke-width:2px,color:#fff;
    classDef client fill:#111827,stroke:#00e5ff,stroke-width:2px,color:#fff;
    class Browser browser;
    class local_mcp docker;
    class LLM_Client client;

---

🔒 Security & Hardening by Design

Because the MCP server runs locally and connects to a public web interface, it is built with strict security measures to protect end-users:

1. Docker Sandbox: The server runs inside an unprivileged environment (USER node) instead of root. Compiled files inside /app are set to read-only (755 owned by root:root) to prevent post-exploitation modification of execution binaries.
2. Strict Origin Validation: The WebSocket server strictly validates HTTP Origin headers, allowing connections only from https://salban.de and authorized local development hosts (e.g. localhost:3000). All other connection attempts (e.g., malicious background tabs) are rejected immediately with a 403 Forbidden response.
3. Connection Rate Limiting: Limits connections to a maximum of 2 concurrent active WebSocket sockets to prevent denial-of-service (DoS) exploits.
4. Payload Size Restriction: Limits incoming frame sizes strictly to 15MB.
5. Flexible Token Protection (Pro-Mode):
   • By default, it operates in a Hybrid No-Token Mode for a frictionless out-of-the-box experience.
   • For maximum security (e.g. preventing unauthorized local host scripts from accessing the bridge), you can activate Token Pro-Mode by setting the SALBAN_MCP_TOKEN environment variable. When set, clients must pass this token during the WebSocket handshake.

---

⚖️ GDPR (DSGVO) & EU AI Act Compliance

This project is built from the ground up to respect user privacy and comply with European regulatory frameworks.

🇪🇺 GDPR / DSGVO Compliance (Privacy by Design - Art. 25)

• No Processing of Personal Data (PII): The MCP server processes only technical telemetry and synthesis variables (tempo, notes, pitches, mute states, envelope parameters). It does not collect, log, or transmit personal data such as names, emails, IPs, or location telemetry.
• 100% Local Loopback (Art. 32 Security): All communication occurs locally. No audio parameters or command payloads are sent to external servers or third parties.
• Strict Necessity (Exemption from Cookie Banner): The local token and configuration details stored in the browser's localStorage are technically necessary to establish and secure the local loopback WebSocket connection requested by the user, making it fully exempt from prior cookie consent requirements under ePrivacy guidelines.

🤖 EU AI Act Compliance

• Low-Risk Classification: This application acts as a creative assistant for music generation. It does not fall under the "High-Risk" categories (such as critical infrastructure, education, law enforcement, or biometrics) outlined in Annex III of the EU AI Act.
• Transparency Requirement (Art. 52): When using an AI co-producer via this MCP bridge, the user initiates all actions. There is complete transparency that an artificial intelligence model is generating the notes/sequences.
• Human-in-the-Loop (HITL): The user remains in complete control. All sequences generated by the AI can be edited, mutated, or muted in real-time via the web interface.

---

🚀 Installation & Getting Started

1. Build and Run via Docker (Recommended)

Building the container automatically compiles the TypeScript source code in a secure sandboxed multi-stage build.

Step A: Build the Docker Image

docker build -t salban-mcp-server:latest .

Step B: Run the Container

Option A: Hybrid No-Token Mode (Frictionless / Default) Allows instant connection from https://salban.de via automatic origin verification:

docker run -d --name salban-mcp -p 8080:8080 salban-mcp-server:latest

Option B: Token Pro-Mode (High Security) Enforces authentication with a custom static token:

docker run -d --name salban-mcp -p 8080:8080 -e SALBAN_MCP_TOKEN=your_secure_password salban-mcp-server:latest

(Enter this token once on the salban.de interface when prompted; it will be securely cached in your browser's local storage).

---

🛠️ Configuring AI Clients (Claude Desktop / Cursor)

To allow your AI assistant to use the MCP tools, add the server to your local Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry (adjusting the paths or command if running via Docker):

Running via Stdio (Native Docker)

{
  "mcpServers": {
    "salban-monolith": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "salban-mcp-server:latest"
      ]
    }
  }
}

---

📡 Registered MCP Tools

The server exposes 31 rich semantic tools to the AI assistant, organized into seven functional groups:

🗂️ Preset & Parameter Management

• salban_get_preset: Returns the active preset JSON state from the browser client. Pass includeSamples: true to include full Base64 audio data.
• salban_apply_preset: Sends a complete preset JSON configuration to the browser (up to 50 MB).
• salban_tweak_parameter: Tweaks a single nested parameter (e.g., synthParams.lead.cutoff, mixer.kick.mute). Supports dotted-path and bracket notation.
• salban_get_parameter_schema: Returns the full list of valid tweakable parameter paths and all allowed LFO modulation targets.

🎙️ Sample & Phrase Injection

• salban_load_sample: Injects a Base64-encoded audio sample into a sampler pad (0–7).
• salban_load_phrase: Loads a Base64-encoded audio loop directly into the central Phrase Sampler.
• salban_inject_mcp_sample: Programmatically synthesizes standard electronic drum hits (kick, noise, sine_click) in Node.js and injects them as WAV.

🎼 Step Sequencer (16-Step Grid)

• salban_get_sequence: Returns the 16-step sequence for a specific voice (kick, snare, hat, bass, lead, sampler, pad0–pad7).
• salban_set_drum_sequence: Sets kick/snare/hat 16-step integer triggers (0=off, 1=normal, 2=accent, 3=ghost).
• salban_set_synth_sequence: Sets note values, ties, and accents for bass or lead 16-step sequences.
• salban_set_pad_sequence: Sets triggers, pitch, reverse, and volume for a sampler pad's 16 steps.
• salban_set_sampler_sequence: Sets triggers, pitch, reverse, volume, and tie (sustain) for the Phrase Sampler's 16 steps.
• salban_set_voice_params: Sets loop length (1–16 steps), playback speed, direction, and transpose for any voice.
• salban_clear_sequence: Silences all 16 steps of a voice in one call.

🎼 Clip Launcher & Piano Roll

The Clip Launcher is a full DAW-style Piano Roll with 3 tracks × 5 scenes. ClipIndex encoding: Morph32 (poly) = 0–4, Bassline = 5–9, Lead Synth = 10–14.

• salban_get_clip_launcher: Returns all 15 clips with their notes (pitch, startBeat, durationBeats, velocity), clip length, name, isEmpty status, and scene/track assignment.
• salban_write_clip: Writes or fully replaces all piano-roll notes in a clip. Accepts MIDI note numbers (0–127) or note names (C4, F#3, Bb2). Supports setting clip length in bars and a display name.
• salban_delete_clip_notes: Deletes notes from a clip filtered by exact pitch and/or beat-range (startBeatMin/startBeatMax). Omit all filters to clear the entire clip.
• salban_quantize_clip: Snaps note start times to the nearest musical grid (64th to quarter note), with adjustable strength (0.0–1.0 for soft quantization).

🥁 Drum Auto-Tune

• salban_set_drum_autotune: Enables pitch-tracking on a drum voice (kick, snare, or hat) so it follows the note sequence of another track in real-time. Target: off | bass | lead | poly. The snare uses the 10th overtone formula (×10, folded to 2000–5000 Hz). Kick folds to 30–75 Hz; Hat to 6000–11000 Hz.

🎛️ Morph32 Polyphonic Synthesizer

The Morph32 is an 8-voice polyphonic synthesizer with dual oscillators, a stereo filter matrix, full ADSR envelopes, and a polyphonic step sequencer.

• salban_get_morph32: Returns the complete Morph32 state: oscillators, dual filters (main + stereo), amp/filter ADSR envelopes, voice configuration, mixer, piano-roll sequence, and all LFO assignments targeting the poly voice.
• salban_set_morph32_params: Configures any combination of Morph32 parameters in a single call. Includes:
  • Oscillators: oscType1/oscType2 (sawtooth|square|triangle|sine|noise|wavetable), oscMix, osc1Footage/osc2Footage (8|16|32), ringMod
  • Main Filter: filterMode (lowpass|highpass), cutoff (Hz), resonance, envMod, filter ADSR (filtA/filtD/filtS/filtR)
  • Stereo Filter: stereoMode (off|spread|mirror), stereoCutoff, stereoSpacing, stereoReso, key-tracking & modulation
  • Amp Envelope: ampA/ampD/ampS/ampR
  • Voice: detune (cents), portamento (s), maxVoices (8|16|32), distributionMode (chord|unison), unisonVoices (1–4)
  • Mixer: level, pan, dlySend, revSend, fuzSend
• salban_set_morph32_sequence: Sets the polyphonic step-sequencer pattern. Each step holds a chord (array of note names or MIDI numbers), with tie and accent flags.

🎼 Song Mode (Song Preset Sequencer)

• salban_get_song_sequencer: Returns the active Song Preset Sequencer state (8 pads, names, repeat counts, play direction, and auto-chain status).
• salban_configure_song_pad: Configures a pad (0–7): assign a name, set repeat count, capture live state, or load a full preset snapshot.
• salban_clear_song_pad: Resets and clears a pad slot, removing the assigned preset.
• salban_configure_song_sequencer: Updates global song sequencer settings (Auto-Chain on/off, play direction: forward/reverse/ping-pong/random).
• salban_trigger_song_pad: Triggers or queues playback of a specific pad immediately or at the next bar boundary.
• salban_set_transport_state: Starts or stops the sequencer transport (playing: true/false).

📡 MIDI Routing & Page Reading

• salban_get_midi_config: Returns the active/connected MIDI input/output devices, individual channel routing assignments, global Omni routing target, and the default CC mapping layout.
• salban_configure_midi: Configures global Omni routing or routes individual MIDI channels (1–16) to specific synthesizer voices (off, lead, bass, sampler, poly).
• salban_read_website_content: Reads the text content of any website page, guide, or documentation file in the project (e.g. index.html, mcp-jam.html, midi-jam.html, architecture_and_status.md, llms.txt) to understand context or explain settings.

---

💻 Developer Setup

If you want to run the server locally outside of Docker for development:

1. Install dependencies:

   npm install
   

2. Compile and run:

   npm run build
   node build/index.js
   

📄 License & Legal Notice

This project is confidential and protected under a Proprietary Evaluation License. Commercial use, production deployment, modification, or distribution is strictly prohibited without a separate, explicit written agreement from Matthias Köhler (Oszillation Media & AI Ecosystems). Please refer to the LICENSE file for full terms, conditions, and third-party notices.

⚠️ Important: These blueprints provide a security architecture pattern and reference implementation. They are not a substitute for a formal security assessment by a qualified professional. Always conduct a Data Protection Impact Assessment (DPIA) under GDPR Article 35 before deploying AI tooling against personal data in regulated environments. Engage your Data Protection Officer and Information Security team before production use.