Keyboardia

io.github.adewalePublished by GitHub account adewalev1.1.0Updated Oct 24, 2026

Create, co-edit, analyze, publish, and export collaborative step-sequencer sessions through MCP.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowMedia & Design

Overview

AI-generated overview

A remote MCP server for Keyboardia, a collaborative step sequencer, letting an assistant create, edit, analyze, publish and export music sessions.

What you can do
Read a session's tempo and track patterns, and analyze its rhythm, pitch content, inferred key and chords without changing anything. Create new sessions, remix published or editable sessions into editable copies, and publish a frozen immutable snapshot. Make narrow, retry-safe edits to an existing session, such as adding a track, assigning steps or changing tempo. Export a session as a base64-encoded Standard MIDI File for use in a DAW.
When to use it
Use it when you want an assistant to co-edit music in Keyboardia alongside connected browsers, start a new sequencer session from scratch, remix existing work, or explain the harmony and rhythm of a session.
Requirements
A remote endpoint at keyboardia.dev over streamable HTTP; no packages, environment variables or headers are declared. To edit existing music, the session UUID from its share URL is needed.
Before you install
Edits change a live shared session that other connected players see, so unintended changes affect collaborators. Publishing creates a new immutable session and should only be done on explicit request. Exported MIDI may drop session features that MIDI cannot carry. Hosted data handling is covered by the service's privacy notice.

Installation

In SourceWeft

  1. Open Keyboardia in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.adewale%2Fkeyboardia/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "keyboardia": {
      "type": "http",
      "url": "https://keyboardia.dev/mcp"
    }
  }
}

README

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 dependenciesnpm install
# Start development servernpm run dev
# Run testsnpm run test:all
# Build for productionnpm 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

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

FileDescription
app/src/audio/engine.tsMain audio engine - coordinates all audio subsystems
app/src/audio/scheduler.tsDrift-free lookahead scheduling (25ms timer, 100ms lookahead)
app/src/audio/synth.ts16-voice polyphonic synthesizer with voice stealing
app/src/audio/toneSynths.tsTone.js synth manager (FM, AM, Membrane, etc.)
app/src/audio/toneEffects.tsEffects chain (reverb, delay, chorus, distortion)
app/src/sync/multiplayer.tsWebSocket client for real-time sync
app/src/worker/live-session.tsDurable Object for session state

Testing

bash
cd appnpm run test:unit          # Unit tests (vitest, fast product lane)npm run test:audio-render  # Offline audio renders (native Web Audio)npm run test:verification-tooling  # Tests of the verification tooling itselfnpm run test:integration   # Integration tests (Cloudflare Workers)npm run test:all           # All of the abovenpm run analyze:bugs       # Static bug pattern analysis

Architecture

Audio Signal Chain

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

Synth Engines

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

Multiplayer Architecture

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

License

MIT

Bundled instrument samples are third-party content with their own licenses (CC0, public domain, and similar free-use terms), documented in app/public/instruments/LICENSE.md.

Source: README.md at commit 869d3f5

Tools

7

get_session

Get Keyboardia session

Read the current tempo and compact track patterns from an existing Keyboardia session.

Parameterssession_idrequired

edit_session

Edit Keyboardia session

Make one narrow, retry-safe edit to an existing collaborative session. After every attempt, the next Keyboardia call must be get_session for the same session. A successful call includes a backwards-compatible compact snapshot plus an acknowledgement. That snapshot is not authoritative verification; do not make another edit or finish from it. Read with get_session next. Supported operations: add_track, set_track_instrument, set_track_pan, set_steps, and set_tempo. set_steps changes only the named steps; it never replaces a track or session. set_track_instrument replaces only a track's sound source, keeping its pattern, mix, timing, and custom name.

Parameterseditrequiredsession_idrequired

create_session

Create Keyboardia session

Create a new editable Keyboardia session with the normal defaults and return its shareable URL. The session starts with no tracks; use edit_session to add them. Pass the same idempotency_key when retrying so an uncertain attempt cannot leave duplicate sessions behind.

Parametersnametempoidempotency_keyrequired

remix_session

Remix Keyboardia session

Copy an existing session — published or editable — into a new editable session that records the original as its source. The source is never modified, so this is how to continue from published work.

Parameterssession_idrequired

publish_session

Publish Keyboardia session

Freeze the current music into a new immutable session and return its URL. The source session stays editable at its own URL. Only call this when someone explicitly asks to publish; it is never a side effect of editing or exporting.

Parameterssession_idrequired

export_midi

Export Keyboardia session as MIDI

Export the session as a base64-encoded Standard MIDI File, matching what Keyboardia's own Export MIDI produces for the same music. The session is not modified. The result lists any session features a MIDI file cannot carry rather than approximating them silently.

Parameterssession_idrequired

analyze_session

Analyze Keyboardia session

Describe what is happening musically in a session — rhythm, pitch content, inferred key, and chords — without changing anything. Use this to explain music rather than to edit it. Results come from the same music-theory module the browser's Key Assistant and Chromatic Grid use, and report where the analysis is uncertain instead of guessing.

Parameterssession_idrequired

Version history

1
  1. v1.1.0LatestSep 16, 2026

Score

75% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts