256 lines
14 KiB
Markdown
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.
|