425 lines
11 KiB
Markdown
425 lines
11 KiB
Markdown
# SPRINT v0.1.33 - NEXT FOR OPENCODE
|
|
## Use The Ableton MCP Correctly, Stop Stalling, Generate Songs With Tools Or Python Fallback
|
|
|
|
**Owner:** OpenCode
|
|
**Reviewer:** Codex
|
|
**Fecha:** 2026-04-03
|
|
**Reason:** OpenCode is behaving as if the MCP were unavailable or unreliable, and is overthinking instead of using the tools to make songs.
|
|
|
|
---
|
|
|
|
## 1. Verified MCP Truth
|
|
|
|
Codex already verified the MCP state from this workspace.
|
|
|
|
Current truth:
|
|
|
|
- OpenCode MCP server is connected
|
|
- `toolCount = 77`
|
|
- canonical wrapper is:
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
|
|
- current OpenCode config is valid in:
|
|
- `C:\Users\ren\.config\opencode\opencode.json`
|
|
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
|
|
- MCP timeout is already:
|
|
- `600000 ms`
|
|
|
|
Therefore:
|
|
|
|
- this is **not** a connection sprint
|
|
- this is **not** a config sprint
|
|
- this is a **tool-usage discipline sprint**
|
|
|
|
If OpenCode says:
|
|
|
|
- "MCP unavailable"
|
|
- "tools missing"
|
|
- "timeout means failure"
|
|
|
|
without rechecking runtime state, that is a workflow error.
|
|
|
|
---
|
|
|
|
## 2. Core Problem
|
|
|
|
OpenCode is wasting turns in reasoning and often does one of these bad patterns:
|
|
|
|
1. thinks too much before calling any MCP tool
|
|
2. treats a timeout as final failure
|
|
3. retries generation blindly
|
|
4. mixes code-debugging behavior into a normal "make me a song" request
|
|
5. claims a song was generated without validating the runtime result
|
|
|
|
This sprint exists to stop that behavior.
|
|
|
|
---
|
|
|
|
## 3. Hard Rules For OpenCode
|
|
|
|
These are not suggestions.
|
|
|
|
### 3.1 When the user asks for a song, use MCP immediately
|
|
|
|
If the user asks to:
|
|
|
|
- create a song
|
|
- generate a track
|
|
- remake a reference
|
|
- refine an existing generated song
|
|
|
|
then OpenCode must call Ableton MCP tools early.
|
|
|
|
Do not spend the turn in analysis-only mode.
|
|
|
|
Within the first tool phase, OpenCode must do at least:
|
|
|
|
1. `ableton-mcp-ai_get_session_info`
|
|
2. `ableton-mcp-ai_get_tracks`
|
|
3. one generation or edit tool appropriate to the request
|
|
|
|
### 3.1.b If MCP tools are temporarily unavailable in the client UI, use Python or shell immediately
|
|
|
|
If OpenCode cannot see MCP tools in the chat client but the project is local and the wrapper exists, it must not stop there.
|
|
|
|
Approved fallback:
|
|
|
|
1. verify MCP config files
|
|
2. verify wrapper path
|
|
3. run `opencode mcp list --print-logs`
|
|
4. inspect Live log if needed
|
|
5. only after that declare a true MCP problem
|
|
|
|
Allowed shell or Python checks:
|
|
|
|
- `opencode mcp list --print-logs`
|
|
- `python C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py`
|
|
- `Get-Content C:\\Users\\ren\\AppData\\Roaming\\Ableton\\Live 12.0.15\\Preferences\\Log.txt -Tail 200`
|
|
|
|
This fallback path is for diagnosis and recovery, not for replacing song generation logic permanently.
|
|
|
|
### 3.2 For full-song creation, prefer async by default
|
|
|
|
For a complete song request, the default tool must be:
|
|
|
|
- `ableton-mcp-ai_generate_song_async`
|
|
|
|
Do **not** start with `generate_song` unless there is a strong reason to keep the call synchronous.
|
|
|
|
Reason:
|
|
|
|
- full-song generation can legitimately take time
|
|
- async is the correct contract for long-running jobs
|
|
- retrying sync generation creates duplicate or misleading states
|
|
|
|
### 3.3 Timeout does not equal failure
|
|
|
|
If `generate_song_async` or `generate_song` times out:
|
|
|
|
- do **not** immediately retry generation
|
|
- do **not** claim the run failed
|
|
- do **not** spawn a second generation blindly
|
|
|
|
Instead, OpenCode must verify state first.
|
|
|
|
### 3.4 Never close a generation turn without validation
|
|
|
|
After generation, OpenCode must always run:
|
|
|
|
1. `ableton-mcp-ai_validate_set`
|
|
2. `ableton-mcp-ai_diagnose_generated_set`
|
|
3. `ableton-mcp-ai_get_generation_manifest`
|
|
|
|
If these are missing, the report is incomplete.
|
|
|
|
---
|
|
|
|
## 4. Approved Workflow
|
|
|
|
This is the exact workflow OpenCode must follow.
|
|
|
|
There are two approved modes:
|
|
|
|
1. `MCP-first`
|
|
2. `Python/shell recovery`
|
|
|
|
### 4.1 Preflight
|
|
|
|
Before generating:
|
|
|
|
1. call `ableton-mcp-ai_get_session_info`
|
|
2. call `ableton-mcp-ai_get_tracks`
|
|
3. confirm Live is reachable
|
|
4. confirm there is no confusion about the active set state
|
|
|
|
Minimum output OpenCode should understand from preflight:
|
|
|
|
- tempo
|
|
- track count
|
|
- whether the session is empty or already populated
|
|
|
|
### 4.1.b Python or shell recovery preflight
|
|
|
|
If the client UI cannot access the MCP tools directly, OpenCode must verify local truth with shell or Python before giving up.
|
|
|
|
Minimum recovery checks:
|
|
|
|
1. `opencode mcp list --print-logs`
|
|
2. inspect:
|
|
- `C:\\Users\\ren\\.config\\opencode\\opencode.json`
|
|
- `C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\opencode.json`
|
|
3. verify wrapper path:
|
|
- `C:\\ProgramData\\Ableton\\Live 12 Suite\\Resources\\MIDI Remote Scripts\\mcp_wrapper.py`
|
|
4. inspect Ableton log:
|
|
- `C:\\Users\\ren\\AppData\\Roaming\\Ableton\\Live 12.0.15\\Preferences\\Log.txt`
|
|
|
|
If those checks show the MCP is healthy, OpenCode must return to MCP generation, not drift into passive analysis.
|
|
|
|
### 4.2 Full-song generation
|
|
|
|
For "make me a song", use:
|
|
|
|
- `ableton-mcp-ai_generate_song_async`
|
|
|
|
Typical parameters:
|
|
|
|
- `genre`
|
|
- `style`
|
|
- `reference_path`
|
|
- `bpm`
|
|
- `key`
|
|
- `structure`
|
|
|
|
Example shape:
|
|
|
|
- genre: `reggaeton`
|
|
- style: `perreo duro vieja escuela tipo safaera`
|
|
- reference_path: `libreria\\reggaeton\\ejemplo.mp3`
|
|
- bpm: `95`
|
|
- key: `Am`
|
|
|
|
### 4.3 Job follow-up
|
|
|
|
If async returns a `job_id`, OpenCode must poll with:
|
|
|
|
- `ableton-mcp-ai_get_generation_job_status`
|
|
|
|
Poll sparingly and read the state:
|
|
|
|
- `queued`
|
|
- `running`
|
|
- `completed`
|
|
- `failed`
|
|
- `cancelled`
|
|
|
|
Do not interpret `running` as failure.
|
|
|
|
### 4.4 If the async call itself times out
|
|
|
|
This is the recovery order:
|
|
|
|
1. re-check `ableton-mcp-ai_get_session_info`
|
|
2. re-check `ableton-mcp-ai_get_tracks`
|
|
3. call `ableton-mcp-ai_get_generation_history`
|
|
4. inspect whether a new run appeared or the set changed
|
|
5. only retry generation if there is clear evidence that nothing started
|
|
|
|
OpenCode must not create duplicate jobs because it panicked on timeout.
|
|
|
|
### 4.5 Validation
|
|
|
|
After a generation completes, OpenCode must run:
|
|
|
|
1. `ableton-mcp-ai_validate_set`
|
|
2. `ableton-mcp-ai_diagnose_generated_set`
|
|
3. `ableton-mcp-ai_get_generation_manifest`
|
|
|
|
OpenCode must report:
|
|
|
|
- the new `session_id`
|
|
- `generation_mode`
|
|
- whether the arrangement contains real material
|
|
- whether the result is usable or still weak
|
|
|
|
### 4.6 Python or shell diagnosis is allowed after generation, but it is not the source of truth
|
|
|
|
Allowed post-run shell checks:
|
|
|
|
- inspect `generation_manifests.json`
|
|
- inspect `generation_jobs.json`
|
|
- inspect Ableton `Log.txt`
|
|
|
|
But final truth still comes from:
|
|
|
|
- MCP validation tools
|
|
- persisted manifest truth
|
|
- the actual Arrangement state
|
|
|
|
---
|
|
|
|
## 5. Approved Edit Workflow
|
|
|
|
If the user wants to edit what already exists, OpenCode must not regenerate immediately.
|
|
|
|
Start with inspection:
|
|
|
|
1. `ableton-mcp-ai_get_session_info`
|
|
2. `ableton-mcp-ai_get_tracks`
|
|
3. `ableton-mcp-ai_get_track_info` on the important tracks
|
|
|
|
Then use the edit tools that already exist instead of rewriting the whole set:
|
|
|
|
- `ableton-mcp-ai_set_track_name`
|
|
- `ableton-mcp-ai_set_track_volume`
|
|
- `ableton-mcp-ai_apply_clip_fades`
|
|
- `ableton-mcp-ai_write_volume_automation`
|
|
- `ableton-mcp-ai_apply_sidechain_pump`
|
|
- `ableton-mcp-ai_arrange_song_structure`
|
|
- `ableton-mcp-ai_set_loop_markers`
|
|
|
|
OpenCode must understand this distinction:
|
|
|
|
- if the user asks for refinement, edit first
|
|
- if the user asks for a new song, generate first
|
|
|
|
If MCP is temporarily unavailable at the client layer, OpenCode may use Python or shell to inspect manifests, jobs and logs before resuming the edit workflow.
|
|
|
|
---
|
|
|
|
## 6. Anti-Patterns That Are No Longer Allowed
|
|
|
|
### 6.1 Bad pattern: think forever, call nothing
|
|
|
|
Wrong:
|
|
|
|
- long reasoning
|
|
- no MCP tools
|
|
- no song
|
|
|
|
Correct:
|
|
|
|
- preflight
|
|
- generation
|
|
- validation
|
|
|
|
### 6.2 Bad pattern: sync timeout then async timeout then surrender
|
|
|
|
Wrong:
|
|
|
|
1. call `generate_song`
|
|
2. get timeout
|
|
3. call `generate_song_async`
|
|
4. get timeout
|
|
5. declare MCP broken
|
|
|
|
Correct:
|
|
|
|
1. use `generate_song_async` first
|
|
2. if timeout happens, inspect state
|
|
3. then decide whether a retry is actually necessary
|
|
|
|
### 6.3 Bad pattern: report success from logs alone
|
|
|
|
Wrong:
|
|
|
|
- "generation completed"
|
|
|
|
without:
|
|
|
|
- `validate_set`
|
|
- `diagnose_generated_set`
|
|
- `get_generation_manifest`
|
|
|
|
Correct:
|
|
|
|
- only claim success when runtime validation agrees
|
|
|
|
### 6.4 Bad pattern: use code-review mode for a song request
|
|
|
|
If the user asked for a song, OpenCode must not spend the turn mainly reading Python files.
|
|
|
|
Only debug code when:
|
|
|
|
- generation tools genuinely fail
|
|
- or the user explicitly asks for debugging/review
|
|
|
|
### 6.5 Bad pattern: use Python or Bash as an excuse to avoid MCP
|
|
|
|
Wrong:
|
|
|
|
- inspect logs
|
|
- inspect config
|
|
- inspect python files
|
|
- never generate
|
|
|
|
Correct:
|
|
|
|
- use Python or Bash only to restore or verify MCP
|
|
- return to MCP tools as soon as they are available
|
|
|
|
---
|
|
|
|
## 7. Product Rules Still Active
|
|
|
|
OpenCode must preserve these project requirements while generating:
|
|
|
|
- final result must live in Arrangement View
|
|
- no automatic vocal tracks
|
|
- user library must remain part of the musical identity
|
|
- harmonic support must stay present across the song
|
|
- do not solve variation with silence and holes
|
|
- do not claim success if the song still feels like one good 4-second loop plus empty space
|
|
- no pianos
|
|
- no piano audio loops
|
|
- no `HARMONY_PIANO_MIDI`
|
|
- no piano-roll strategy based on piano timbre
|
|
|
|
OpenCode must also remember:
|
|
|
|
- harmonic support is still required
|
|
- but it must be implemented with non-piano timbres
|
|
- use pluck, synth, keys-like non-piano textures, pads or other coherent harmonic roles from the library
|
|
- do not reinterpret "harmony" as permission to add piano
|
|
|
|
This rule is absolute for this sprint:
|
|
|
|
- if OpenCode adds piano, it failed the requirement
|
|
|
|
---
|
|
|
|
## 8. Minimum Report Format For OpenCode
|
|
|
|
Every song-generation answer must include:
|
|
|
|
1. which MCP tools were used
|
|
2. whether generation was sync or async
|
|
3. session id
|
|
4. validation result
|
|
5. diagnosis result
|
|
6. short honest statement of whether the song is actually usable
|
|
|
|
If any of those are missing, the result is below standard.
|
|
|
|
The report must also state explicitly:
|
|
|
|
- whether MCP-first was used
|
|
- whether Python or shell recovery was needed
|
|
- whether any piano asset or piano MIDI role was used
|
|
|
|
If piano appears, the report must mark that as a failure.
|
|
|
|
---
|
|
|
|
## 9. What OpenCode Must Do Next
|
|
|
|
On the next real song request, OpenCode must:
|
|
|
|
1. use MCP immediately
|
|
2. use `generate_song_async` as the default full-song path
|
|
3. handle timeout by inspecting state, not panicking
|
|
4. validate the result every time
|
|
5. report the actual session truth, not assumptions
|
|
6. avoid all piano material
|
|
7. use Python or Bash only as a recovery or verification path, not as a substitute for MCP song generation
|
|
|
|
This sprint is complete only when OpenCode behaves like an operator of the system, not a spectator of the system.
|