# Isorek MCP

Local Model Context Protocol companion for reading, validating, and changing
live Prologue and Gates plugin JSON, including matched pair edits, and for
managing both products' saved Project Libraries.

The companion runs entirely on the user's machine. It has no model API key,
telemetry, remote service, or arbitrary filesystem tools. Codex, Claude Code,
or another MCP client starts it as a local STDIO process. Compatible plugins
publish a short-lived presence record and handle requests through their
always-on local bridge; there is no plugin AI mode to activate.

## Commands

```text
isorek-mcp serve
isorek-mcp clients
isorek-mcp clients list [--json]
isorek-mcp clients detect [--json]
isorek-mcp clients add <client>|--detected [--replace]
isorek-mcp clients remove <client>|--all
isorek-mcp doctor
isorek-mcp version
```

Automatic adapters call the client's documented MCP command with the
companion's absolute path. Correct entries are left unchanged. A conflicting
`isorek` entry requires explicit `--replace`, and removal targets only that
entry. Guided adapters print an exact local STDIO configuration for clients
that do not expose a stable management CLI. `clients add --detected` configures
detected automatic clients and prints setup steps for detected guided clients.
`clients remove --all` removes automatic entries through detected CLIs and
prints removal steps for guided configurations; it never edits those files
directly.

Automatic setup supports Codex CLI, Claude Code, Gemini CLI, and GitHub Copilot
CLI. Guided setup covers Codex Desktop, Claude Desktop, Cursor, OpenCode,
Windsurf, Zed, Cline, Roo Code, Antigravity, Rovo Dev CLI, GitHub Copilot IDE
integrations, and Codex or Claude integrations in Xcode. `clients add generic`
prints the portable fallback configuration for any other local STDIO client.

## Install

The public bootstrap downloads a versioned native binary, verifies its SHA-256
checksum plus the macOS or Windows platform signature where available,
installs it for the current user, configures supported client CLIs it detects,
and prints setup steps for detected guided clients. It does not require
Node.js, Python, administrator access, or a package-manager account, and it
does not edit shell startup files.

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://isorek.com/mcp/install.sh | sh
```

```powershell
irm https://isorek.com/mcp/install.ps1 | iex
```

The installed paths are `$HOME/.local/bin/isorek-mcp` on macOS and Linux, and
`%LOCALAPPDATA%\Programs\ISOREK\MCP\isorek-mcp.exe` on Windows. The bootstrap
adds the Windows install directory to the current and persistent user `PATH`.
On macOS and Linux, it prints the command needed when `$HOME/.local/bin` is not
already on `PATH`.

## Tools

- `get_generation_contract`
- `list_plugin_instances`
- `get_plugin_json`
- `validate_plugin_json`
- `set_plugin_json`
- `get_plugin_pair_json`
- `validate_json_pair`
- `set_plugin_pair_json`
- `get_transaction_status`
- `abort_transaction`
- `undo_last_change`
- `list_projects`
- `get_project`
- `create_project`
- `update_project`
- `delete_project`
- `list_gates_output_profiles`
- `get_gates_output_profile`
- `validate_gates_output_profile`
- `create_gates_output_profile`
- `update_gates_output_profile`
- `delete_gates_output_profile`
- `set_gates_active_output_profile`

Saved projects are readable pure-JSON v2 files under each product's
`ISOREK/<product>/projects` directory. Their envelope contains `format`,
`version`, `projectId`, `plugin`, `name`, `description`, `savedAt`, and the
complete musical `project` object; there is no opaque base64 state. MCP project
updates and deletes require the SHA-256 revision returned by `list_projects`
or `get_project`, and creates never overwrite an existing project or duplicate
name. Project tools expose product names and UUIDs, never arbitrary filesystem
paths. Legacy v1 Project Library files are not exposed by these tools.

Gates output-profile tools operate through one explicitly selected live Gates
instance, or automatically select it when exactly one Gates instance is open.
They expose factory profiles for reading while Gates keeps them read-only.
Custom profile updates replace the complete profile and require its SHA-256
revision; deleting the active profile requires an explicit replacement profile.
Because custom profiles are shared, deletion preflights every live Gates instance
and activates that replacement anywhere the profile is currently in use.
Profiles created or replaced through MCP map exactly one MIDI note and channel
to each established Gates lane (`BD`, `SN`, `D1`, `D2`, `CH`, and `OH`). Reads
preserve alternate-note candidates already present in factory profiles. These
tools do not add sequencer lanes or alter musical Project Library JSON.

The bridge lives at `ISOREK/MCP/bridge/v1` under the user's application-data
directory. Each open plugin instance advertises its product, display name,
active section, writable state, and a renewable 15-second lease. When more
than one compatible instance is open, the caller must select an instance ID;
otherwise the only matching live instance can be selected automatically.

Writes use the revision returned by a get operation, so an intervening user
edit is never overwritten silently. Matched Prologue/Gates writes prepare,
commit, and finalize both instances as one local transaction and roll both
back if either side fails. Before preparing either plugin, the server reads
and validates both current projects against their expected revisions and the
live plugins; an invalid rollback baseline stops the pair without changing
either instance. Prepared JSON is kept separate from the current playback JSON
under a renewable 30-second transaction lease. Transaction status reads expose
both states without extending the lease, and abort requires the exact
transaction ID. Numeric revisions remain monotonic state revisions while
`contentRevision` identifies the actual JSON content, including when rollback
restores earlier content. Bridge requests and individual project JSON remain
limited to 4 MB. Responses may use an 8 MB envelope so transaction status can
return complete `currentJson` and `nextJson` values together. The live bridge
does not preview or install files,
expose arbitrary paths, or require a plugin-side setup mode; Project Library
CRUD is a separate direct JSON capability.

## Development

Go 1.25 or newer is required.

```sh
go test ./...
go build ./cmd/isorek-mcp
```

The official MCP Go SDK is pinned in `go.mod`. Product-specific contracts live
behind the server adapter boundary; adding another product requires a compatible
portable project loader in that plugin first.

## Packaging

- `packaging/bootstrap/install.sh` and `install.ps1` are the canonical public
  bootstrap sources published at `https://isorek.com/mcp/`.
