Cubase-MCP-GAJ3T.MusicGen.R.../prompts/step_8.md

187 lines
9.8 KiB
Markdown

# Step 8: Wire truthful profile discovery and MIDI generation into MCP
## Objective, sequencing and stop boundary
Read the updated [plan](plan.md), [profile report](report_4.md), [MIDI writer
report](report_5.md), and existing source/tests first.
Accepted baseline: 714 tests; two source-Documented default profiles (AGLP/AME),
five declared-but-unmapped targets, actual type-1 MIDI writing and no production
MCP tools. The owner requested continuation.
Implement both planned tools and the real text -> admitted profile -> MIDI
pipeline now. Native codecs remain unavailable: exercise explicit MIDI fallback
without fake writers or success claims. This sequencing does not mark native
Steps 6/7 completed or establish application compatibility.
Work only this step. Preserve existing changes, especially the source-backed
profile work. Do not modify orchestrator prompts/plan, write later prompts,
commit, delegate, implement AGP/SDP encoding or start publishing.
## Files and architecture
Create/modify directly necessary files under:
```text
src\GAJ3T.MusicGen.RiffGrooveBuilder.Core\Generation\
GenerateProjectRequest.cs
GenerationResult.cs
src\GAJ3T.MusicGen.RiffGrooveBuilder.Generation\
GenerationService.cs
Output\ # Shared filename/path validation if needed
Midi\MidiFileWriter.cs # Only for actual shared-helper extraction
src\GAJ3T.MusicGen.RiffGrooveBuilder.Server\
Program.cs
Tools\MusicGenTools.cs
Tools\McpToolDefinition.cs # Only necessary schema/serialization support
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
Generation\GenerationServiceTests.cs
Protocol\ # Contract/schema/tool factory coverage
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
Stdio\McpGenerationTests.cs
Stdio\McpProtocolTests.cs
Stdio\McpProcess.cs
README.md
docs\mcp-protocol.md
docs\format-compatibility.md
prompts\report_8.md
```
Small genuinely needed DTO/helper files are allowed. Keep Core independent of
DryWetMIDI. No new package, project, HTTP, GUI, runtime profile/VST loading,
audio, cloud, CLI generation command or configuration framework.
Reuse the existing typed tool registry/serializer, parser, profile catalog,
articulation planner and staged MIDI writer. Avoid duplicate path logic:
extract a small shared helper only if both consumers actually need it.
## Public tool contracts
Register exactly `list_instrument_profiles` and `generate_project` in production.
Keep JSON-RPC/MCP lifecycle behavior and stdout purity intact.
### `list_instrument_profiles`
- Optional role filter: lead/bass/drums.
- Return all matching declared instruments and their mapping availability,
plus matching admitted profiles. Seven identities remain visible; two
Documented Lead profiles are available, five targets remain unavailable.
- Expose stable IDs, vendor/product identity, role, documentation URL,
profile-to-instrument binding, product/version scope, mapping revision,
playable range, supported articulations/mechanisms, evidence status and
immutable compatibility notes.
- Native statuses are unverified/unavailable with no native writer. MIDI is the
implemented output capability. Mapping availability is not native support or
installed-plugin acceptance. No synthetic/test profile or fixture is exposed.
### `generate_project`
Inputs as in the plan:
- Required description, absolute outputDirectory, safe projectName stem.
- Optional unique nonempty formats array (`agp`, `sdp`, `mid`).
- Optional profiles object (lead/bass/drums profile IDs).
- fallbackToMidi defaults true.
Publish explicit input/output JSON Schemas: required fields, string enums,
nonempty/unique formats and additionalProperties:false. Actual serialization
must match advertised schemas, including enums and nullable failure fields.
Use minimal shared typed schema support; do not replace the registry framework.
Result must include the plan's status, interpretedComposition/defaults, artifacts,
per-role/per-requested-format targets (with instrumentId/profileId), warnings,
errors and timing. Byte counts/absolute paths must reflect real existing files.
Wrap structuredContent with matching serialized JSON text content.
isError is true only for failed results, not explicitly requested fallback.
## Exact generation semantics
1. Validate request, parse/plan text, then resolve exactly the selected roles.
Profile ID selection must match the role/instrument and catalog admission.
There is no authorized automatic role default: missing selection must give
an actionable diagnostic listing relevant available IDs. Do not choose the
first guitar or silently substitute another instrument.
2. A selected Bass/Drums/unmapped target cannot be dropped just because its
profile is unavailable. Fail explicitly with no artifact. Supplying a
profile for an unselected role also fails rather than being ignored.
3. Every Documented profile generates a compatibility warning containing its
source-only status and relevant configuration/version/routing/timing scope.
It must never be described as installed/application verified.
4. Omitted formats mean applicable native formats for selected roles plus MIDI.
For a Lead-only description that is AGP + MIDI, NOT an inapplicable SDP
request. Explicit inapplicable formats fail actionably.
5. Native AGP/SDP writers do not exist. If applicable native output is requested
with fallback true, produce ONE actual combined MIDI file using the same
complete event plan; return status=fallback, per-target fallback reasons and
native-unavailable warnings. Reuse an explicitly requested MIDI artifact;
do not emit duplicate files or renamed MIDI/native placeholders.
6. If native output is requested with fallback false, fail preflight before any
output. A MIDI-only request succeeds regardless of fallback=false and has
status=complete, with documented-profile warnings as applicable.
7. Output is `<projectName>.mid`, conductor plus selected named role tracks,
preserving the verified writer semantics, source pitches and controls.
8. Validate filenames/traversal/reserved names and output path. Do not overwrite
existing output, including races. Create the explicitly chosen directory only
after semantic/profile/format preflight. Never invoke a shell for generation.
9. MIDI-format limitations, invalid input, missing mappings, I/O errors,
cancellation and unexpected failures are NOT native-fallback triggers.
Expected failures return actionable fields/codes; unexpected exceptions use
the existing logged JSON-RPC internal-error boundary. Propagate cancellation
and clean only request-owned staging/output paths.
10. Keep actual work off the transport reader's synchronous path so pings and
cancellation can be read while generation runs. Honor cancellation before
publication; document synchronous DryWetMIDI serialization boundaries.
Single-file staging is already implemented; do not create a speculative
multi-native-output transaction framework. Do not edit the text grammar to
silently accept instrument/genre instructions it does not support.
## Required tests
### Unit / contract tests
- Exactly two registered production tools; empty/test-only registries continue
to work in existing unit tests.
- Discovery filtering, seven identities/two Documented profiles, unavailable
targets, evidence/compatibility and truthful format capabilities.
- Exact input/output schemas versus serialized results; enum/string values,
required/unknown/null fields, defaults, unique/nonempty formats and nested
profile object validation.
- Valid explicit AGLP and AME Lead requests; missing/unknown/wrong-role/unselected
profile, unavailable Bass/Drums, invalid text/path/name/formats, and errors
without partial usable output.
- Native-only and native+MIDI fallback produce one MIDI artifact and complete
per-target diagnostics; disabled fallback fails preflight; MIDI-only works
with fallback disabled; omitted formats respect role applicability.
- Documented warnings always survive successful/fallback generation.
- Collision/no overwrite, cancellation/I/O errors, limits and cleanup.
### Real subprocess integration
- Launch the actual server, initialize, discover the two tools, list profiles,
then generate via tools/call using each admitted profile:
description `palm-muted eighth-note lead`, formats=[mid] and a unique stem.
- Read the returned file with DryWetMIDI: type 1/960 PPQ, tempo/meter, conductor/
Lead, expected notes and switches, lead-in and end markers.
- Native fallback, disabled fallback, no invented AGP/SDP artifacts, invalid
profiles/roles/requests, preserved existing files and no undisclosed partials.
- Assert outputSchema/result shape, structured/text content agreement, isError/
status consistency, protocol-only stdout, unrelated cwd and bounded cleanup.
- Verify ping and cancellation remain responsive during asynchronous work;
use deterministic unit seams where real tiny requests complete too quickly.
- Update prior real-process empty-discovery expectations to the intentional
two-tool behavior, preserving unrelated protocol regressions.
## Validation and mandatory report
Run targeted Generation/MCP tests, then Release build, all xUnit tests and locked
restore. No package changes are needed. Use installed .NET 10 and DryWetMIDI
8.0.3, with the established CLI fallback for unavailable editor discovery.
When complete, write your end-of-step report to ./prompts/report_8.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
Entire report: exactly one plain triple-backtick fence. Include changed files,
exact commands/counts, real RPC-generated file/read-back evidence, documented
profile disclosure, native/mapping limits and explicit supported-slice readiness.
Stop for report review; do not publish or start another worker step.