MCP tools and resources

barline exposes its full AI surface over MCP. The authoritative contract is the generated capability graph at barline://capabilities; it records permissions, risk, reversibility, Studio surfaces, direct tools, composed workflows, and human-only boundaries.

The song remains the authority. File tools mutate the same Yjs document as the editor, live commands reach the elected open Studio tab, and revision-bound operations refuse stale compiled context.

Discovery and context

• list_songs: list songs the caller can access, optionally scoped to an artist or organization.
• get_song: read every TypeScript source file plus revision-aware compiled metadata when the last good compile matches the current project.
• get_status: read compile state, source and compiled revisions, transport, playhead with sampled source ids, current Studio canvas, Source Lens selection, primary playback range, every simultaneous playback range, structure, Audio Session diagnostics, meters, loudness, and spectral features.
• list_devices: discover every instrument and effect with parameter ranges, units, automation support, latency, CPU class, and tails.
• list_presets: find code-ready factory presets by device, kind, or text.
• list_assets: search the authenticated production library with metadata, analysis, ownership, lineage, and project pins.
• list_packages: discover source-distributed pattern and production packages.
• get_regions: read normalized, revision-bound audio regions and their exact source ids.
• get_musical_diagnostics: read musical-domain diagnostics, exact source ranges, and proposed edits.

Songs, projects, and source

• create_song: create an empty song or initialize one from a complete TypeScript project, including licensed remix lineage.
• update_song: rename a song and change publication or remix settings.
• delete_song: permanently delete a song after explicit confirmation.
• write_file: atomically replace or create a complete source file.
• edit_file: apply an exact conflict-detecting text replacement. Prefer this for focused edits after reading the current source.
• create_file: create a new project module without overwriting an existing path.
• delete_file: remove a project module; the entry module remains protected.
• export_project: return the complete portable file map.
• import_project: replace a song with a validated complete file map.
• install_package: install a registry package as a source file in the song.

After every source mutation, call get_status. A compile error means the last good program is still playing and the new edit has not become authoritative audio.

Live performance and mixing

• transport: play, pause, stop, seek, set flags, set or clear a section loop, launch a quantized Session scene, and toggle the metronome.
• get_mixer: read track, return, and master mixer state.
• set_mixer: change track volume, pan, mute, or solo, and return/master volume.

Live commands require an open Studio tab because the browser owns the Web Audio engine. A zero-delivery response means no tab is available to execute the command.

Rendering and production analysis

• render_and_measure: render exact bars or an arrangement section, optionally isolate a track/return, and return LUFS, dBTP, crest, transient evidence, frequency-dependent stereo, RMS/peak, spectrum, semantics, and provenance.
• compare_to_reference: render the same way and compare loudness, spectrum, and musical character with the stored reference profile.
• render_audio: publish a revision-bound managed bounce and return native MCP audio when bounded plus an immutable audio resource link.
• freeze_target: create or remove a source-linked pre-fader cache for a track or return.

Use live get_status.features for immediate feedback and render_and_measure for deterministic decisions. The offline result is the trusted production measurement.

Assets and recordings

• update_asset: edit bounded metadata such as name, kind, tags, collections, license, analysis, and notes.
• pin_asset: add or remove an owned asset from a project after membership validation.
• delete_asset: permanently delete unpinned owned bytes and metadata, or force deletion with explicit confirmation.
• derive_audio_asset: crop or consolidate a managed region into a new immutable asset and optionally relink its source.

Choosing local bytes, granting microphone/device permission, arming recording, calibrating a physical route, and printing an external return remain explicit human gestures. Once bytes exist in the managed library, the agent can inspect, organize, derive, pin, relink, render, and delete them within its scopes.

History and branches

• list_snapshots: list named and automatic restore points.
• create_snapshot: capture the current complete project.
• restore_snapshot: reapply a snapshot through the shared Yjs document.
• list_branches: list direct development branches.
• create_branch: snapshot and fork a song into an in-organization branch.
• merge_branch: replace the target with a reviewed direct branch after automatically snapshotting the target.

Composed Studio workflows

These capabilities deliberately compose stable tools instead of hiding state in workflow-specific endpoints:

• Read Source Lens context: call get_status for studio.canvas, studio.activeFile, studio.selected, primary studio.playback, complete studio.playbackSources, and playhead.sourceIds; then use get_song for the exact current source. Treat selection metadata as last-good compile context when compiledContextStale is true.
• Edit vocal notebook: use get_song, edit_file, and write_file against the documented vocals.ts schema.
• Read audio diagnostics: read get_status.audio for Audio Session ownership, health events, output identity, clock source, routes, latency/PDC, asset/worklet readiness, and MIDI sync.
• Review Musical Change Request: use list_branches, read base and branch with get_song, compare the complete file sets and stable source-map ids, run matching render_and_measure windows for each open target, then call merge_branch only after review.
• Build Production Proof: compose get_song, get_status, and a full-arrangement render_and_measure. Report compile/revision freshness, song shape, engine and asset health, LUFS/true peak, referenced assets/devices, fallbacks, degradations, and provenance as separate evidence.

Production Proof is evidence, not a synthetic score or a replacement for human listening and target-hardware sign-off.

Resources

• barline://capabilities: generated capability and authorization contract.
• barline://devices: generated instrument/effect catalog.
• barline://presets: generated factory preset catalog.
• barline://assets: the authenticated caller’s managed asset library.
• barline://vocal-notebook-schema: source conventions for lyrics, timing, direction, and preferred takes.
• song://{org}/{slug}/status: revision-aware Studio telemetry.
• song://{org}/{slug}/{+path}: one source file, such as song://barline/demo/main.ts.

Permissions

OAuth scopes separate song:read, song:write, asset:read, and asset:write. Published songs are readable with song scope. Drafts and every mutation additionally require membership in the owning organization. Permanent song and asset deletion require explicit confirmation.

The common loop is get_song -> focused source edit -> get_status -> transport or offline measurement -> inspect evidence -> iterate.