# 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 `. 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.