Investigate: distribution shapes for easier integration (standalone binary and/or MCP server)

[oveddan]

Every documented path into this project currently assumes a Node toolchain and a source checkout. The README examples all read node dist/cli.js, and docs/agent-skill.md install is a clone plus a build plus copying a skill directory.

#3 and #8 already cover the npm-shaped answers — a mft-config bin, a packable tarball, npx with no clone. This issue is for the two distribution shapes neither of those covers, evaluated together because they compete for the same "how does a person actually get this" slot.

This is an investigation, not an implementation. The deliverable is a decision with reasoning, not a built artifact.

Option A — a standalone executable, no Node required

"Download this, run it." No npm, no toolchain, no clone.

The constraint that makes this non-trivial: @julusian/midi is a native addon. A single-file executable has to carry a prebuilt .node for every platform and architecture we claim to support — macOS arm64, macOS x64, Windows x64, Linux x64 at minimum. This is the whole difficulty; it is not a normal bundling job.

To evaluate:

• Node SEA (single executable applications) — how it handles native addons, and whether the .node has to be extracted to disk at runtime
• pkg — now deprecated/unmaintained, so probably disqualifying, but worth confirming rather than assuming
• bun build --compile — different native-addon story, worth a look
• Shipping a plain platform tarball with a bundled Node runtime instead of a true single file — less elegant, possibly much less work
• macOS code signing and notarization: an unsigned downloaded binary that talks to USB is a bad first-run experience, and this may dominate the total cost
• CI release matrix and artifact size

Option B — a long-running local process the agent talks to

Recorded at the bottom of #8 and not yet scoped. Moving it here so the two options can be compared rather than each being evaluated in isolation.

Dan, 2026-08-07: "it can also be like a command that you run or program you install or something, that Claude talks to."

An MCP server or small daemon, installed once, that every agent speaking the protocol can use.

Arguments for:

• The Twister connection stays open instead of being rediscovered on every command
• One install serves Claude Code, Codex, and anything else that speaks MCP — no per-tool skill directory to copy and keep in sync
• Typed tool definitions instead of the agent composing shell strings — a narrower and safer surface for something that writes settings over USB
• Matches how chromatik-mcp already installs and behaves

Open questions:

• Does it replace the skill in Add a Claude Code and Codex compatible MFT skill #2, or sit under it?
• Does a persistent process holding the MIDI port conflict with a DAW or the stock Twister editor wanting the same port?
• Is the plan/apply flow still legible to a human when it is tool calls instead of copy-pasteable commands?

They are not mutually exclusive

A human running one-off exports and an agent driving the device repeatedly are different users and may deserve different answers. A plausible outcome is: MCP server for agents, npm/npx per #3 and #8 for humans, and no standalone binary at all. Another is that the binary is the only thing that makes the "download and go" promise in the README true. Decide deliberately rather than by default.

Acceptance criteria

• A written recommendation covering both options, with the reasoning and the rejected alternatives
• The native-addon question answered concretely for whichever bundler is recommended — verified against a real build, not inferred from docs
• A cost estimate for macOS signing and notarization if a binary is recommended
• The MIDI port-contention question answered before any daemon work is scheduled
• A decision on whether this replaces, supplements, or defers to Package the CLI as the mft-config command #3 and One-click install for agentic tooling (Claude Code plugin + npx-runnable CLI) #8
• Whatever is chosen gets its own implementation issue; this one closes on the decision

Related

• Package the CLI as the mft-config command #3 — mft-config packaging and the bin name
• One-click install for agentic tooling (Claude Code plugin + npx-runnable CLI) #8 — one-click install, npx, Claude Code plugin. Option B above was recorded there and is superseded by this issue.
• Add a Claude Code and Codex compatible MFT skill #2 / Add Claude Code and Codex Twister skill #4 — the agent skill being distributed