ableton-mcp-ai/AGENTS.md

AGENTS.md

This repository drives Ableton Live 12 through an MCP server plus a Remote Script. Read this file before changing code. See CLAUDE.md for expanded context.

What This Repo Is For

• Inspect the current Live set
• Generate arrangements and clips
• Edit already-open .als projects
• Analyze references and local samples
• Leave the final set audible, editable, and stable in Ableton

This is not a toy loop generator. Do not optimize for "it returned success"; optimize for runtime truth in Live.

The Three Layers

Keep these separate — most bad fixes happen because someone patched the wrong layer:

1. MCP transport and public tool layer — server.py, mcp_wrapper.py
2. Socket protocol / runtime bridge — abletonmcp_runtime.py
3. Ableton Remote Script / Live API layer — abletonmcp_init.py, Live objects

Active Paths

Purpose	Path
MCP wrapper	...\mcp_wrapper.py
MCP server	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py
Song generator	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\song_generator.py
Reference listener	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\reference_listener.py
Spectral engine	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\spectral_engine.py
Arrangement intelligence	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\arrangement_intelligence.py
Melody generator	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\melody_generator.py
Build spectral index	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\build_spectral_index.py
Coherence analyzer	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\coherence_analyzer.py
Bus routing fix	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\bus_routing_fix.py
Human feel	...\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\human_feel.py
Runtime shim	...\abletonmcp_init.py
Runtime mirror	...\AbletonMCP_AI\abletonmcp_runtime.py
Open project target	C:\Users\ren\Desktop\song Project\song.als
Ableton log	C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt

All ... paths share the root C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts.

Source of Trust Order

1. Current Live state
2. MCP responses and exact tool call results
3. Ableton log
4. Code
5. Old sprint reports or manifests

Do not trust a report that says COMPLETED if Live still shows an empty or repetitive arrangement.

Build / Test Commands

Use PowerShell and absolute Windows paths.

Compile individual files

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_runtime.py"
python -m py_compile "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py"

Compile the entire MCP tree

python -m compileall "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI"

Run tests

# All tests
python -m unittest discover "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests"

# Single test file
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py"

# Single test (pytest preferred)
python -m pytest "C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\test_runtime_truth.py::TestRuntimeTruthHelpers::test_public_set_device_parameter_supports_parameter_name"

Diagnostics

Get-Content "C:\Users\ren\AppData\Roaming\Ableton\Live 12.0.15\Preferences\Log.txt" -Tail 120
netstat -an | findstr 9877
opencode mcp list --print-logs

High-value test files

All under AbletonMCP_AI\AbletonMCP_AI\MCP_Server\tests\:

• test_runtime_truth.py — core MCP tool behaviour
• test_selection_coherence.py — selection and coherence helpers
• test_piano_forward.py — harmonic MIDI placement
• test_sample_selector.py — sample selection logic
• test_human_feel.py — humanization and groove
• test_integration.py — end-to-end integration smoke tests
• test_spectral_integration.py — spectral engine tests (T018-T043)
• test_arrangement_intelligence.py — arrangement logic tests (T086-T094)
• test_gain_staging.py — gain staging tests (T079-T087)
• test_melody_generator.py — melody generation tests (T121-T135)
• test_reggaeton_coherence.py — reggaeton structure coherence

Mandatory Questions Before Patching

1. Which file is the active entrypoint?
2. Which layer owns the bug (transport, bridge, or Live API)?
3. Can the bug be reproduced with logs, MCP calls, tests, or Live inspection?
4. How will you prove the fix after the patch?

Coding Rules

• Use PowerShell, not bash. Use absolute Windows paths.
• Standard library imports first, third-party second, local last.
• No wildcard imports. Use narrow try/except ImportError for optional modules.
• Follow existing file style; do not reformat whole files.
• Keep functions small, especially those touching Live API objects.
• Preserve typing annotations in MCP/server-side Python.
• Functions: snake_case. Classes: PascalCase. Constants: UPPER_SNAKE_CASE.
• Return structured dicts from MCP tools. Log with searchable prefixes: [MCP], [ARRANGEMENT], [HOOK], [COHERENCE], [ERROR].
• Never swallow exceptions around runtime mutations.

Product Rules

• Editing an open project is more important than creating a new one.
• Reduce silent gaps and rigid mirror symmetry.
• Harmonic MIDI should span the arrangement and fill structural holes.
• Do not force "piano" as a sound design direction; harmonic MIDI is a musical backbone, not a timbral mandate.
• Avoid automatic vocals.
• Avoid visually repetitive 4-second blocks unless explicitly required.

Validation Checklist

• Changed Python files compile without errors
• Relevant tests pass
• MCP still connects (get_session_info and get_tracks return valid data)
• If editing the open set: inspect tracks, clips, devices after mutation
• If claiming coherence improvement: provide before/after evidence
• If claiming Arrangement MIDI exists: prove it from Live, not only from a manifest

Anti-Patterns

• Do not patch dead or backup files before active entrypoints.
• Do not trust stale sprint reports over current code and Live state.
• Do not close a sprint on documentation alone.
• Do not confuse harmonic MIDI with "must sound like a piano preset".
• Do not optimize only for manifest metrics while the actual set still sounds empty or repetitive.
• Do not treat a timeout as definitive proof of failure without inspecting Live.