koios/docs/tools/orpheus.md

Orpheus

Robert's Kawai piano — play music, manage the song library, review practice sessions.

• MCP server name: orpheus
• Prompt snippet: prompts/tools/orpheus.md

What It Is

Orpheus is the MCP for Robert's Kawai piano. It turns the piano into something an assistant can actually play — converting ABC notation to MIDI, queuing pieces for playback, managing a song library, and capturing practice sessions for review. Named for the Greek musician whose lyre could move stones; the Kawai is the modern equivalent.

Music isn't something David just talks about — it's something he can bring to life. Orpheus is the difference between recommending a piece and demonstrating it.

MCP Tools

Playback

Tool	Purpose
play_abc	Play music from ABC notation. Converts to MIDI and queues for playback. The easiest way to play a piece. Args: title, abc, optional tempo_bpm.
play_midi	Queue raw MIDI events. Each event is a dict with type, time, note, velocity, channel, control, value. Args: title, midi_data, tempo_bpm (default 72).
play_song	Queue a library song by ID. Args: song_id.
stop_playback	Stop whatever's currently playing.
playback_status	Returns {is_playing, is_paused, title, playback_id, progress}.

Library

Tool	Purpose
export_midi	Convert ABC to MIDI and save to the song library for future replay via play_song. Args: title, abc, optional tempo_bpm, save_to_library=True.
list_songs	List all songs in the library — id, title, composer, genre, duration.

Sessions (review practice history)

Tool	Purpose
list_sessions	List recent practice sessions — id, date, duration, note count. Args: limit (default 20).
get_session	Full session details including all raw MIDI events. Args: session_id.

System

Tool	Purpose
get_system_info	Returns hostname, IP, instrument, uptime, DB path, version.

Canonical Workflows

Play a piece from ABC notation

play_abc(
    title="Gymnopédie No. 1",
    abc="X:1\nT:Gymnopédie No. 1\nC:Erik Satie\nM:3/4\nL:1/4\nK:Dmaj\n...",
    tempo_bpm=60
)

The simplest path — composer + piece + ABC notation → live piano playback.

Save a piece to the library for later

export_midi(
    title="Gymnopédie No. 1",
    abc="...",
    tempo_bpm=60,
    save_to_library=True
)
# returns a song_id

# Later:
play_song(song_id="...")

Useful when David has converged on the right interpretation of a piece and wants it persistent rather than re-composed each time.

Review a practice session

list_sessions(limit=5)
# returns recent sessions with date and note counts

get_session(session_id="...")
# returns full MIDI event detail — every note played, when, how hard

This is the diagnostic side — when Robert practiced something and wants to see what he actually played vs. what he intended.

Who Uses Orpheus

• David — primary user. Music is David's domain, so the piano is most often his to play. Orpheus is how David can demonstrate rather than just describe.

Other agents may use Orpheus too — it just happens that David is the first one with it. If another agent's work has a legitimate reason to play something (a piece tied to a memory, a song for a mood), Orpheus is available.

What It's Good For

• Demonstrating a piece David is recommending ("here, let me play it for you")
• Building a library of pieces Robert is working on or wants to revisit
• Reviewing practice sessions for analysis — what was played, tempo discipline, note accuracy
• Setting a mood — a piece in the background while doing something else
• Exploring music interactively — try a piece, adjust tempo, try variations

What It's Not Good For

• Music recommendations alone — those don't need Orpheus; conversation is enough. Orpheus is for when David wants to play the recommendation, not just describe it.
• Recording — Orpheus plays back; the piano captures sessions separately
• Genre or artist analysis — that's interpretation work belonging in David's Neo4j Music, Artist, Playlist nodes
• Songs not in ABC notation or MIDI form. To play something obscure, you need the notation first.

Known Gotchas

• ABC notation is the path of least resistance. Most pieces in the public domain (classical, traditional folk) have ABC available. For other pieces, you may need to transcribe or find a MIDI source first.
• Tempo matters for piece identity. Satie at 60 bpm and Satie at 90 bpm are different musical experiences. Pick deliberately and document the choice in the song-library entry if saving.
• Playback is queued, not instant. playback_status tells you what's actually playing. Don't assume a successful queue call means the piece is currently audible.
• stop_playback is the kill switch. Use it when something is wrong (wrong piece, wrong tempo, distraction) rather than waiting for it to finish.
• get_session returns all raw MIDI events. For long sessions this is a lot of data. If you just want overview metrics (date, duration, count), list_sessions is enough.
• The piano is a physical object in Robert's space. Playing something loud at 11pm has real consequences. Confirm before queueing a piece if context suggests it might be disruptive.