cochlea-mcp

An MCP (Model Context Protocol) stdio server over the cochlea libraries. Any MCP client — Claude Code, another agent, a script — gets render / probe / spectro / lint / digest / loudness / beats / diff / import / export / transcribe / reference as tool calls, so it can compose, render, and “listen” to audio through numbers and images without shelling out to the cochlea binary or reading raw PCM.

The protocol is hand-rolled JSON-RPC 2.0 over newline-delimited stdio: one JSON object per line in, at most one JSON object per line out. No async runtime — offline batch tools (render a score, extract a report, write a PNG) need none. Every response is a pure function of its request: no wall clock, no session state, so identical requests produce identical responses.

Tools

Each tool mirrors the matching cochlea CLI subcommand’s semantics exactly (see crates/cli/src/main.rs) over the same library calls — this is a second front end onto the same offline pipeline, not a reimplementation.

Tool-level failures (a bad path, a render error, a failed verify or lint) come back as a normal tools/call success response with isError: true and the reason in the text content — never a JSON-RPC error. JSON-RPC errors (-32700/-32601/-32602) are reserved for protocol problems: malformed JSON, an unknown method, or missing/malformed arguments on a known tool. audio_diff’s different verdict is not one of these failures — see its row above.

Confinement (--root)

By default the server reads and writes wherever the caller points it — appropriate for a personal, local loop. For anything less trusted, launch with --root DIR: every path argument on every tool, reads and writes alike, must then resolve (canonically — symlinks and .. are resolved first) inside DIR, and anything else is refused as an Invalid Params error before the filesystem is touched. This is defense against a confused or prompt-injected client, not a sandbox against hostile local processes.

Confinement covers paths the score implies, not just the ones the caller types. render_score with a stems_dir derives one file per track from the track name, and a track name is free-form score data — it can arrive from a hand-authored RON file or, through import_midi, from a MIDI track-name meta event. A name spelled as a path (/etc/x, ../../x) would otherwise escape both the stems directory and DIR while every path argument stayed legitimately inside it. Two checks close that:

• The name, against cochlea_render::stem_file_name before the render starts — one ordinary, portable file name, with separators, :, <>"|?*, control characters and the Win32 device names refused on every platform so a score means the same thing on every host.
• The path it lands on, when the stem is written. A well-formed name is not enough: a symlink already sitting at <stems>/<track>.wav would be followed straight out of the directory, so anything already at that path is resolved and checked for containment. Presence is tested with symlink_metadata, not exists() — exists() follows the link, so a link pointing at a file that does not exist yet used to read as “nothing here” and skip the check while File::create followed it anyway (fixed in 0.7.1). A link that cannot be resolved is refused — including a dangling one whose target would have been inside the directory, since a lexical check of an unresolvable target is exactly the check that cannot see a redirect. One that resolves and stays inside the stems directory is ordinary and still works.

A stem that would land on the mix (out_path) or the score (score_path) is refused too, so a stems_dir overlapping either cannot destroy them. “Same file” here folds case (Lead.wav and lead.wav are one file on macOS and Windows), on every platform — the same rule the CLI uses, and the same rule that governs every out_path-versus-input check on this server.

claude mcp add cochlea -- cochlea-mcp --root ~/music-workspace

Client setup

Claude Code:

claude mcp add cochlea -- cargo run -p cochlea-mcp --release

or, against an already-built binary:

claude mcp add cochlea -- /path/to/target/release/cochlea-mcp

Any other stdio MCP client: launch cochlea-mcp (or cargo run -p cochlea-mcp) as a subprocess and speak JSON-RPC 2.0 over its stdin/stdout, one object per line. stdout carries only protocol responses; all logging goes to stderr, so it’s safe to leave stderr connected to a terminal or log file without corrupting the transport.

Example

Request (tools/call for probe_audio, sent as one line):

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"probe_audio","arguments":{"audio_path":"mix.wav"}}}

Response (one line back; the pretty-printed report is escaped into the text field, shown here unescaped for readability):

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\n  \"schema_version\": 5,\n  \"source\": {\n    \"sample_rate\": 48000,\n    \"channels\": 2,\n    ...\n  },\n  ...\n}"}],"isError":false}}

Testing this crate

crates/mcp/src/lib.rs exists so the dispatch logic (server::Server) can be driven in-process from integration tests — Server::handle_line(&str) -> Option<String> takes one request line and returns at most one response line, with no stdin/stdout/subprocess involved. crates/mcp/src/main.rs is just the framing loop around it. See crates/mcp/tests/protocol.rs for JSON-RPC conformance and crates/mcp/tests/tools_e2e.rs for a real render → probe → spectrogram round trip against examples/scores/first_light.ron.