SAL BAN Monolith Engine - Model Context Protocol (MCP) 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.

Built in compliance with the MCP Specification 2026-07-28 (Stateless Core, Prompt-Caching via CacheableResult, and Sub-Second Co-Producing Latency).

🌟 Spotlight: Interactive MCP Apps (SEP-1865) & Live Groovebox Widget

🚀 Try the Live Groovebox MCP App

When your local MCP Server is running (on Docker or Node.js), open the demo in any modern browser:

👉 http://localhost:8080/mcp-app-groovebox.html (or http://localhost:8080)

🎛️ What Makes This MCP App So Powerful?

🛠️ Developer Guide: How to Build Your Own MCP Apps

Any creator or developer can use public/mcp-app-groovebox.html as a reference boilerplate to create custom AI chat widgets:

1. Host-to-Widget Communication (SEP-1865 standard):

   // Listen for incoming state updates from the AI host (Claude / Antigravity / Cursor)
   window.addEventListener('message', (event) => {
     if (event.data?.source === 'mcp-host' && event.data.type === 'sync_state') {
       updateWidgetUI(event.data.payload);
     }
   });
   
   // Notify the AI host when the user interacts with the widget
   function notifyHost(type, payload) {
     if (window.parent && window.parent !== window) {
       window.parent.postMessage({ source: 'mcp-app-groovebox', type, payload, timestamp: Date.now() }, '*');
     }
   }

2. Direct WebSocket Studio Bridge: Connect to ws://localhost:8080 to send commands directly to the live synthesizer:

   • set_transport_state: { type: "set_transport_state", playing: true }

   • tweak_parameter: { type: "tweak_parameter", path: "cutoff", value: 75 }

   • set_drum_sequence: { type: "set_drum_sequence", drumType: "kick", steps: [...] }

   • apply_preset: { type: "apply_preset", preset: {...} }

3. Ideas for Custom MCP Apps:

   • 🎚️ DJ Mixer & Crossfader: Blend stems between different song arrangement scenes.

   • 🎹 Polyphonic Piano Roll: Chord drawing widget for the 8-voice Morph32 synthesizer.

   • 🌌 3D Audio Visualizer: WebGL / Three.js particle sphere reacting to the master audio stream.

Related MCP server: FL Studio MCP Server

⚡ MCP Specification 2026-07-28 Upgrade Highlights

The server has been upgraded to the latest Model Context Protocol 2026-07-28 Specification, introducing major architectural optimizations for AI co-producing:

1. Stateless Core & Capability Probing (salban_discover - SEP-2575):

   • Enables lightweight, zero-roundtrip capability detection for LLMs and automated agents.

2. Deterministic Prompt-Caching (CacheableResult - SEP-2549):

   • All static schemas, tool lists, and documentation tools provide standard _meta cache declarations (ttlMs: 300000, cacheScope: "public"), boosting prompt cache hit-rates to > 85% and drastically reducing LLM inference costs.

3. Live Co-Producer Delta-Engine (salban_get_live_deltas):

   • Instead of transmitting the heavy multi-kilobyte preset JSON on every turn, the server and browser maintain a synchronized delta buffer. The AI can query only what changed in the last N seconds, saving up to 95% tokens per interaction.

4. Asynchronous Tasks Lifecycle (SEP-2663):

   • Compute-intensive operations (e.g. multi-track audio stem rendering or song arrangement batch-processing) return a taskHandle in < 20ms. Long operations run asynchronously without triggering client timeouts.

5. Interactive MCP Apps (salban_get_chat_widget - SEP-1865):

   • Exposes an interactive, sandboxed HTML5/Canvas Groovebox widget directly in LLM chat interfaces (Claude Artifacts, Antigravity IDE, Cursor) featuring live 16-step LED sequencing, track mutes, and real-time audio visualization.

🎛️ 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

📐 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 38 rich semantic tools to the AI assistant, organized into functional groups:

⚡ Discovery, Live Co-Producing & MCP Apps (2026-07-28 Spec)

• salban_discover: Returns server capabilities, protocol version (2026-07-28), connected clients, and supported extension sets for stateless probes.

• salban_get_live_deltas: Returns a compact list of parameter changes (knob tweaks, mute/solo toggles, tempo changes) since a given timestamp, saving up to 95% tokens during live jamming.

• salban_render_song_stems: Asynchronously renders multi-track audio stems (bass, lead, drums, sampler, master), returning a taskHandle in < 20ms.

• salban_create_song_arrangement_task: Asynchronously configures multi-pad song arrangements in the Song Preset Sequencer.

• salban_get_task_status: Polls the execution progress (0–100%) and download result of background tasks.

• salban_cancel_task: Cancels a running background task.

• salban_get_chat_widget: Returns the interactive HTML5/Canvas Groovebox MCP App with live 16-step grid and visualizer for in-chat interaction.

🗂️ 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.