- `packaging/macos/build-archive.sh` builds, signs, notarizes, and verifies the
  universal macOS ZIP.
- `packaging/windows/build-archive.ps1` packages the Azure-signed Windows x64
  executable. The existing Inno installer is retained as an unadvertised
  fallback.
- `packaging/linux/build-tarball.sh` creates the Linux x86_64 tarball.
- `packaging/release/build-checksums.sh` gathers all three archives and writes
  the release `SHA256SUMS` file.
- `THIRD_PARTY_NOTICES.txt` is included in every public archive.

The legacy signed macOS `.pkg` and Windows Inno installer builders remain
available as fallback delivery paths, but are not the primary public install.

Signing credentials are supplied only to the release environment and are never
stored in this repository.

From the parent workspace, the shared macOS, Windows, and Linux release scripts
always release Bridge, Gates, Prologue, and Isorek-MCP together. Each product
keeps its own version unless an explicit common version override is supplied.

Windows release packaging requires Windows SDK SignTool, Inno Setup 6, .NET 8
or newer, and Microsoft.ArtifactSigning.Client. It uses Azure CLI authentication
by default, so run `az login` first. The script accepts the workspace release
variables `SIGNTOOL_PATH`, `ISCC_PATH`, `TRUSTED_SIGNING_DLIB_PATH`,
`TRUSTED_SIGNING_ENDPOINT`, `TRUSTED_SIGNING_ACCOUNT_NAME`,
`TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, `TRUSTED_SIGNING_TIMESTAMP_URL`,
`TRUSTED_SIGNING_SUBSCRIPTION_ID`, and `TRUSTED_SIGNING_CORRELATION_ID`. Set
`TRUSTED_SIGNING_USE_DEFAULT_CREDENTIAL_CHAIN=1` only when the full Azure
DefaultAzureCredential chain is intentional. Without overrides, it uses the
same ISOREK endpoint, signing account, certificate profile, timestamp service,
and subscription defaults as the workspace Windows release script.

Push and pull-request cross-build artifacts are short-lived unsigned CI binaries
for build verification only. A tagged workflow produces the signed macOS and
Windows archives, the Linux archive, `SHA256SUMS`, and `latest.txt` for the
GitHub release.
