ableton-mcp-ai/docs/SPRINT_v0.1.33_NEXT_OPENCODE.md

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.