renato97/ableton-mcp-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
v0.1.0
ableton-mcp-ai/CLAUDE.md
renato97 d0a4444135 chore: publish current ableton mcp ai workspace
2026-03-30 02:35:02 -03:00

350 lines
11 KiB
Markdown
Raw Permalink Blame History

# Project CLAUDE.md
This is the canonical project context file for any AI agent working in this repository.
If you are Kimi K2, Claude Code, Codex, GLM, Qwen, or any other model:
- read this file first
- treat it as the highest-signal project handoff
- use it before exploring code, making edits, debugging, or declaring success
## Mission
This project is not a toy loop generator.
The goal is to operate Ableton Live 12 through MCP and a Remote Script so an AI agent can:
- inspect the Live set
- create and edit tracks and clips
- generate musical arrangements
- analyze references
- retrieve local samples
- leave the final result audible, editable, and stable
## Mandatory Read Order
Read in this order before doing substantial work:
1. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\CLAUDE.md`
2. `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\KIMI_K2_CODEBASE_FIXES.md`
3. inspect the active entrypoints and code directly
Do not trust stale docs over live code.
Do not trust live code over runtime evidence.
## Project Roots
User-facing project root:
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts`
Actual MCP code root used by the wrapper:
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI`
## Environment Rules
This machine is using native Windows paths.
- prefer PowerShell commands, not bash
- do not use `/c/...` paths
- do not assume `Program Files` if the executable was already verified elsewhere
- when in doubt, use the exact absolute paths documented in this file
Verified executable paths:
- active Ableton install:
`C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe`
- backup or parallel updated install:
`C:\ProgramData\Ableton\.Live 12 Suite_updated\Program\Ableton Live 12 Suite.exe`
## Current Active Execution Paths
### MCP used by Claude Code and opencode
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
### Remote Script used by Ableton Live
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`
Important:
- those shims currently prefer `AbletonMCP_AI_BAK_20260328_200801\Remote_Script.py`
- they only fall back to `abletonmcp_init.py`
This means MCP and Ableton Live are not currently using a single implementation.
## Source Of Truth Rules
Before changing code, answer these questions with evidence:
1. Which file is the active entrypoint for this path?
2. Which file is actually loaded at runtime?
3. Is the bug in the MCP server, the wrapper, or the Live runtime?
4. Can the bug be confirmed with logs, compile output, or direct socket checks?
If you cannot answer those, you are not ready to patch.
## Non-Negotiable Engineering Rules
- Do not guess the active runtime.
- Do not patch dead files first.
- Do not assume a timeout means failure.
- Do not assume a success string means Live is healthy.
- Do not declare success without runtime validation.
- Do not break `get_session_info`, `get_tracks`, or `generate_track`.
- Do not create a second architecture when one already exists.
- Do not use the backup tree as the long-term source of truth.
- Do not edit random helper scripts and call that a fix.
## What Success Looks Like
A fix is only real if most of these are true:
- the MCP connects
- Ableton loads the `AbletonMCP_AI` Control Surface
- the socket is listening on `127.0.0.1:9877`
- `get_session_info` responds quickly
- `get_tracks` responds consistently
- Ableton remains responsive during mutations
- generation does not trigger `Audio queue timeout`
- the final set is audible and editable
## Best Practices For Working In This Repo
### 1. Start from the active path, not from file names
There are duplicate and legacy files:
- multiple servers
- backup runtimes
- moved trees
- legacy utility scripts
Always start from the wrapper or shim that is actually being executed.
### 2. Separate the layers mentally
This project has three separate layers:
- MCP transport and tool layer
- socket protocol layer
- Ableton Remote Script / Live API layer
Many bugs come from fixing the wrong layer.
### 3. Prefer runtime evidence over theory
Use:
- Ableton log
- compile output
- direct socket probes
- MCP `tools/list`
- `get_session_info`
- `get_tracks`
Do not argue with logs.
### 4. Keep Live API mutations short
Long or monolithic work on the Live thread is dangerous.
If a task touches Live objects:
- keep each mutation small
- avoid large blocking batches
- do heavy planning outside the Live thread
- schedule short main-thread operations when required
### 5. Compile changed Python files
Before testing runtime changes, compile the touched Python files.
Useful pattern:
```powershell
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py"
```
### 6. Validate both MCP and Live
MCP can be healthy while Live is broken.
Live can be listening while generation still crashes it.
Check both.
### 7. Prefer one source of truth
If you are cleaning architecture:
- pick one canonical Remote Script runtime
- pick one canonical MCP server
- retire or isolate dead variants
Do not leave three half-working options.
## High-Value Files
Read these first when debugging real behavior:
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\__init__.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\Remote_Script.py`
- `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_AI_BAK_20260328_200801\Remote_Script.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py`
- `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt`
## Known Current Reality
As of the latest audit:
- Claude Code and opencode can connect to the MCP
- Ableton can load the `AbletonMCP_AI` Control Surface
- `generate_track` can still push Live into `Audio queue timeout`
- `server_v2.py` does not compile
- `server.py` contains duplicated MCP tools
- the backup runtime is still in the active load path
If your task involves repairs, read `KIMI_K2_CODEBASE_FIXES.md` immediately after this file.
## Fast Diagnostic Checklist
### When MCP fails to appear
Check:
- `.mcp.json`
- `opencode.json`
- `mcp_wrapper.py`
- `C:\Users\ren\.claude.json` if Claude behaves differently from project config
### When Ableton does not show the Control Surface
Check:
- `AbletonMCP_AI\__init__.py`
- `AbletonMCP_AI\Remote_Script.py`
- Ableton log for `MidiRemoteScript`
### When Ableton listens on 9877 but commands hang or crash
Check:
- newline framing in socket responses
- thread model in the Remote Script
- long Live API operations during generation
- Ableton log for `Audio queue timeout`
### When a generation times out
Do this before declaring failure:
1. inspect Ableton log
2. query `get_session_info`
3. query `get_tracks`
4. verify whether the set changed anyway
## Commands Worth Remembering
Read Ableton log tail:
```powershell
Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
```
Check if Live socket is listening:
```powershell
netstat -an | findstr 9877
```
Compile active MCP and runtime files:
```powershell
python -m compileall "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI" "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\abletonmcp_init.py"
```
## Launching Ableton Safely
Use the real Ableton executable:
- active install:
`C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe`
- backup or parallel updated install:
`C:\ProgramData\Ableton\.Live 12 Suite_updated\Program\Ableton Live 12 Suite.exe`
Preferred restart policy:
1. if Live is responsive, close it normally first
2. only use `taskkill` if Live is hung or a script crash left zombie processes
3. wait a few seconds before relaunching
4. relaunch the executable directly
Known helper script:
- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\restart_ableton.bat`
Do not invent alternate launch paths.
Do not copy files into random Ableton installs and then launch a different binary.
## Recovery Popup Suppression
If the user explicitly wants to skip the recovery popup after a crash, clean the active recovery file before relaunching Live:
- `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashRecoveryInfo.cfg`
Important:
- this discards the pending crash-recovery state for the last session
- do this only when the user wants to suppress the popup
- do not delete the whole `Crash` folder under `Preferences`
- `CrashDetection.cfg` may remain; the popup-relevant file is `CrashRecoveryInfo.cfg`
Safe PowerShell pattern:
```powershell
$liveExe = 'C:\ProgramData\Ableton\Live 12 Suite\Program\Ableton Live 12 Suite.exe'
$recoveryFile = 'C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\CrashRecoveryInfo.cfg'
Get-Process 'Ableton Live 12 Suite' -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process 'AbletonPushCpl' -ErrorAction SilentlyContinue | Stop-Process -Force
Get-Process 'Ableton Index' -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep -Seconds 3
if (Test-Path $recoveryFile) {
Remove-Item -LiteralPath $recoveryFile -Force
}
Start-Process -FilePath $liveExe
```
After relaunch:
1. wait 10 to 15 seconds for full startup
2. verify the process is still alive
3. inspect `C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt` before declaring success
If a task requires preserving the unsaved recovery state, do not remove `CrashRecoveryInfo.cfg`.
## Working Mindset
Be skeptical.
Be concrete.
Verify everything important.
In this repo, the intelligent agent is not the one that writes the most code.
It is the one that identifies the active runtime, patches the correct layer, and proves the fix with evidence.
Reference in New Issue View Git Blame Copy Permalink