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.mdanddocs/architecture.mdfor implemented startup/protocol. - Change
pyproject.tomlonly if a console entry point or directly necessary typing/test configuration is needed.python -m riff_groove_builderis 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
- 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.
- Register exactly
list_instrument_profilesandgenerate_music. Reusetool_input_schemaandtool_output_schemawithout wrapping or weakening them. Revalidate incoming arguments through their authoritative models, including strict types and cross-field rules. - 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.
- Successful calls include
structuredContentplus a concise text summary. Known domain failures returnisError: trueand the declared typed error. Protocol errors, unknown methods/tools, malformed JSON, invalid parameters, and notifications retain correct SDK behavior. list_instrument_profilescurrently returns the truthful empty registry:{"profiles":[]}. No guessed entries or synthetic production profiles.- Valid
generate_musicrequests 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. - 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.
- 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. - 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.
- 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.
- 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.