analog-rytm-agent-bridge

Let your coding agent use your Analog Rytm MkII with MCP.

Thirty-two semantic tools covering the whole instrument — patterns and p-locks, kit sounds and machines, scenes and performance macros, songs, the sample RAM, and audio capture. The agent reads the device's real state, proposes a change in musical terms, and commits it on the next beat.

Site · MCP setup · Quick start · Tools · Safety · Capabilities

claude mcp add rytm -- npm run mcp

That attaches the full tool surface to your agent against a mock device — no hardware, no MIDI cable, nothing at risk. Ask it "what's on pattern A01?" and it will reach for rytm_inspect_pattern.

What this is

An Analog Rytm holds twelve voices, 128 patterns, kits, sounds, scenes, performance macros, songs, and 127 sample slots of state that a person edits by hand. This bridge exposes that state to a coding agent as semantic operations, so you can say "give the snare a conditional fill every 4th pass" or "chain A01 into A02 twice and mute the toms on the last one" and have it land on the hardware, on the beat.

The vocabulary is musical intent rather than SysEx addresses, and the agent works from a compact summary of what is actually on the device rather than a guess. Capture is part of the loop too — it can play what it wrote, record it, and listen back.

It is also usable without an agent. The daemon and CLIs are ordinary tools for inspecting, validating, queueing, and applying Rytm operations.

Related MCP server: forge-mcp

The safety model

The short version: hardware has no ctrl-Z, so every persistent change is validated against decoded device state, snapshotted as raw SysEx, applied at a musical boundary, read back, and restored byte-exactly if the readback disagrees. Read the rest before pointing it at hardware.

Nothing mutates without --execute. Every hardware command runs in validate-only mode by default: it connects, decodes real device state, checks the operation against it, and reports what would happen. Adding --execute is the only way to write.

Every persistent write is snapshotted first. The daemon captures the raw SysEx of each affected Pattern, Kit, Global, and Settings object before touching it, and stores it durably.

Every write is verified by readback. After applying, the daemon re-reads the object and compares it to what was asked for, canonicalizing codec-quantized values first so the comparison is real rather than cosmetic.

A failed readback rolls back automatically — restoring the original raw bytes, across multiple objects, without ever decrementing the public revision. This path is hardware-certified, not just unit tested: see docs/HARDWARE_VALIDATION_2026-07-17_COMPLETE.md.

What it will still overwrite. The bridge protects the objects it knows it is touching. It does not back up your entire device. Before first use, save your projects to +Drive and take an external backup — this is a tool that writes to a musical instrument you care about.

Realtime gestures are deliberately not persistent. Scene activation, performance macro amounts, and live parameter moves go out as transient CC/NRPN and never change the persistent revision, matching how the hardware itself treats them.

Requirements

• macOS. The daemon depends on CoreMIDI and CoreAudio and does not build elsewhere.

• An Analog Rytm MKII. Certified against OS 1.72; the codecs target firmware 1.70 and unknown-capability operations are gated rather than guessed.

• Rust ≥ 1.89 (File::try_lock, used for the single-instance state lock).

• Node ≥ 22.14 (24+ recommended). The TypeScript side runs on Node's native type-stripping. Its only runtime dependency is the official MCP SDK, used by the stdio server; the control plane, CLIs, and daemon client pull in nothing.

• For sample management only: a pinned Elektroid CLI fork — see docs/HARDWARE_SETUP.md.

Quick start

1. Without hardware

git clone https://github.com/chronick/analog-rytm-agent-bridge
cd analog-rytm-agent-bridge
npm install          # MCP SDK + dev-time typechecker
npm run demo

npm run check runs the full gate: Node tests, TypeScript typecheck, and the Rust daemon's cargo test.

Run the mock daemon as a long-lived process to exercise the real RPC boundary:

cargo run --manifest-path daemon/Cargo.toml -- serve --adapter mock

2. With hardware

Work through docs/HARDWARE_SETUP.md first — it covers MIDI port configuration, the device settings the bridge expects, and the backup you should take before any write test.

Confirm the device is visible and identifies itself:

cd daemon
cargo run -- midi-list
cargo run -- identity
cargo run -- capture-state ../hardware/runs/baseline

Then run the validation suite. Without --execute it only reads:

npm run hardware:control            # validate only
npm run hardware:control -- --execute
npm run hardware:all -- --execute --phase=core

Start the hardware daemon:

cargo run --manifest-path daemon/Cargo.toml -- serve --adapter hardware --clock-source observed

