# CHUK Music MCP Server
A music design system for MCP — **shadcn/ui for music composition**.
You copy patterns into your project, you own them, you modify them. The library provides correct primitives and well-designed starting points, not a black box.
## Vision
**Music as a design system, not a DAW.** This is a control-plane for composition.
LLMs operate at the intent level — structure, energy, arrangement. The system handles music theory. Composers own their patterns.
## Features
- **Pattern System**: Copyable, ownable pattern templates (drums, bass, harmony, melody, fx)
- **Style System**: Constraint bundles that **constrain**, **suggest**, and **validate**
- **Arrangement Model**: Layers × Sections structure with energy curves and harmony
- **Score IR**: Versioned intermediate representation — golden-file testable, diffable, round-trippable
- **MIDI Export**: Deterministic compilation from YAML to playable MIDI files
- **MCP Integration**: Full MCP server with 37+ tools for AI-assisted composition
## Quick Start
```bash
# Install
git clone https://github.com/chuk-ai/chuk-mcp-music
cd chuk-mcp-music
pip install -e ".[dev]"
# Compile an arrangement
python examples/compile_arrangement.py
# Verify determinism
shasum output/demo.mid
# e3b0c442... (always the same for the same input)
```
## The Stack
```
Intent (LLM)
↓
Tokens (semantic constraints)
↓
Structure (sections, energy curves)
↓
Layers (drums, bass, harmony, melody, fx)
↓
Patterns (owned, modifiable recipes)
↓
Score IR (symbolic, inspectable, versioned)
↓
MIDI (deterministic compilation)
↓
Audio (optional, downstream)
```
## What You Own vs What the Library Owns
| You Own | Library Owns |
|---------|--------------|
| Patterns you copy to your project | Schema definitions (`pattern/v1`, `score_ir/v1`) |
| Arrangement YAML files | Compiler pipeline |
| Style overrides and customizations | Validation rules |
| Project-specific pattern libraries | Default pattern/style libraries |
| Output MIDI files | IR specification and canonicalization |
The boundary is clear: **you own the content, the library owns the machinery**.
## Key Concepts
### Patterns (The shadcn Layer)
Patterns are copyable, ownable, modifiable templates:
```yaml
# patterns/bass/root-pulse.yaml
schema: pattern/v1
name: root-pulse
role: bass
pitched: true
parameters:
density:
type: enum
values: [half, quarter, eighth]
default: quarter
variants:
driving:
density: eighth
template:
events:
- degree: chord.root
beat: 0
velocity: $velocity_base
```
### Arrangements (Your Composition)
```yaml
# arrangements/demo.arrangement.yaml
schema: arrangement/v1
key: D_minor
tempo: 124
harmony:
default_progression: [i, VI, III, VII]
sections:
- name: intro
bars: 8
- name: verse
bars: 16
layers:
bass:
role: bass
patterns:
pulse:
ref: bass/root-pulse
variant: driving
arrangement:
intro: null
verse: pulse
```
### Styles (Constraint Bundles)
Styles do three things:
1. **Constrain** — tempo ranges, forbidden patterns, key preferences
2. **Suggest** — pattern shortlists per layer, register hints
3. **Validate** — lint errors with actionable fixes
```yaml
# styles/library/melodic-techno.yaml
schema: style/v1
name: melodic-techno
description: Driving, melodic electronic music
tokens:
tempo:
range: [120, 128]
default: 124
key_preference: minor
structure_hints:
breakdown_required: true
section_multiples: 8
layer_hints:
bass:
suggested: [bass/rolling-sixteenths, bass/root-pulse]
register: low
forbidden:
patterns: [drums/trap-*]
```
Validation output:
```json
{
"valid": false,
"errors": [
{"message": "Tempo 140 outside style range [120, 128]", "severity": "error"},
{"message": "Pattern drums/trap-hat forbidden by style", "severity": "error"}
],
"suggestions": [
{"message": "Consider drums/four-on-floor for drums layer", "severity": "info"}
]
}
```
### Score IR (Intermediate Representation)
The Score IR is the **stable, inspectable contract** between arrangement and MIDI:
```
Arrangement YAML → Score IR (diffable, versioned) → MIDI
```
**Same arrangement → same Score IR → same MIDI. Always.**
#### Schema Excerpt (`score_ir/v1`)
```json
{
"schema": "score_ir/v1",
"name": "my-track",
"key": "D_minor",
"tempo": 124,
"time_signature": {"numerator": 4, "denominator": 4},
"ticks_per_beat": 480,
"total_bars": 24,
"notes": [
{
"start_ticks": 0,
"pitch": 50,
"duration_ticks": 480,
"velocity": 90,
"channel": 1,
"source_layer": "bass",
"source_pattern": "bass/root-pulse",
"source_section": "verse",
"bar": 0,
"beat": 0.0
}
],
"sections": [
{"name": "intro", "start_ticks": 0, "end_ticks": 15360, "bars": 8}
]
}
```
#### Canonicalization Rules
- Notes sorted by `(start_ticks, channel, pitch)`
- Sections sorted by `start_ticks`
- All times in ticks (480 ticks per beat)
- Source traceability on every note
#### Usage
```python
# Compile and inspect
result = compiler.compile(arrangement)
print(result.score_ir.summary())
# {'name': 'my-track', 'total_bars': 32, 'total_notes': 256,
# 'layers': {'drums': 128, 'bass': 64, 'harmony': 64},
# 'pitch_range': (36, 72), 'velocity_range': (60, 110)}
# Compare two versions
diff = old_ir.diff_summary(new_ir)
# {'notes_added': 12, 'notes_removed': 8, 'notes_unchanged': 244,
# 'tempo_changed': False, 'key_changed': False}
# Debug: "Why is this note here?"
for note in result.score_ir.notes:
if note.pitch == 50 and note.bar == 3:
print(f"From {note.source_layer}/{note.source_pattern} in {note.source_section}")
```
## Common Workflows
### 1. Create Track from Style
```python
# Apply style → suggest patterns → add sections → arrange → compile
music_apply_style(arrangement="my-track", style="melodic-techno")
music_suggest_patterns(arrangement="my-track", role="bass")
# Returns: ["bass/rolling-sixteenths", "bass/root-pulse"]
music_add_section(arrangement="my-track", name="intro", bars=8)
music_add_section(arrangement="my-track", name="verse", bars=16)
music_arrange_layer(arrangement="my-track", layer="bass",
section_patterns={"intro": None, "verse": "main"})
music_compile_midi(arrangement="my-track")
```
### 2. Iterate on Bassline
```python
# Preview → tweak → diff → compile
music_preview_section(arrangement="my-track", section="verse")
music_update_pattern_params(arrangement="my-track", layer="bass",
params={"density": "eighth"})
music_diff_ir(arrangement="my-track-v1", other_arrangement="my-track-v2")
# {'notes_added': 32, 'notes_removed': 16, ...}
music_compile_midi(arrangement="my-track")
```
### 3. Debug a Bad Result
```python
# Compile to IR → inspect provenance → validate → fix
result = music_compile_to_ir(arrangement="my-track")
# Inspect which pattern produced the wrong notes
# Each note has: source_layer, source_pattern, source_section, bar, beat
music_validate(arrangement="my-track")
# {"valid": false, "errors": [{"message": "Channel conflict on channel 1"}]}
# Fix the issue
music_set_layer_level(arrangement="my-track", name="bass", level=0.8)
```
### 4. Extract Stems (IR Round-Trip)
```python
# Compile → modify IR → emit separate MIDI files
ir = music_compile_to_ir(arrangement="my-track")
# Extract just the bass layer
bass_ir = music_modify_ir(ir_json=ir["score_ir"], filter_layers=["bass"])
music_emit_midi_from_ir(ir_json=bass_ir["score_ir"], output_name="bass-stem")
# Extract drums, reduce velocity
drums_ir = music_modify_ir(ir_json=ir["score_ir"],
filter_layers=["drums"],
velocity_scale=0.8)
music_emit_midi_from_ir(ir_json=drums_ir["score_ir"], output_name="drums-stem")
# Transpose harmony up an octave
harmony_ir = music_modify_ir(ir_json=ir["score_ir"],
filter_layers=["harmony"],
transpose=12)
music_emit_midi_from_ir(ir_json=harmony_ir["score_ir"], output_name="harmony-high")
```
## MCP Tools
The server provides 37+ tools organized by domain:
**Arrangement Tools** (6):
- `music_create_arrangement` - Create a new arrangement
- `music_get_arrangement` - Get arrangement details
- `music_list_arrangements` - List all arrangements
- `music_save_arrangement` - Save to YAML
- `music_delete_arrangement` - Delete an arrangement
- `music_duplicate_arrangement` - Clone an arrangement
**Structure Tools** (11):
- `music_add_section`, `music_remove_section`, `music_reorder_sections`
- `music_set_section_energy`, `music_add_layer`, `music_remove_layer`
- `music_arrange_layer`, `music_mute_layer`, `music_solo_layer`
- `music_set_layer_level`, `music_set_harmony`
**Pattern Tools** (6):
- `music_list_patterns`, `music_describe_pattern`
- `music_add_pattern`, `music_remove_pattern`
- `music_update_pattern_params`, `music_copy_pattern_to_project`
**Style Tools** (6):
- `music_list_styles`, `music_describe_style`
- `music_suggest_patterns`, `music_validate_style`
- `music_apply_style`, `music_copy_style_to_project`
**Compilation Tools** (8):
- `music_compile_midi`, `music_preview_section`
- `music_compile_to_ir`, `music_diff_ir`
- `music_modify_ir`, `music_emit_midi_from_ir`
- `music_export_yaml`, `music_validate`
## Humanization (Planned)
Determinism doesn't mean robotic. Humanization is **seeded and explicit**:
```yaml
# In arrangement
humanize:
timing_ms: 8 # ±8ms timing drift
velocity: 6 # ±6 velocity variation
seed: 42 # Reproducible randomness
```
Same seed → same humanization → still deterministic. Change the seed to explore variations.
## Development
```bash
# Clone and install
git clone https://github.com/chuk-ai/chuk-mcp-music
cd chuk-mcp-music
pip install -e ".[dev]"
# Run full check suite
make check # Linting, types, security, tests (532 tests)
# Run tests with coverage
make test-cov # Currently at 89% coverage
# Format code
ruff format .
ruff check --fix .
```
## Project Structure
```
src/chuk_mcp_music/
├── core/ # Music primitives (pitch, rhythm, chord, scale)
├── models/ # Pydantic models (arrangement, pattern, style)
├── arrangement/ # Arrangement management
├── patterns/ # Pattern system and library
│ └── library/ # Built-in patterns (copy these!)
├── styles/ # Style system and library
│ └── library/ # Built-in styles
├── compiler/ # Compilation pipeline
│ ├── arranger.py # Arrangement → Score IR → MIDI
│ ├── score_ir.py # Intermediate representation (versioned, diffable)
│ └── midi.py # MIDI file generation
├── tools/ # MCP tool implementations
└── async_server.py # MCP server entry point
```
## Roadmap
See [roadmap.md](roadmap.md) for the full design document.
**Next up:**
- Export profiles (GM, Ableton, Logic drum maps)
- CC automation lanes (filter sweeps, sidechain ducking)
- Real-time preview via Web MIDI
- Pattern learning from MIDI import
## License
MIT
