125 lines
7.0 KiB
Markdown
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.
|