ableton-mcp-ai/docs/SPRINT_v0.1.36_NEXT_KIMI_PROJECT_EDITING.md

# SPRINT v0.1.36 - NEXT FOR KIMI
## Expose Real Project-Editing Tools In MCP And Use `song.als` As The Benchmark

**Owner:** Kimi via OpenCode  
**Reviewer:** Codex  
**Fecha:** 2026-04-03  
**Context:** We are no longer only generating songs from scratch. We now need to edit already-open Ableton projects until they sound professional.

Primary benchmark project:

- `C:\Users\ren\Desktop\song Project\song.als`

Supporting audit:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\docs\PROJECT_AUDIT_song_2026-04-03.md`

---

## 1. Core Product Decision

From this sprint forward, the system must support two workflows:

1. `generate new song`
2. `edit existing opened project`

The second workflow is now mandatory.

The `song.als` project is the first real benchmark for it.

---

## 2. Current MCP Truth

Codex verified the current MCP situation.

### 2.1 What is already exposed as public MCP tools

The server already exposes:

- `get_session_info`
- `get_tracks`
- `get_track_info`
- `set_track_name`
- `set_track_color`
- `set_track_volume`
- `apply_clip_fades`
- `write_volume_automation`
- `apply_sidechain_pump`
- `arrange_song_structure`
- `set_loop_markers`
- `create_drum_pattern`
- `create_bassline`
- `create_chord_progression`
- `validate_set`
- `diagnose_generated_set`
- `get_generation_manifest`
- generation tools

This means:

- basic editing exists
- but not enough for serious project editing

### 2.2 What already exists in runtime but is NOT properly exposed as MCP tools

Codex verified these capabilities already exist in:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\abletonmcp_runtime.py`

Existing runtime commands include:

- `set_track_mute`
- `set_track_solo`
- `set_track_arm`
- `set_track_pan`
- `set_track_send`
- `set_device_parameter`
- `create_arrangement_clip`
- `add_notes_to_arrangement_clip`
- `duplicate_clip_to_arrangement`

These are exactly the kinds of operations we need for editing real projects.

### 2.3 Main gap

The gap is not “Ableton cannot do it”.

The gap is:

- the runtime can do it
- but the MCP server does not expose enough of it in a clean public interface

Conclusion:

- yes, we **must give those tools to MCP**

---

## 3. Project-Audit Truth To Respect

From `PROJECT_AUDIT_song_2026-04-03.md`, Kimi must treat these as real product targets:

- the arrangement exists but is still skeletal
- the project has useful palette and bass continuity
- the harmonic MIDI spine is empty in Arrangement
- there are too many arrangement islands
- the declared structure and actual timeline are mismatched
- this project is worth editing, not discarding

This sprint is therefore about:

- making project editing possible
- not about generating another new song

---

## 4. Coding Goals

## P0. Expose project-edit primitives as public MCP tools

