{"id":49492371,"url":"https://github.com/deer/music.build","last_synced_at":"2026-05-01T07:04:53.558Z","repository":{"id":352094527,"uuid":"1212785351","full_name":"deer/music.build","owner":"deer","description":"MCP server for AI music composition. A typed, immutable music theory library — pitches, rhythms, harmony, form, transforms. Agents compose incrementally and export to MIDI and LilyPond.","archived":false,"fork":false,"pushed_at":"2026-04-25T17:22:14.000Z","size":443,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T19:19:51.945Z","etag":null,"topics":["ai","java","lilypond","mcp","midi","model-context-protocol","music","music-theory"],"latest_commit_sha":null,"homepage":"https://music.build","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T18:21:55.000Z","updated_at":"2026-04-25T17:22:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/deer/music.build","commit_stats":null,"previous_names":["deer/music.build"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deer/music.build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deer%2Fmusic.build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deer%2Fmusic.build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deer%2Fmusic.build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deer%2Fmusic.build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deer","download_url":"https://codeload.github.com/deer/music.build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deer%2Fmusic.build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32487746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","java","lilypond","mcp","midi","model-context-protocol","music","music-theory"],"created_at":"2026-05-01T07:04:53.026Z","updated_at":"2026-05-01T07:04:53.553Z","avatar_url":"https://github.com/deer.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# music.build\n\n[![CI](https://github.com/deer/music.build/actions/workflows/main-pull-request.yml/badge.svg)](https://github.com/deer/music.build/actions/workflows/main-pull-request.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/build.music/music-mcp)](https://central.sonatype.com/artifact/build.music/music-mcp)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nAn MCP server that lets AI agents compose music. Built on a typed, immutable music theory library — notes, voices, harmony, form, and transforms are first-class values that agents build up incrementally and export to MIDI and LilyPond notation.\n\nApache 2.0 · Java 25 · JPMS · Maven\n\n## What it does\n\nConnect music.build to Claude Desktop or any MCP-capable agent. The agent can:\n\n- Build note sequences with full pitch spelling, rhythm, and articulation\n- Layer voices into a score, assign instruments, set key and tempo\n- Generate walking bass lines, chord voicings, and diatonic harmonizations\n- Assemble multi-section forms with volta endings\n- Check voice leading and range rules\n- Export to MIDI, LilyPond PDF, and a replayable session log\n\nNo piano roll. No GUI. The composition emerges from tool calls.\n\n## Setup\n\n**Prerequisites**\n\n- Java 25 (`java -version` should report `25.x`)\n- LilyPond 2.24+ (optional — required only for PDF export; MIDI works without it)\n\n**Clone and run**\n\n```bash\ngit clone https://github.com/deer/music.build\ncd music.build\n./mvnw exec:java -pl music-server\n```\n\nAll dependencies (`base.build`, `codemodel.build`, `serve.build`) are on Maven Central — no local installs required.\n\nThe MCP server listens on `http://localhost:3000/mcp`. To use a different port:\n\n```bash\nPORT=4000 ./mvnw exec:java -pl music-server\n```\n\n**Connect to Claude Code**\n\nIf you're using [Claude Code](https://claude.ai/code), install the `compose` plugin from this repo's marketplace. It registers the MCP server and loads the composition skill automatically. Start the server, then open Claude Code in this directory — the `music-server` tools and skill are available in every session.\n\n**Connect to Claude Desktop**\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), adjusting the port if you changed it:\n\n```json\n{\n  \"mcpServers\": {\n    \"music\": {\n      \"url\": \"http://localhost:3000/mcp\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The server must be running before Claude connects — start it first, then open Claude. Ask Claude to compose something.\n\n## Module stack\n\n| Module | What it provides                                             |\n|---|--------------------------------------------------------------|\n| `music-pitch` | Pitches, intervals, enharmonics, tuning                      |\n| `music-time` | Durations, time signatures, tempo, metric positions          |\n| `music-core` | Notes, rests, chords, chord symbols, velocity, articulation  |\n| `music-transform` | Transpose, invert, retrograde, augment                       |\n| `music-score` | Voice, Part, Score — the central exchange types              |\n| `music-voice` | Voice operations: slice, concat, pad, merge                  |\n| `music-harmony` | Keys, scales, Roman numerals, chord progressions, harmonizer |\n| `music-instrument` | Instrument catalog with ranges and GM program numbers        |\n| `music-rules` | Voice leading, range, meter, parallel motion checks          |\n| `music-form` | Sections, formal plans, volta endings                        |\n| `music-midi` | MIDI render and read, General MIDI constants                 |\n| `music-lilypond` | LilyPond source generation and PDF engraving                 |\n| `music-mcp` | 47 MCP tools, composition context, save/load                 |\n| `music-server` | HTTP adapter, MCP dispatch, session event log                |\n\n## Build and test\n\n```bash\n./mvnw test                   # all modules\n./mvnw test -pl music-mcp     # just MCP layer\n```\n\n## Limitations\n\nmusic.build is designed for **single-user local use**. All composition state lives in a single in-process `CompositionContext` — concurrent requests share the same session. Don't run it as a hosted or multi-user service.\n\n## Design\n\nMusic types are built on [`codemodel.build`](https://github.com/deer/codemodel.build) — the same typed attribute system used across the `*.build` family. Each type carries a set of `Trait`s queryable by the framework. Construction uses static factories (`Note.of(...)`, `Voice.of(...)`); spelling and arithmetic stay exact throughout.\n\n- **Exact rational arithmetic** — durations are `Fraction`, never `double`\n- **Null-free** — `Optional` for genuinely absent values\n- **Immutable** — transforms return new instances\n- **Sealed hierarchies** — `NoteEvent permits Note, Rest, Chord`; pattern matching is exhaustive by construction\n- **Parse ↔ print** — `toString()` and `parse()` round-trip losslessly for pitches, intervals, durations\n\n## Group ID\n\n`build.music` · `0.1.0-SNAPSHOT`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeer%2Fmusic.build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeer%2Fmusic.build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeer%2Fmusic.build/lists"}