Cubase-MCP-GAJ3T.MusicGen.R.../docs/local-deployment.md

256 lines
14 KiB
Markdown

# Local Windows x64 deployment — supported MIDI slice
This deploys the two existing stdio MCP tools, not a generation command-line
interface or HTTP service. It supports explicit AGLP/AGM/AGT/AME **Documented-default
Lead** and ABJ **Sustain-only Bass**, with Standard MIDI and explicit MIDI fallback
for unavailable native formats. AMR and SD3 remain unmapped; ABJ PalmMute
explicitly fails rather than substituting Sustain.
No AGP/SDP writer, application-Verified mapping, Cubase/plugin import, playback
or full-product acceptance is claimed.
## Publish
From the repository root, using the SDK pinned by `global.json`:
```powershell
dotnet publish .\src\GAJ3T.MusicGen.RiffGrooveBuilder.Server\GAJ3T.MusicGen.RiffGrooveBuilder.Server.csproj -p:PublishProfile=win-x64 -o .\artifacts\publish\win-x64
```
`Properties\PublishProfiles\win-x64.pubxml` sets Release, `win-x64`,
`SelfContained=true`, `PublishSingleFile=true`, `PublishTrimmed=false`,
`PublishAot=false`, `UseAppHost=true` and
`IncludeNativeLibrariesForSelfExtract=true`. This remains a `net10.0` console
application using `Microsoft.NET.Sdk`, not a web SDK.
The profile uses `packages.win-x64.lock.json` separately from the ordinary
server `packages.lock.json`: RID/single-file restore needs the SDK's implicit
`Microsoft.NET.ILLink.Tasks` 10.0.11 tooling for single-file analysis even though
trimming/AOT are disabled. This is not an application package addition.
The exact central application/test package pins are unchanged, including
DryWetMIDI **[8.0.3]**. To enforce the publication graph's lock:
```powershell
dotnet restore .\src\GAJ3T.MusicGen.RiffGrooveBuilder.Server\GAJ3T.MusicGen.RiffGrooveBuilder.Server.csproj -p:PublishProfile=win-x64 --locked-mode
dotnet publish .\src\GAJ3T.MusicGen.RiffGrooveBuilder.Server\GAJ3T.MusicGen.RiffGrooveBuilder.Server.csproj -p:PublishProfile=win-x64 --no-restore -o .\artifacts\publish\win-x64
```
Inspect an existing publication before republishing. Build tools update their
own output files; do not recursively clean unrelated directories.
## Observed payload and extraction
The correction iteration 4 publication refresh produced these five files in
`artifacts\publish\win-x64` (original Step 9 inventory is preserved in its report):
| File | Bytes | Role |
| --- | ---: | --- |
| `GAJ3T.MusicGen.RiffGrooveBuilder.Server.exe` | 74,734,064 | Self-contained single-file executable |
| `GAJ3T.MusicGen.RiffGrooveBuilder.Core.pdb` | 37,636 | Optional debugging symbols |
| `GAJ3T.MusicGen.RiffGrooveBuilder.Generation.pdb` | 20,208 | Optional debugging symbols |
| `GAJ3T.MusicGen.RiffGrooveBuilder.Server.pdb` | 20,320 | Optional debugging symbols |
| `Melanchall_DryWetMidi_Native64.dylib` | 90,600 | Package-copied macOS native sidecar; not used on Windows |
Refreshed executable SHA256:
`921AADE7FB75222E8A7E5E81151F3DC73747CD8036EE751555A613A5DBDD308E`.
Symbols and the `.dylib` are not needed for this Windows MIDI-only path:
an **executable-only** isolated copy successfully initialized MCP and generated
readable MIDI from `C:\Windows\System32` (the actual system directory on this host).
There are no loose managed DLLs, catalog JSON, runtimeconfig or deps files in
the published payload. Catalogs and managed dependencies are embedded.
The pinned package's build targets copy native32/native64 Windows DLLs and a
macOS dylib without RID filtering. With this publish profile the Windows DLLs
are bundled and extracted at startup:
- `Melanchall_DryWetMidi_Native32.dll`: 57,954 bytes.
- `Melanchall_DryWetMidi_Native64.dll`: 66,926 bytes.
Tests compare their SHA256 hashes with the inspected 8.0.3 package assets.
Only those two DLLs were extracted in the observed SDK 10.0.400/.NET 10.0.11
single-file run; no loose `coreclr.dll`, `clrjit.dll` or managed library was
extracted. Host tracing reported “Executing as a self-contained app”,
“Using internal hostpolicy” and `CoreCLR path = '', CoreCLR dir = ''`.
These are actual bundle observations, not a claim that device APIs/native
playback were tested or that every dependency is irrelevant.
Normal .NET Windows bundle extraction uses the user's `%TEMP%\.net` cache.
It needs writable space; security software may also affect execution/extraction.
`DOTNET_BUNDLE_EXTRACT_BASE_DIR` can select a writable private cache if needed.
Tests set it only for their child process to a task-owned checkout directory,
then delete that directory after process exit. They do not edit machine/user
environment or client settings. No playback/device API is used.
**Architecture/acceptance:** this payload is for Windows x64 and includes
.NET 10.0.11. It is not an ARM64/macOS/Linux publication. Launch and host tracing
on this SDK-equipped machine verify packaging, **not** a matching runtime-free
Windows installation. That acceptance check remains **pending**; no fake
`DOTNET_ROOT`, runtime removal, VM, container or product installation substitutes
for it. Normal supported-Windows OS prerequisites still apply.
## Copyable VS Code MCP client configuration
This is a reference snippet only. No workspace/user/global MCP settings were
modified. If you choose to configure VS Code, put the following server entry in
your chosen MCP configuration and adjust the absolute path for your checkout
or copied executable. The command is the executable itself, with **no shell
wrapper, HTTP URL or generation CLI arguments**:
```json
{
"servers": {
"riff-groove-builder": {
"type": "stdio",
"command": "D:\\_Repos\\Code\\GAJ3T\\MCPs\\MusicGen\\GAJ3T.MusicGen.Riff-Groove-Builder.Net\\artifacts\\publish\\win-x64\\GAJ3T.MusicGen.RiffGrooveBuilder.Server.exe",
"args": []
}
}
}
```
The client launches and owns this finite stdio process. MCP uses UTF-8
newline-delimited JSON-RPC, negotiates `2025-11-25`, then requires
`notifications/initialized` before tool calls. A normal MCP client handles
this handshake. Discover `list_instrument_profiles` and `generate_project`;
profile discovery with `{}` returns seven identities and five Documented profiles
(four Lead Sustain/PM, one Bass Sustain-only; two unavailable identities).
There is no server URL, listener, background service or registration step.
Call `generate_project` with these **tool arguments** (not executable `args`):
```json
{
"description": "4 bars at 120 BPM in E minor, 4/4: palm-muted eighth-note lead",
"outputDirectory": "D:\\MusicGenOutputs",
"projectName": "ame-lead-example",
"formats": ["mid"],
"profiles": {
"lead": "ample-ame-documented-defaults-2026-10-20"
},
"fallbackToMidi": false
}
```
AGLP instead requires the explicit profile
`ample-aglp-documented-defaults-2026-10-20`. No profile is automatically selected.
AGM and AGT also have explicit `ample-agm-documented-defaults-2026-10-20` and
`ample-agt-documented-defaults-2026-10-20` profiles. For Lead+Bass, change
description to `"palm-muted eighth-note lead and sustained bass"` and profiles to:
```json
{
"lead": "ample-ame-documented-defaults-2026-10-20",
"bass": "ample-abj-documented-defaults-2026-10-20"
}
```
The output is one combined MIDI, not two role files: Lead channel 0 and Bass
channel 1, shared lead-in 120. ABJ supports Sustain velocities 1-125 only;
PalmMute and accent velocities 126-127 fail explicitly. Missing Bass selection
is `no_default_profile`; unmapped Drums is `mapping_unavailable`. Neither is
a silently reduced arrangement. Native fallback still produces one combined
artifact retaining both roles.
The example returns `status:"complete"`, one absolute
`D:\MusicGenOutputs\ame-lead-example.mid` path and the Documented compatibility
warning. This is **source-backed, NOT installed/application-verified**. Honor
the returned version/configuration/routing/timing notes, including default
tuning/mapping/thresholds, instrument mode, MIDI Guitar mode off, idle isolated
receiver, Lead channel 0 and (when selected) Bass channel 1. The switch advance/pulse timing is engineering
policy, not certified plugin latency or a vendor minimum.
## Output, fallback, shutdown and troubleshooting
- The caller supplies an absolute output directory and safe filename stem;
the server creates the directory after preflight. Relative paths, traversal
and unsafe names fail. Existing destinations are never overwritten; use a
new stem on `output_exists`. Request-owned staging is cleaned on failure;
an empty newly created directory may remain after an I/O failure.
- Omitted Lead formats default to `["agp","mid"]`, and omitted
`fallbackToMidi` defaults to true. AGP requests therefore return
`status:"fallback"` and one real `.mid` with explicit native-unavailable
reasons, never a renamed native file. Native requests with fallback disabled
fail before output. SDP is inapplicable to a Lead-only request.
- Failed results have `isError:true`, no artifacts and actionable errors.
Schema/argument violations use JSON-RPC `-32602`; parse errors use `-32700`.
Output permissions/disk failures are errors, not fallback opportunities.
- Keep stdin open until the response arrives. Closing it signals EOF, cancels
active work and ends the process; empty stdin/EOF exits silently with code 0.
Do not pipe a whole generation conversation and immediately close stdin.
- MCP cancellation is observed around synchronous DryWetMIDI serialization
and before publication; it cannot interrupt inside library serialization.
The final no-overwrite move is the commit point. Late cancellation does not
undo a published file. Clients should inspect the completed result.
- Stdout is protocol-only. Consult stderr/client logs for diagnostics, not an
HTTP endpoint. A process launched interactively waits for stdin; that alone
is not a readiness check. Successful initialize/ping/tool responses are.
- For missing tools/profiles, verify you launched the published executable,
completed initialization and rebuilt after catalog changes. Catalogs are
embedded; copying loose JSON beside the executable does not configure them.
- For extraction/launch failures, check Windows x64 compatibility, writable
bundle cache, permissions/security software and stderr. Do not install vendor
software or invoke device APIs merely to use this MIDI-file slice.
## Automated publication checks and retained example
Publish first. From the repository root:
```powershell
dotnet restore .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx --locked-mode
dotnet build .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-restore
dotnet test .\tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests.csproj -c Release --no-build --filter FullyQualifiedName~PublishedServerTests
dotnet test .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-build
```
The 28 focused published checks reuse the bounded concurrent-drain process
harness, copy the actual publish payload into a task-owned isolated directory,
use an unrelated existing cwd, and clean only owned files/processes. They also
exercise an executable-only copy with host tracing. Tests fail with a publish
instruction if the payload is missing; they do not silently skip packaging.
`RIFFGROOVE_PUBLISHED_SERVER` optionally selects an **absolute executable path**
for test infrastructure only, not an application configuration feature.
Checks cover exactly two tools, seven identities/five Documented profiles, all
four explicit Lead profiles, real Lead+Bass MIDI and combined native fallback,
ABJ Sustain-only discovery/PM rejection, missing Bass selection, disabled fallback, unavailable
selected roles, real-file collision preservation, malformed/schema errors,
ping, cancellation, active/empty EOF and protocol-only stdout.
The eight refreshed published Lead+Bass cases (each guitar plus ABJ, complete
and native fallback) each write/read one **435-byte** MIDI, SHA256
`F31C7C2236637AF9412738418AF61E7D613D51C89A8FFB43B379012C7798384A`.
Read-back verifies Conductor/Lead/Bass, channels 0/1, 32 Lead and four Bass
musical notes, PM26/Sustain24 on0/off30, shared lead-in120 and three end
markers15480. These test-owned files are removed, not presented as retained
examples or application acceptance.
The retained `artifacts\examples\ame-lead-example.mid` was generated through
the **published stdio RPC**, not copied from vendor MIDI or an in-process writer.
Pinned DryWetMIDI 8.0.3 reopened the actual returned path and verified type 1,
960 PPQ, Conductor/Lead tracks, tick-zero 120 BPM/4/4, 32 pitch-64 velocity-96
musical notes at `120 + 480*i`, duration 480, channel 0; switch26/velocity100
on0/off30, shared lead-in120 and both end markers15480. It is 371 bytes, SHA256:
`6F5791FB5C3A7A17E54AAF6436963E4D5723FB948057585060C09BF9B2AFCA3E`.
It demonstrates file semantics, **not Cubase/Ample import or audible acceptance**.
Publication/examples are ignored generated artifacts, retained locally.
To generate another retained example through the same test (existing examples
are preserved and a distinct stem is selected):
```powershell
$env:RIFFGROOVE_RETAIN_EXAMPLE = '1'
try {
dotnet test .\tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests.csproj -c Release --no-build --filter FullyQualifiedName~PublishedRpcGeneratesReadBackExample --logger 'console;verbosity=detailed'
}
finally {
Remove-Item Env:\RIFFGROOVE_RETAIN_EXAMPLE
}
```
Without this opt-in, the test reads back and removes its own example. No
long-lived process is left running. See [format compatibility](format-compatibility.md)
and [mapping evidence](articulation-mappings.md) for the still-blocked AMR/SD3
mappings, ABJ PalmMute, native writers, exact installed versions and licensed-application
acceptance matrix. Successful supported-slice deployment does not complete
the full requested product.