Add public MCP tools in:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`

using the already-existing runtime support underneath.

### Required new MCP tools

#### Inspection

- `get_clips(track_index)`
- `get_devices(track_index, track_type="track")`
- `get_clip_info(track_index, clip_index)`

These are required so an agent can inspect an already-open project without guessing.

#### Track control

- `set_track_mute(track_index, mute, track_type="track")`
- `set_track_solo(track_index, solo, track_type="track")`
- `set_track_arm(track_index, arm, track_type="track")`
- `set_track_pan(track_index, pan, track_type="track")`
- `set_track_send(track_index, send_index, value, track_type="track")`

These are required for real editing and mix decisions.

#### Device control

- `set_device_parameter(track_index, device_index, value, parameter_name="", parameter_index=-1, track_type="track")`

This is required to shape an already-built project instead of regenerating it.

#### Arrangement editing

- `create_arrangement_clip(track_index, start_time, length)`
- `add_notes_to_arrangement_clip(track_index, start_time, notes)`
- `duplicate_clip_to_arrangement(track_index, clip_index, start_time)`

These are the minimum serious tools needed to:

- fill harmonic holes
- extend sections
- edit MIDI support over an existing song

---

## P0. Add a first-class editing workflow for existing songs

Do not stop at exposing low-level tools.

Add one orchestration path in the server for project editing.

### Preferred direction

Add a tool like:

- `audit_current_project()`

and optionally:

- `refine_existing_song(...)`

But do **not** make `refine_existing_song` a fake magic black box.

It must internally use the new public MCP-edit tools and return inspectable actions.

### Minimum acceptable behavior for `audit_current_project()`

It should detect:

- longest drum gap
- longest harmonic gap
- tracks with zero arrangement clips
- MIDI harmonic tracks with devices but no clips
- declared section structure mismatch
- repeated sample overuse

This tool should be aimed at real projects, not only generated manifests.

---

## P0. Use `song.als` as the benchmark project

Kimi must develop against the actual benchmark:

- `C:\Users\ren\Desktop\song Project\song.als`

The sprint is not complete if the new editing tools only work on toy examples.

Required benchmark checks:

- inspect tracks from the loaded project
- inspect clips from the loaded project
- inspect devices from the loaded project
- create or extend MIDI harmony in the loaded project

---

## P1. Do not confuse shell-level project opening with MCP editing

Opening a `.als` file can remain outside MCP for now.

Shell-level opening is acceptable:

- `Start-Process "C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe" -ArgumentList '"C:\Users\ren\Desktop\song Project\song.als"'`

That is not the blocker.

The blocker is:

- once the project is open, MCP still lacks enough public editing tools

So do not waste this sprint inventing a fancy “open set” MCP feature first.

Prioritize editing and inspection.

---

## P1. Keep product semantics correct

### No piano requirement

The user explicitly said:

- no pianos

So for this sprint:

- do not add piano-specific strategy
- do not build new features around piano timbre
- if a track is currently called `HARMONY_PIANO_MIDI`, treat it as an editable harmonic MIDI track, not as a reason to force piano sound

### Harmonic role is still required

Even with no piano:

- harmonic MIDI support remains required
- the editing workflow must be able to add MIDI notes across the arrangement

The point is:

- non-piano harmonic editing
- not no-harmony

---

## 5. Code Review Constraints

Kimi must follow these review-grade rules.

### 5.1 Do not just expose wrappers blindly

Each new MCP tool must:

- validate parameters
- call the correct runtime command
- return useful JSON or readable text
- handle `track_type` correctly where relevant

### 5.2 Do not break generation while adding editing

This sprint is about adding editing capability.

Do not regress:

- `generate_track`
- `generate_song`
- runtime truth
- manifest persistence

### 5.3 Do not build project editing only around manifests

Real editing must inspect the actual open project state:

- tracks
- clips
- devices

Not only the stored manifest.

### 5.4 Do not overtrust ALS XML for mutable runtime truth

The `.als` file is useful for audit.

But live editing truth must come from:

- the loaded Live set via MCP tools

That means the new tools must become the primary source of truth after opening the project.

---

## 6. Required Implementation Order

Kimi must implement in this order:

1. public inspection tools
2. public track/device edit tools
3. public arrangement MIDI edit tools
4. one project-audit tool
5. benchmark validation against `song.als`

Do not start from a giant “smart edit” tool before the primitives exist.

---

## 7. Required Tests

Kimi must add tests for the new MCP-facing layer.

Minimum coverage:

### Tool exposure tests

Verify the server exports the new tools:

- clip inspection
- device inspection
- track control
- arrangement edit

### Parameter validation tests

Verify bad indexes and bad values fail cleanly.

### Runtime command wiring tests

Verify each MCP tool sends the correct command payload to Ableton.

### Project-edit benchmark tests

At least one test must cover the logic needed for:

- detecting an empty harmonic MIDI track with an instrument loaded
- identifying arrangement holes worth filling

---

## 8. Required Validation For The Report

The next validation report is invalid unless it includes:

### New tools

- exact list of new MCP editing tools added

### Evidence

- proof they are callable from OpenCode
- proof they work on the open `song.als` project

### Benchmark actions

At minimum, Kimi must demonstrate:

1. inspect clip data on a real track from `song.als`
2. inspect devices on `HARMONY_PIANO_MIDI`
3. create or extend arrangement MIDI on that track or another chosen harmonic track

### Honesty requirement

If the tools are exposed but not yet pleasant to use, say so.

Do not call the editing workflow “done” if it is still only low-level and awkward.

---

## 9. What Success Looks Like

At the end of this sprint, OpenCode/Kimi should be able to do this on a loaded project:

1. inspect tracks
2. inspect clips
3. inspect devices
4. mute/solo/arm tracks if needed
5. change pan/sends/device parameters
6. create an arrangement MIDI clip
7. add notes to it
8. duplicate or extend arrangement material

That is the minimum viable “edit existing song” workflow.

If those steps work, we can stop treating every problem as “generate again”.

---

## 10. Non-Goals

Do not spend this sprint on:

- new genre generation features
- new piano-forward logic
- more reference-remake tuning
- cosmetic report polish

This sprint is about giving the MCP real editing hands.