State lives in ~/.analog-rytm-agent-bridge/hardware-state.json by default; --state-dir selects an isolated store. Mock and hardware modes speak the same request/response/event protocol — see docs/DAEMON_RPC.md.

Use it from an agent

The bridge ships an MCP stdio server exposing all 32 tools to any MCP client. Start with the mock adapter — every tool answers, and no hardware is involved:

claude mcp add rytm -- npm run mcp

For the real device:

claude mcp add rytm-hw -- npm run mcp:hardware

Full setup for Claude Code, Claude Desktop, and other clients — plus flags and troubleshooting — is in docs/MCP.md.

The agent surface

Thirty-two semantic MCP tools, grouped by what they let an agent do:

rytm_describe_capabilities is the one an agent should call first: it reports what the connected device and firmware actually support, so unsupported operations fail as a refusal rather than a corrupted object.

Declarative projects

build:project applies a whole project — patterns, machines, sounds, scenes, performance macros, samples — from one JSON declaration, validation-first, with snapshot and readback:

npm run build:project -- <declaration.json> [--execute] [--auto-slots]
npm run audition:project [-- A01 B04 ...]

A declaration with a samples section is preflighted against the device's RAM inventory before anything is applied. Each declared slot must be free or already hold that sample's own content; otherwise the run prints a conflict report and exits non-zero with nothing applied, rather than failing late after every kit and pattern batch has already landed. --auto-slots remaps conflicting slots in memory (lowest free slot first, and a sample already loaded elsewhere follows its own slot, so repeat runs are idempotent), rewrites the sample_number p-locks and kit slot fields that referenced them, and prints the final map as one line of JSON. P-lock references to slots the declaration does not own are never touched.

The sounds section designs each track's kit sound — a machine selection plus per-page parameter locks. Every field is optional. The machine is emitted before its parameters, because setting a machine resets its page to defaults:

{
  "project": "layered-kick-demo",
  "patterns": [],
  "sounds": {
    "BD": {
      "machine": "bdplastic",
      "machineParams": { "tun": -14, "swt": 54, "swd": 21, "dec": 45, "tic": 32, "lev": 110 },
      "filter": { "filter_type": "Pk", "resonance": 40 },
      "amp": { "overdrive": 8 }
    },
    "BT": {
      "machine": "btclassic",
      "lfo": { "destination": "SampleFineTune", "waveform": "Tri", "mode": "Hold", "depth": 32 }
    }
  }
}

Parameter names and enum casing are the daemon's — see apply_sound_parameter in daemon/src/hardware.rs. Enum values are the CamelCase serde variants (SampleStart, Tri), not the lowercase rytm-rs strings. audition:project then plays each pattern from generated clock and captures a verified bounded recording per slot.

Architecture

Coding agent / MCP host
  → MCP stdio server / TypeScript facade
  → versioned JSON-lines RPC over stdio
  → long-running Rust daemon             revisions, queue, snapshots, rollback
  → CoreMIDI / SysEx / realtime MIDI
  → Analog Rytm MKII
                    ↘ CoreAudio capture (stereo, or Overbridge multitrack)

Two lanes, deliberately separate: SysEx for persistent state, realtime MIDI for gestures. Two adapters behind one protocol: a mock for development and a hardware adapter that adds a durable queue, explicit transport epochs, generated or observed MIDI clock, reconnect reconciliation, and semantic readback verification. Deltas rather than whole-project regeneration; compact state summaries rather than giant payloads.

This repo is intentionally separate from pd-agent-bridge, which is the reference implementation of the control-plane pattern, not a dependency. They are meant to run side by side with the coding agent as the only glue, and each should remain useful alone.

Documentation

The dated HARDWARE_VALIDATION_*.md files are certificates: each records a suite run against a connected device, with the device restored to its exact pre-test state afterward.

Credits and licensing

SysEx codecs come from rytm-rs by alisomay (MIT), pinned to a maintained fork whose changes are being prepared for upstream — see docs/UPSTREAM.md. Sample transfer uses a pinned fork of Elektroid by dagargo.

docs/reference/rytm.yaml is a machine-readable parameter reference distilled from Elektron's published documentation. Its descriptions are concise paraphrases, not copies. Elektron's manual is copyrighted and is not redistributed here; keep your own copy if you want one.

This project is not affiliated with, endorsed by, or supported by Elektron. "Analog Rytm" and "Overbridge" are Elektron's trademarks, used here only to describe what the software interoperates with.

Licensed under the MIT License.