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

14 KiB

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:

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:

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:

{
  "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):

{
  "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:

{
  "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:

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):

$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 and mapping evidence 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.