cardinal-mcp

中文 · Documentation

An MCP/OSC and file-tool workflow for inspecting, authoring and controlling Cardinal modular-synth racks.

AI-assisted code and documentation can be wrong. Review and test on backed-up copies first; signal voltage is not proof of audible sound. The historical AI disclosure records the project's earlier WorkBuddy origin; subsequent work also uses Hermes. No agent's self-review replaces user acceptance.

Capabilities and delivery status

• 64 MCP tools, with matching TOOLS/DISPATCH names in cardinal_mcp.py: patch inspection and five-stage audits, module/parameter lookup, live reads and edits, wiring, history, sequencers, SongRoll arrangement tables, samplers, ABC export and optional in-process JS.

• The optional source patch chain contains 17 patches and expects 33 OSC endpoints / 36 diagnostic marks. Diagnostic marks are not a full source-identity, build or runtime certification.

• Python safety fixes and persistent regression fixtures/harnesses are delivered. A local native17 Windows build was built and deployed with permission; a short user-operated SongRoll edit/undo/redo check passed. See the delivery record for exact scope and reproduction.

• This repository does not ship a Cardinal executable, binary release or complete build toolchain. A local deployment is not a downloadable release.

Related MCP server: synthlab-mcp

Safe quick start

Use Python 3.13 (the exercised series), Git and a checkout of this repository. Install the two declared Python dependencies in your chosen environment:

python -m pip install -r requirements.txt
python -B tools/cardinal_mcp.py --tools

--tools lists the actual tool table without contacting Cardinal. It is not a live self-test. Start with file-only inspection in your MCP client, for example: “List saved patches, then inspect one without loading it.”

For live operations, install Cardinal standalone separately. Stock Cardinal does not supply all patched live-read/write capabilities; use the source-patch and build guide if you need them. Preserve your current rack and save a backup before allowing loads, edits, undo/redo, MIDI or playback. Never auto-load a demo over an unsaved rack. Leave playback under user control.

Only after choosing the target instance and enabling OSC there, an optional read-only connectivity check is:

python -B tools/cardinal_mcp.py --call cardinal_ping

A UDP listener alone does not prove a reply; a timeout does not prove an endpoint is unsupported. Inspect returned errors and verification fields, not just a successful process launch. --selftest is broader and contacts the live instance; its result is not proof that every mutating tool or audio path works.

MCP configuration and prerequisites

Replace <REPO>, <PYTHON> and <CARDINAL_RESOURCES> with absolute paths on your machine (forward slashes on Windows); placeholders are not shell expansions. The resource path must match the Cardinal build you actually use.

{
  "mcpServers": {
    "cardinal": {
      "command": "<PYTHON>",
      "args": ["-B", "<REPO>/tools/cardinal_mcp.py"],
      "env": {
        "CARDINAL_PATCH_DIR": "<REPO>/patches",
        "CARDINAL_MANIFEST_DIR": "<CARDINAL_RESOURCES>/PluginManifests",
        "CARDINAL_IP": "127.0.0.1",
        "CARDINAL_PORT": "2228",
        "CARDINAL_TIMEOUT": "1.5"
      }
    }
  }
}

See also mcp.example.json. Keep confirmation enabled for writes. The server uses stdio/JSON-RPC; environment values configure the Python client, not an already-running Cardinal process. Windows desktop/MIDI helpers require Windows; Linux/macOS parity has not been certified. Existing racks and legacy helpers can contain machine-specific paths: inspect sample paths before loading, use relocate_samples.py for relocation, and do not assume a moved sampler rack will still sound.

The optional C++ patch route needs separate upstream sources, fixed Git objects, third-party dependencies and a compiler/cross-build environment. Use recovery instructions and the delivery/build boundaries, not the legacy injectors. Do not replay onto a dirty production source tree or treat four recovery roots as a complete build dependency lock.

Tests

The explicit offline runner is run_safety_regression.py. The last recorded run passed 295 unique unittest methods across 15 suites; that is recorded execution, not a new run or a claim of hosted CI coverage. It requires Windows + Ubuntu-26.04 WSL, pinned source objects, Python dependencies, g++, pthread and real Jansson development headers/runtime. Missing prerequisites fail rather than skip. Output and scratch directories must be outside the repo; use a new output directory and ordinary Python, not -O.

python -B tools/run_safety_regression.py --help
python -B tools/run_safety_regression.py --out D:/external-audit/run-001 --tmpdir D:/external-scratch --wsl-source /home/USER/Cardinal --jansson-include-dir /path/to/jansson-development/include

These are replaceable example paths, not bundled dependencies. Delivery prerequisites and the test/harness index explain fixed objects, Jansson, standalone runners, source provenance and what the test shells substitute.

Verification boundaries

• File audits, fixed-source replay, extracted C++ tests, complete Native build, limited live behavior and human listening are separate evidence layers.

• native17 user sound confirmation, long-duration/full-library coverage, downstream PianoRoll stop/mute and hard-real-time/latency acceptance remain open. MiniArranger snapshot risks are not fixed by SongRoll's lock.

• read_live / save_live use autosave snapshots, not authoritative current GUI state. Check staleness and session association; use live module/parameter reads where supported. Multi-writer and cross-output resource transactions remain unproven; do not upgrade verified=false to success.

• Raw parameter values and displayed units differ. Read back the actual value; a loadable rack, nonzero voltage or a passing static audit is not audio acceptance.

Navigation

• Documentation index: usage, development/recovery, delivery/history, and reference materials. HANDOFF is the handover entry; TODO is the single backlog. Both retain dated history.

• Practical usage notes: live/file distinctions, JS safety, sample relocation and workflow examples retained from the former long README.

• Repository areas stay in place: tools, patches, params, music, samples, refs and js.

License and sources

See LICENSE for the repository's MIT license. That does not relicense upstream Cardinal/Rack/plugin code included in patches, fixtures or harness reference/ snapshots. Retain source headers and comply with the applicable upstream licenses (including GPL where applicable). See source provenance and historical attribution; the older attribution page's blanket “no third-party source shipped” language predates these fixtures and is not the current inventory. Cardinal, VCV Rack, community module authors, python-osc and zstandard provide the upstream software and dependencies.