Skip to main content
Glama
README.md
<!-- (C) -->
# house-mcp

An [MCP](https://modelcontextprotocol.io) server that gives an AI assistant two music skills:
listen to a reference track and describe it (tempo, key, a chord vamp to match it, where the
drops and breakdowns are), and write a complete house arrangement as MIDI, one file per
instrument, ready to drop into any DAW.

Ask Claude "make me something like this track" and it can analyze the track, pick the tempo and
key, and hand you a 128-bar arrangement with kick, clap, hats, snare build, bass, chord stabs, pad
and arpeggio.

## Tools

| Tool | What it does |
|---|---|
| `analyze_song(path)` | Reads an `.mp3` or `.wav`. Returns tempo (folded into the 110 to 140 BPM house range), the best key guess with runners-up, a two-chord vamp in that key, the five strongest pitches, and an eight-section energy map. |
| `generate_arrangement(out_dir, bpm, root, mode, arrangement)` | Writes a MIDI pack. `arrangement="loop"` is an 8-bar groove; `"full"` is a 128-bar track in eight sections: intro, groove, breakdown, build, drop, breakdown, groove, outro. |
| `list_pack(out_dir)` | Lists the `.mid` files in a pack with their sizes. |

Bad input (an unknown key, a BPM outside 60 to 200, a missing file) comes back as an
`{"error": ...}` result the model can read and correct, never a crash.

## Quick start

Python 3.10 or newer.

```bash
git clone https://github.com/plutothedev/house-mcp
cd house-mcp
pip install -r requirements.txt
```

**Claude Code:**

```bash
claude mcp add house-mcp -- python /absolute/path/to/house-mcp/server.py
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "house-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/house-mcp/server.py"]
    }
  }
}
```

Then try: *"Analyze ~/Music/reference.mp3, then write a full arrangement in the same key and
tempo into ~/Music/house-pack."*

## How the arrangement is built

The harmony is the two-chord vamp deep and melodic house leans on: the i chord (a minor 7th, or a
major 7th in a major key) and a minor 7th a whole step above it, changing every two bars. In G
minor that is Gm7 to Am7.

The full arrangement, by bar:

| Bars | Section | Playing |
|---|---|---|
| 0 to 15 | Intro | Pad, closed hats, a soft kick in bars 12 to 15 |
| 16 to 31 | Groove | Kick, clap, both hats, bass, chord stabs |
| 32 to 47 | Breakdown | Pad and bass |
| 48 to 63 | Build | Bass, busier hats, kick back at bar 56, a snare roll that doubles in speed from bar 56 |
| 64 to 79 | Drop | Kick, clap, both hats, bass, chord stabs, arpeggio |
| 80 to 95 | Breakdown | Pad, with the arpeggio in bars 88 to 95 |
| 96 to 111 | Groove | Kick, clap, both hats, bass, chord stabs |
| 112 to 127 | Outro | Pad, with kick and closed hats until bar 119 |

Drums use General MIDI notes (kick 36, snare 38, clap 39, closed hat 42, open hat 46). The pitched
parts carry notes only: the sound comes from whatever synth or sample you load on each track.

Tempo comes from librosa's beat tracker. Key comes from matching the track's average chroma
against the Krumhansl-Kessler key profiles.

## What it does not do

- It does not control a DAW. FL Studio, for one, has no outside automation API, so the output is
  MIDI files you import.
- It matches notes, not sound. The vibe of a track lives in its patches and samples.
- Tempo and key are estimates. Expect the right answer on clear, four-on-the-floor material and
  check by ear on anything else.

## Layout

```
server.py               entry point (python server.py)
house_mcp/
  server.py             the three MCP tools
  arrangement.py        builds every part as note events, no I/O
  midi.py               writes a part to a .mid file
  analysis.py           tempo, key, vamp and energy map
  theory.py             note names, MIDI numbers, chord shapes, key profiles
tests/                  pytest suite
```

## Development

```bash
pip install -r requirements.txt pytest
python -m pytest
```

The suite covers:

- **Golden digests:** every case's MIDI messages are hashed in `tests/golden.json`, so any change
  to the generated notes fails. For an intended change, run `python -m tests.golden` and review
  the diff.
- **Musical checks:** chord spellings, every note released, notes inside the song, tempo written
  to every file.
- **Analysis:** tempo, key and energy map checked on synthetic tracks generated inside the tests.
- **A real MCP round trip:** a client starts `server.py` over stdio, lists the tools and calls one.

## License

MIT. See [LICENSE](LICENSE).

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: analyze_song reads audio, generate_arrangement writes MIDI, list_pack inspects output folders. No overlap in resource or action, so misselection is unlikely.

Naming Consistency5/5

All three tools follow a consistent snake_case verb_noun pattern: analyze_song, generate_arrangement, list_pack. Tense and style are uniform throughout.

Tool Count4/5

Three tools is on the thin side but fits a narrow analyze→generate→inspect workflow without bloat. Each tool earns its place, though one or two more (e.g. regenerate/validate) would round it out.

Completeness3/5

Core happy path (analyze reference → generate pack → list files) is covered, but the surface has dead ends: no delete/cleanup, no inspecting individual .mid contents, and no way to modify or regenerate a section of an existing arrangement.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues