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

125 lines
7.0 KiB
Markdown

# Step 3: MCP stdio server skeleton
## Objective and accepted prerequisites
Implement only Step 3 of `prompts/plan.md`. Steps 1 and 2 are accepted after
report/implementation review and independent tests (6 foundation tests and 321
focused contract tests). Use the existing typed contracts; do not redefine them.
Read the plan, reports 1-2, current `schemas.py`, `errors.py`, and package tooling.
Inspect the installed MCP 1.x SDK APIs before choosing the simplest integration.
Do not delegate, commit, create later prompts, implement generation/native
writers, or claim production mapping compatibility.
## Owned files
- Create `src/riff_groove_builder/server.py`.
- Create `src/riff_groove_builder/__main__.py`.
- Create `tests/unit/test_server.py`.
- Create `tests/integration/test_stdio.py`.
- Update `README.md` and `docs/architecture.md` for implemented startup/protocol.
- Change `pyproject.toml` only if a console entry point or directly necessary
typing/test configuration is needed. `python -m riff_groove_builder` is required;
an additional executable/transport is not required.
- Write `prompts/report_3.md`.
Preserve existing models/tests. Explain any tightly coupled change rather than
silently changing the reviewed tool contract.
## Implementation constraints
1. Use the official SDK's stdio transport, Server lifecycle, JSON-RPC parsing,
request IDs, notifications, initialization, negotiation, and EOF shutdown.
Do not hand-roll framing, Content-Length headers, or protocol dispatch.
2. Register exactly `list_instrument_profiles` and `generate_music`. Reuse
`tool_input_schema` and `tool_output_schema` without wrapping or weakening
them. Revalidate incoming arguments through their authoritative models,
including strict types and cross-field rules.
3. Choose the SDK interface that correctly preserves the existing explicit
input/output schemas and structured success/error union. The low-level
official SDK Server is acceptable if its tool decorators are clearer than
FastMCP's inferred schemas. Do not build a second abstraction/framework.
4. Successful calls include `structuredContent` plus a concise text summary.
Known domain failures return `isError: true` and the declared typed error.
Protocol errors, unknown methods/tools, malformed JSON, invalid parameters,
and notifications retain correct SDK behavior.
5. `list_instrument_profiles` currently returns the truthful empty registry:
`{"profiles":[]}`. No guessed entries or synthetic production profiles.
6. Valid `generate_music` requests currently return an explicit development-only
typed error stating that generation is not implemented in this skeleton.
Use an existing error-schema branch with a clear message/reason rather than
pretending a file exists or blaming an unverified native format.
This handler is replaced in Step 9. It must never create artifacts.
7. Validate known model failures into public-safe field/reason details.
Do not echo raw descriptions, arbitrary user values, private fixture paths,
tracebacks, or exception representations into protocol results/logs.
Unexpected operational failures must be visible through standard diagnostics;
do not add broad silent catches or success-shaped fallbacks.
8. Startup: `python -m riff_groove_builder --output-dir <existing-local-directory>`.
Require this option. Reject nonexistent/non-directory roots and clearly
unsafe/non-local forms with stderr diagnostics and nonzero exit.
Resolve/store the root for later service wiring. Do not create files,
auto-create arbitrary roots, or claim writeability before an actual write.
Full publication/link-confinement checks remain Step 9.
9. Keep stdout strictly UTF-8 newline-delimited protocol messages. Startup
messages, logs, and errors go to stderr. Importing either the package or
server module must not start services or print.
10. Keep implementation/test seams small and concrete. An internal create-server
helper is fine; no generic handler registry, HTTP server, plugin framework,
persistent jobs, or external model calls.
11. Document that tool discovery works but generation intentionally remains
unfinished. Include an accurate Windows MCP-client stdio configuration and
existing-root setup example without claiming a client was manually tested.
## Required unit tests
- Both tool definitions exactly reuse the reviewed schemas.
- Input model validation rejects malformed/unknown/strict-type failures.
- Empty profile list has valid structured output and no false capabilities.
- Generation returns the explicit unfinished error and publishes no files.
- Error conversion preserves public code/message while excluding private data.
- Output-root validation and required CLI argument failures.
- Importing server/package is silent and does not run the CLI.
## Required integration tests
Use a real module subprocess, with bounded timeouts and guaranteed process
cleanup. Prefer the official client for the normal handshake, and a small raw
stdio harness only where needed to exercise malformed requests. The harness is
a test client, not production protocol code.
- Initialize, send initialized notification, list tools/schemas, call each tool.
- Verify response-ID preservation and no response to notifications.
- Verify valid structured outputs against the published schemas.
- Exercise invalid tool arguments, unknown tools/methods, malformed JSON, and
SDK-supported malformed-request behavior without assuming every error code is
a parse error. Follow the selected SDK's actual protocol semantics.
- Confirm stdout has only valid JSON-RPC lines; diagnostics remain on stderr.
- Close stdin and verify clean EOF shutdown; no invented shutdown method.
- Missing/bad output root exits nonzero without protocol-noisy stdout.
- Run the module from a different working directory using the installed editable
package, proving no current-directory import assumptions.
- Verify every valid generation call remains explicitly unfinished and creates
no artifacts.
Do not leave child processes running. Do not kill processes by name.
## Verification and acceptance
Run the focused new tests, relevant existing contract/import checks, Ruff
lint/format, strict mypy, and distribution tests if package configuration changes.
The editor test runner is known not to discover this project; the verified
`.venv\Scripts\python.exe -m pytest` CLI fallback is acceptable.
Acceptance: genuine SDK-backed MCP stdio lifecycle and honest tool skeleton,
correct schemas/errors, clean shutdown, protocol-clean stdout, passing checks.
No MIDI/native generation or application acceptance is claimed.
## Required report
When complete, write your end-of-step report to ./prompts/report_3.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
Place the complete report inside exactly one plain triple-backtick fence.
Include exact commands/results, SDK interface choice and observed protocol
behavior, child cleanup, skips/limitations, and Step 4 readiness.