io.github.adewale/keyboardia MCP Server

The io.github.adewale/keyboardia MCP server provides MCP tools to create, co-edit, analyze, publish, and export collaborative step-sequencer sessions. Its purpose is focused on collaborative sequencing workflows, exposed to clients via the Model Context Protocol for developer-driven integration.

🛠️ Key Features

Create step-sequencer sessions
Co-edit collaborative sessions
Analyze step-sequencer data
Publish sessions
Export sessions

🚀 Use Cases

Collaborative step-sequencing among multiple participants
Programmatic creation and editing of sequencing sessions
Analyzing session content for development or tooling workflows
Publishing and exporting completed sessions

⚡ Developer Benefits

MCP access to sequencing session lifecycle operations (create → co-edit → analyze → publish/export)

⚠️ Limitations

Available capabilities are limited to the operations described: create, co-edit, analyze, publish, and export step-sequencer sessions

Keyboardia

A multiplayer step sequencer with polyrhythmic patterns, built for real-time collaboration.

Features

Real-time Multiplayer - Up to 10 players can jam together on the same session
Polyrhythmic Patterns - Each track can have 3-128 step counts (26 options including triplet-friendly values)
70 Sound Generators - 32 Web Audio synths, 11 Tone.js FM/AM synths, 27 sampled instruments
27 Sampled Instruments - Grand piano, 808 kit, acoustic drums, Hammond organ, kalimba, steel drums, strings, guitars, sax, and more
Effects Chain - Reverb, delay, chorus, and distortion with limiter (full multiplayer sync)
Parameter Locks - Per-step pitch, volume, and tied notes automation
Chromatic Grid - Two view modes: "Events" (key intervals + used pitches) and "All" (49 pitches from -24 to +24)
Scale Lock - Constrain chromatic grid to selected musical scale with out-of-scale warnings
Scale Sidebar - Visualize scale notes with root/fifth emphasis and active usage highlighting
Per-track Swing - Global and per-track swing settings for groove control
Session Sharing - Share links, remix others' work, publish immutable sessions
QR Code Sharing - Mobile-friendly session sharing
Agent Rhythm Editing (Experimental) - Co-edit, create, remix, publish, export, and analyze sessions through stateless MCP

Use with an agent

Configure your MCP client with:

text

https://keyboardia.dev/mcp

To co-edit music you already have, open a session and give the agent the UUID from its https://keyboardia.dev/s/{session_id} URL. Agents can read the current rhythm, add a track, assign specific steps, and change tempo. Their edits use the same live session as connected browsers, and published sessions stay read-only.

Agents can also start from nothing: create a new session and hand back its link, remix a published session into an editable copy without touching the original, publish the current result as an immutable snapshot when you ask, and export the session as a MIDI file for a DAW.

They can explain music too — ask what key a session is in, how its rhythms sit against each other, or what chord a moment forms, and the answer comes from the same music-theory module the Key Assistant uses, with its uncertainty stated rather than hidden.

See the stateless MCP rhythm-slice specification for the exact tool contract and current limitations. Directory maintainers can use the canonical MCP listing record, and hosted data handling is described in the MCP privacy notice.

Tech Stack

Frontend: React 19, TypeScript, Vite
Audio: Web Audio API, Tone.js
Backend: Cloudflare Workers, Durable Objects, KV Storage
Real-time: WebSockets with Hibernation API

Getting Started

bash

cd app

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm run test:all

# Build for production
npm run build

Development

Debug Mode

Add ?debug=1 to the URL to enable debug features:

Event tracing
Audio state debugging
Persistent log storage
Bug pattern detection

See docs/DEVELOPMENT-TOOLS.md for comprehensive debugging documentation.

Project Structure

code

app/
├── src/
│   ├── audio/           # Audio engine, synths, effects, scheduling
│   ├── components/      # React UI components
│   ├── hooks/           # React hooks (useSession, useMultiplayer, etc.)
│   ├── state/           # State management (grid reducer)
│   ├── sync/            # Multiplayer synchronization
│   ├── worker/          # Cloudflare Worker (Durable Objects, API routes)
│   ├── utils/           # Logging, debugging, utilities
│   └── debug/           # Debug overlay and context
├── e2e/                 # End-to-end tests (Playwright)
├── test/                # Integration tests
└── scripts/             # Development and debugging scripts

Key Files

File	Description
`app/src/audio/engine.ts`	Main audio engine - coordinates all audio subsystems
`app/src/audio/scheduler.ts`	Drift-free lookahead scheduling (25ms timer, 100ms lookahead)
`app/src/audio/synth.ts`	16-voice polyphonic synthesizer with voice stealing
`app/src/audio/toneSynths.ts`	Tone.js synth manager (FM, AM, Membrane, etc.)
`app/src/audio/toneEffects.ts`	Effects chain (reverb, delay, chorus, distortion)
`app/src/sync/multiplayer.ts`	WebSocket client for real-time sync
`app/src/worker/live-session.ts`	Durable Object for session state

Testing

bash

cd app
npm run test:unit          # Unit tests (vitest)
npm run test:integration   # Integration tests (Cloudflare Workers)
npm run test:all           # All tests
npm run analyze:bugs       # Static bug pattern analysis

Architecture

Audio Signal Chain

code

Source (Oscillator/Sample)
    → Track Gain (per-track volume)
    → Master Gain
    → Effects Chain (Tone.js: reverb → delay → chorus → distortion)
    → Limiter
    → Compressor
    → Destination

Synth Engines

SynthEngine (synth.ts) - Native Web Audio oscillators, 40+ presets
ToneSynthManager (toneSynths.ts) - Tone.js FM/AM/Membrane synths
AdvancedSynthEngine (advancedSynth.ts) - Dual-oscillator with filter envelope and LFO
SampledInstrument (sampled-instrument.ts) - Sample-based playback (piano)

Multiplayer Architecture

code

Client A ←→ Durable Object ←→ Client B
              ↓
        DO Storage (immediate)
              ↓
        KV Storage (on disconnect)

Each session is a single Durable Object instance
WebSocket connections use Hibernation API for cost efficiency
State changes broadcast to all connected clients
Hybrid persistence: Mutations saved immediately to DO storage, KV updated on disconnect

Documentation

ROADMAP.md - Implementation phases and status
SYNTHESIS-ENGINE.md - Audio architecture spec
SHARING-AND-PUBLISHING.md - Session persistence spec
DEVELOPMENT-TOOLS.md - Debug tools reference
UI-PHILOSOPHY.md - Design principles
LESSONS-LEARNED.md - Debugging war stories

session_id	string	required	The UUID after /s/ in a Keyboardia share URL. Pass only the UUID, not the full URL.
edit	any	required	Exactly one narrow session edit.

idempotency_key	string	required	A UUID you generate for this creation attempt. Reusing it returns the session the first attempt created instead of making another one.
name	string	optional	Optional display name for the new session.
tempo	number	optional	Starting tempo in BPM. Defaults to Keyboardia's own default.

Keyboardia

io.github.adewale/keyboardia MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

get_session

edit_session

create_session

remix_session

publish_session

export_midi

analyze_session

Keyboardia

Features

Use with an agent

Tech Stack

Getting Started

Development

Debug Mode

Project Structure

Key Files

Testing

Architecture

Audio Signal Chain

Synth Engines

Multiplayer Architecture

Documentation

License

Install

Remote endpoint