AbletonMCP_AI/CLAUDE.md

CLAUDE.md - AbletonMCP_AI v3.2

Canonical project context for AI agents. Read this BEFORE doing any work.

CRITICAL RULES

1. NEVER touch libreria/ or librerias/ - User's sample library.
2. NEVER delete project files - Overwrite only.
3. NEVER create debug .md files in project root - All in AbletonMCP_AI/docs/.
4. ALWAYS compile after changes: python -m py_compile "<file_path>"
5. ALWAYS restart Ableton after changes to __init__.py.
6. STRICT SESSION VIEW ONLY - Arrangement View is discarded for production.

Architecture

AbletonMCP_AI/
├── __init__.py          # Remote Script (All-in-one API)
├── docs/                # Sprints & SYSTEM_SCORE_RENDER.md
└── mcp_server/
    ├── server.py        # MCP Server (130+ tools)
    ├── score_engine.py  # [NEW] Pure Python song data model
    ├── score_renderer.py # [NEW] Session View renderer
    ├── ai_loop.py       # [NEW] Autonomous production loop
    └── scores/          # [NEW] JSON song storage

Primary Workflow (Score → Render)

The preferred way to produce music is the Compose-then-Render pipeline:

1. Compose: Use compose_from_template or incremental new_score + compose_* tools.
2. Review: Use get_score to see the JSON structure.
3. Save: Use save_score to persist the canzone in mcp_server/scores/.
4. Render: Use render_score to inject the JSON into Ableton's Session View.
5. Batch: Use render_all_scores to produce multiple songs at once.

How It Works

1. Ableton starts TCP server (9877).
2. MCP tools build a SongScore object in memory.
3. Renderer translates JSON sections to Scenes and definitions to Clip Slots.
4. Patterns (Dembow, Bass, etc.) are resolved server-side into MIDI notes.

Workflow

• Kimi codes fast, implements features.
• Qwen verifies, compiles, debugs, creates next sprint.
• Refer to docs/SYSTEM_SCORE_RENDER.md for full technical details.