mcp_sound_engineer

An MCP server that measures audio and decides like a mix/master engineer, returning a DAW-neutral action plan.

It does not control any DAW. It is one of two independent MCPs:

┌───────────────────────┐   facts + answers + recipe   ┌──────────────────────┐
│  mcp_sound_engineer   │ ───────────────────────────► │  adapter MCP (yours) │
│  measure → judge      │        (neutral JSON)        │  applies the plan    │
└───────────────────────┘                              └──────────────────────┘
        numpy + Jev

Two hats: mixing (N stems: balance, masking, corrective EQ) and mastering (one stereo file: send-back gates, dynamics, limiter, loudness target, dither).

1. Requirements

No ffmpeg, no libsndfile, no system packages. WAV is read with the standard library; FLAC/OGG/AIFF need the optional soundfile extra.

Related MCP server: music-perception-mcp

2. Getting a Jev key

Jev is a System One decision model by TypeSafe AI. It answers choice / score / noul with calibrated probabilities instead of prose — that is why the output is machine-actionable.

1. Open https://jevtypesafeai.com/pricing#get-key and create an account.

2. Create a key. Two kinds exist and they hit different endpoints:

   Key looks like	Endpoint	Notes
   jv_live_…	https://jevtypesafeai.com/api/v1/decide	Hosted playground/reseller
   apikey_…	https://api.typesafe.ai/v1/systemone	Official TypeSafe API (default here)

3. Put it in .env:

JEV_API_KEY=apikey_...
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone   # optional
JEV_MODEL=jev-latest                                # optional

.env is git-ignored. The server re-reads it on every decision, so you can rotate the key without restarting.

A key from one endpoint does not work on the other: a jv_live_ key against api.typesafe.ai returns 401, and vice versa. If judge_* fails with an auth error, check which service issued the key. Without a key the server still starts, analyze_* works, and every judge_* call returns a clear error.

3. Install and run

cd mcp_sound_engineer
./start-sound-engineer-mcp.sh          # creates .venv, installs deps, starts HTTP on :8766

Register it in any MCP client, next to your DAW adapter — they are separate servers:

{"mcpServers": {
  "engineer": {"command": "/abs/path/mcp_sound_engineer/start-sound-engineer-mcp.sh", "args": ["--stdio"]}
}}

4. Tools

5. The rules, and where they live

Sources: the mastering-engineer methodology (send-back gates, ten-stage chain, parameter ranges) and the 2026 platform loudness targets.

Everything numeric lives in server/rules.py; the wording lives in the question schemas in server/engineer_server.py.

The ❌ rows are honest gaps: the constant exists, the detector does not. They are listed in docs/LIMITS.md and in §8.

How to know a rule is real

Claims in this README are worth nothing; the tests are the contract.

./start-sound-engineer-mcp.sh --test     # smoke + 12 domain assertions

tests/test_rules.py encodes the domain, not the implementation:

• streaming loudness is a playback reference — no target_lufs may exist anywhere;

• CD is 16-bit + TPDF, streaming is 24-bit + no dither;

• corrective EQ never exceeds 3 dB per point and 6 dB total;

• gain reduction never exceeds 3 dB, limiter never exceeds 4 dB;

• send_back is terminal; an unmastered mix is never refused;

• every GATE constant is either enforced or listed in UNIMPLEMENTED_GATES — a rule cannot be documented but unwired without failing the suite.

When you change a rule, break it on purpose first: reintroduce the wrong value and confirm the suite goes red. If it stays green, the test is decoration.

Adding a rule

Three edits, no config files:

1. The number → server/rules.py, in GATE (a cap) or PLATFORMS/REFERENCE_CURVE (a target).

2. The judgement → the question dict in server/engineer_server.py (MASTER_QUESTIONS or MIX_QUESTIONS). Use noul for gates, score 2–10 levels for magnitudes, choice for treatments — and write instructions that reference the measured fields, so the model judges the numbers rather than guessing from genre.

3. The action → build_master_recipe / build_mix_recipe, emitting a _action(...) from ACTIONS. Clamp it with the cap you added in step 1; never trust the model to respect it.

Then ./start-sound-engineer-mcp.sh --test and a real call:

curl -s -X POST http://127.0.0.1:8766/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"judge_master","arguments":{"path":"/abs/track.wav"}}}'

6. The recipe contract

Recipes are ordered arrays of action primitives; no plugin, vendor or DAW name appears. Full schema: docs/RECIPE.md (currently 1.1.0).

[
  {"action": "eq.high_pass", "target": "master", "schema": "1.1.0", "freq_hz": 25, "slope_db_oct": 12},
  {"action": "eq.bell", "target": "master", "schema": "1.1.0", "freq_hz": 300, "gain_db": -2.0, "q": 5.0, "role": "corrective"},
  {"action": "limiter", "target": "master", "schema": "1.1.0", "ceiling_dbtp": -1.0, "expected_gain_reduction_db": 2.0},
  {"action": "send_back", "target": "master", "schema": "1.1.0", "reasons": ["already_mastered:measured"], "probabilities": {"already_mastered": 0.77}}
]

7. What has and has not been verified

Measured on 24 real music clips (8 tracks × 3 versions: original, +3.4 dB at 60–250 Hz, +5.3 dB at 6–16 kHz):

Not verified: no human labels, one repetition per clip, synthetic perturbations. It measures sensitivity to a known change, not agreement with a trained ear.

8. Status

0.1.0. What is missing is tracked in docs/LIMITS.md: noise-floor and lossy-source detectors, reference-track analysis (the reference curve is still a constant), per-section analysis, dry_run, confidence policy, packaging and CI.

License

MIT.