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

7.0 KiB

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.