# Codex Musica

> A static, server-free catalog of recording "recipes" for 2503 recorded-music
> traditions and 1406 instruments. Each tradition resolves to a compressed
> descriptor-stack recipe (how to record a song in that style) plus a structured
> arrangement (ensemble, room, signal chain, tuning). All data is plain JSON served as
> static files — open a URL and read it. No API key, no server, no rate limit.

## START HERE — the live EDITABLE engine (MCP connector)
The full editable engine is a Model Context Protocol server: seed a recipe from any
tradition, then re-pick prefaces, swap part variants, override room/chain/tuning, and
add/remove instruments or traditions. Recipe tools are deterministic; thread the
returned workspace into the next call. Lyrics revision retains private run state,
and optional kitchen writing sends briefs and drafts to a paid external provider.
The chat surface supports durable request receipts. Everything below this
section is a SEPARATE read-only product — one pre-compiled recipe per tradition, built by
a different pipeline and worded differently. Use it for bulk reads; use the connector for
anything you want to change, and do not expect the two strings to match.

- Task endpoints (Streamable HTTP, no auth): https://mcp.codexmusica.com/mcp/recipe and https://mcp.codexmusica.com/mcp/lyrics
- Add in Claude: Settings -> Connectors -> Add custom connector -> paste the task URL.
- Native clients must preserve initialization guidance, complete tool metadata,
  the host-selected task and exact returned artifacts; use the maintained adapter
  documented in docs/connector.md. Keep run and request capabilities private.
- Server card (capabilities, for auto-discovery): https://mcp.codexmusica.com/.well-known/mcp.json
- Tools: start_recipe, edit_recipe, render_recipe, search_catalog, search_prefaces, get_instrument, get_tradition, list_traditions, list_options.
- Lyric tools (separate planning/grading/revision pipeline; kitchen writing is paid): lyric_screen, lyric_sweep, lyric_plan, lyric_grade, lyric_recover, lyric_check, lyric_verify, lyric_revise, lyric_types.

Do NOT fetch codex.html: it is a multi-megabyte browser GUI, it will blow your context or
fail to load, and it contains no instructions for you.

The default seed is SCAFFOLDING, not the answer: after start_recipe, push it toward the
user's words with edit_recipe. Mood/aesthetic word -> search_prefaces then set_preface on
each instrument it should color; specific gear/material/technique -> get_instrument then
set_variant; space/era/medium -> set_environment; roster -> add/remove instruments and
traditions. There are NO coherence fences — nothing is anachronistic, out-of-region, or
physically impossible (it is words for audio generation); the researched defaults are
flavor to keep or override, and every id-valid combination renders. Batch edits in one
call; present the FINAL recipe verbatim.

## Pre-compiled catalog (static JSON — bulk reads, no editing)
One recipe per tradition, pre-compiled at build time. Use it to read the whole catalog
cheaply or to work offline; use the connector above to change anything.

NOT a snapshot of what start_recipe returns. These recipes come from a search over the
axis space, the connector's from seeding a workspace and rendering it, so the two describe
the same tradition in different words. If you need the string a user would see in the app,
call the connector; if you need 2503 recipes in one fetch, this is the only thing that
does that.
- ALL default recipes in one fetch: https://codexmusica.com/api/all.json
- List of traditions: https://codexmusica.com/api/traditions/index.json
- One tradition (recipe + arrangement): https://codexmusica.com/api/traditions/{id}.json
- List of instruments: https://codexmusica.com/api/instruments/index.json
- One instrument: https://codexmusica.com/api/instruments/{id}.json
- Catalog root / endpoint map: https://codexmusica.com/api/index.json

Each tradition file has: id, name, family, lineage, recipe (string, <=1000 chars),
recipe_chars, score, config (the structured arrangement), and source (the raw
catalog-row fields — tuning/room/chain — that the browser app imports from). Fetch
the index to get every {id}, then fetch the per-id file you need.

## Full functionality (clone & run — for agents with a shell)
The static JSON above is the DEFAULT recipe per tradition (read-only). The full engine —
blend multiple genres, add/remove instruments, swap part variants, axis-target search,
and add/edit/delete catalog entries — runs from the repo. An agent with a shell can:

    git clone https://github.com/WeningerII/CodexMusica
    cd CodexMusica && npm ci
    node scripts/recipe.js --traditions afrobeat,post_punk --exclude-instrument=tonewheel_organ
    node scripts/recipe.js --diff --weight=0.6 bluegrass thrash_metal
    node scripts/recipe.js --axis-target "harm:1,density:2,intensity:2"

See SKILL.md in the repo for the complete contract (data model, all flags, CRUD,
validation). Source: https://github.com/WeningerII/CodexMusica

## Catalog
- [Live editable engine — MCP endpoint, START HERE](https://mcp.codexmusica.com/mcp)
- [Server card (capabilities)](https://mcp.codexmusica.com/.well-known/mcp.json)
- [All default recipes (one file)](https://codexmusica.com/api/all.json)
- [Catalog index](https://codexmusica.com/api/index.json)
- [Traditions index](https://codexmusica.com/api/traditions/index.json)
- [Instruments index](https://codexmusica.com/api/instruments/index.json)
- [Agent guide](https://codexmusica.com/AGENTS.md)
- [Complete contract (data model, flags, CRUD)](https://codexmusica.com/SKILL.md)
- [Full engine + skill (clone & run)](https://github.com/WeningerII/CodexMusica)