13 KiB
13 KiB
Step 3 report — SDK-backed MCP stdio server skeleton
Date: 2026-10-19
Result: PASS for Step 3. Ready for Step 4 review/authorization.
IMPLEMENTATION AND PRESERVED SCOPE
Created:
- src\riff_groove_builder\server.py
- src\riff_groove_builder\__main__.py
- tests\unit\test_server.py
- tests\integration\test_stdio.py
- prompts\report_3.md
Updated:
- README.md — actual module startup, existing-root setup, Windows VS Code MCP
configuration, honest tool behavior, and protocol-test commands.
- docs\architecture.md — SDK choice, validation/error/logging boundaries,
observed protocol semantics, lifecycle, and remaining pipeline work.
Read the approved plan, Step 3 prompt, reports 1–2, authoritative schemas/errors,
package/test tooling, and installed SDK implementation/signatures. Existing
models, errors, initializer, foundation/contract/distribution tests, package
configuration, plan, and prior prompts/reports were preserved. pyproject.toml
did not need changes; no console executable or additional transport was added.
No delegation, commits, later prompts, MIDI/native generation, music fixtures,
invented production profiles, external model calls, or service implementation.
SDK INTERFACE AND TOOL CONTRACT
Selected official MCP 1.30.0 low-level Server with its list_tools/call_tool
decorators and mcp.server.stdio.stdio_server transport. The SDK owns UTF-8
newline framing, parsing, request IDs, dispatch, notifications, initialization,
protocol negotiation, lifecycle, and EOF shutdown. No production protocol code
was hand-written; raw framing exists only in the integration-test client.
Exactly list_instrument_profiles and generate_music are registered. Their
inputSchema/outputSchema exactly equal the existing tool_input_schema and
tool_output_schema dictionaries, including the explicit success/error union.
No fields, result branches, or reviewed validation rules were redefined.
call_tool(validate_input=False) deliberately disables the SDK's schema-only
input checker: its errors echo values and JSON Schema accepts 4.0 as an integer.
Authoritative Pydantic input models instead enforce strict types and cross-field
rules. Errors contain only known field names, numeric positions, <unknown>
placeholders, and reason codes; no validation messages, inputs, contexts,
descriptions, arbitrary property names/values, causes, or private paths.
Explicit CallToolResult objects preserve structuredContent, a concise text
summary, and isError. This SDK return path bypasses automatic output-schema
validation; authoritative model constructors validate outputs and unit/real
subprocess tests independently validate them against the published schemas.
Two narrow ignore comments cover only the SDK's untyped decorators; strict
mypy remains enabled, with no configuration relaxation.
Profile listing truthfully returns {"profiles":[]}, isError false, and
"No verified instrument profiles." No mapping/capability claims are invented.
Every valid generate_music call returns isError true and the existing typed
SERIALIZATION_ERROR schema branch, with the explicit message:
"Music generation is not implemented in this development-only stdio skeleton."
Details: {"reason":"generation_not_implemented","development_only":true}.
This provisional code does not claim a serializer ran, blame native support,
publish paths, or create files. Step 9 must replace the unfinished handler.
Known domain errors preserve their public code/message/explicit details only.
Unexpected execution/output-model failures log the failure class to stderr
without traceback/exception values and return an SDK error with a fixed safe
message. They are not silently treated as invalid input or successful fallback.
STARTUP, DIAGNOSTICS, AND IMPORTS
Required startup:
& '.\.venv\Scripts\python.exe' -m riff_groove_builder --output-dir <existing-local-directory>
The CLI resolves an existing root and stores it in the SDK lifespan context.
Missing/nonexistent/file roots and URI, UNC, device, drive-relative, alternate
stream, and control-character forms are rejected. No root is auto-created;
no writeability claim/probe or publication takes place. Full link/reparse-point,
volume, permissions, collision, and publication checks remain Step 9.
Logging is configured only by CLI execution, on stderr. A narrow filter replaces
the selected SDK's value-containing validation/unlisted-tool diagnostics with
fixed messages, without changing dispatch or suppressing operational failures.
Importing package, server, or __main__ is silent and does not start services.
stdout remains exclusively valid UTF-8 newline-delimited JSON-RPC.
The README includes an absolute-path Windows VS Code .vscode\mcp.json example
and operator provisioning example. No manual MCP-client test is claimed.
OBSERVED REAL-SUBPROCESS PROTOCOL BEHAVIOR
- Official ClientSession.initialize performs the normal initialization and
initialized notification; both tools are discovered and called over real
stdio. Published schemas and returned structured content are checked.
- Raw tests independently exercise initialization, both tools, and clean stdout.
String and integer IDs are preserved. Initialized/progress notifications
produce no response; ping barriers and bounded quiet checks verify this.
- Supported requested versions are retained. An unsupported requested version
negotiates to an SDK-supported version; production code hard-codes none.
- Tool validation failures return typed INVALID_REQUEST with isError true.
Unknown tools use SDK text error results ("Unknown tool."), not invented
domain results or success.
- Unknown methods outside the SDK request union and invalid method parameters
return INVALID_PARAMS (-32602). Recognized but unregistered resources/list
reaches SDK dispatch and returns METHOD_NOT_FOUND (-32601).
- Invalid JSON, array messages, and objects missing a required method produce
the SDK's generic notifications/message ("Internal Server Error"), not an
invented parse-error response. Sanitized diagnostics remain on stderr.
The connection subsequently handles ping correctly.
- The installed SDK classifies an object with id:null and a method as a
notification. An unknown such method yields no response, with sanitized
stderr diagnostics. Tests assert actual SDK behavior rather than overriding it.
- Every captured stdout line decodes as UTF-8, ends in a newline, parses as JSON,
and validates as an SDK JSONRPCMessage. SDK generic logging notifications
are protocol messages, not freeform stdout logs.
- Closing stdin exits zero both after a session and before initialization.
No shutdown method is invented.
- Six bad-startup subprocess cases exit nonzero with empty stdout and stderr
diagnostics; nonexistent roots remain absent and unrelated sentinel data
remains intact.
- Editable-install metadata is verified. Real server processes use -I -B,
cleared PYTHONPATH/PYTHONHOME, and a different, otherwise empty working
directory under .test-artifacts. Startup therefore does not depend on cwd
source imports. Unicode request descriptions traverse real UTF-8 stdio.
- Every valid generation call stays explicitly unfinished and leaves its
output directory empty, including native requests with fallback disabled.
ENVIRONMENT AND EXACT FINAL VERIFICATION
Windows AMD64, repository .venv, CPython 3.13.13.
Selected installed versions:
mcp 1.30.0; pydantic 2.14.1; pytest 9.1.1; anyio 4.15.1;
ruff 0.17.1; mypy 2.4.0; jsonschema 4.26.0.
No dependency installation/reinstallation was required or performed.
All commands ran from the repository root. For pytest/build scratch:
$scratch = New-Item -ItemType Directory -Force '.test-artifacts\scratch'
$env:TEMP = $scratch.FullName
$env:TMP = $scratch.FullName
$env:TMPDIR = $scratch.FullName
The combined regression/full-suite run additionally set:
$env:PIP_NO_INDEX = '1'
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_server.py tests\integration\test_stdio.py -q
PASS: 53 passed in 11.94s; 0 failed, 0 skipped.
Breakdown: 36 unit tests and 17 real-process integration tests.
& '.\.venv\Scripts\python.exe' -m pytest tests\unit\test_schemas.py tests\unit\test_errors.py tests\integration\test_contracts.py tests\unit\test_package.py -q
PASS: 325 passed in 1.45s; 0 failed, 0 skipped.
Includes all 321 previously accepted contract checks and four import/foundation
unit checks, unchanged.
& '.\.venv\Scripts\python.exe' -m pytest -q -s
PASS: 380 passed in 19.66s; 0 failed, 0 skipped; no warnings reported.
This includes every new test, all 327 prior tests, and both offline distribution
tests. They build sdist/wheel with --no-isolation, install a separate --no-deps
wheel venv offline, and import its initializer with -I -B outside the checkout.
Observed installed-wheel evidence:
- version and metadata_version: 0.1.0
- cwd: D:\_Repos\Code\GAJ3T\MCPs\MusicGen
- isolated: 1
- module_path: repository-local .test-artifacts\distribution-fd0502e0224b40dfb9ae26b615ebf0e7\wheel-venv\Lib\site-packages\riff_groove_builder\__init__.py
The distribution workspace was removed after successful checks. This existing
wheel test proves package/import safety, not installed-wheel protocol or full
runtime-dependency certification; real protocol tests use the editable install.
& '.\.venv\Scripts\python.exe' -m ruff check .
PASS: All checks passed!
& '.\.venv\Scripts\python.exe' -m ruff format --check .
PASS: 23 files already formatted.
& '.\.venv\Scripts\python.exe' -m mypy
PASS: Success: no issues found in 12 source files.
& '.\.venv\Scripts\python.exe' -m pip check
PASS: No broken requirements found.
git --no-pager diff --check
PASS: no tracked-diff whitespace errors. Existing/new untracked source is
additionally covered by full Ruff lint/format checks.
Editor problems tool: no errors in all four new Python files.
Known editor pytest discovery limitation: used the explicitly authorized,
verified .venv pytest CLI fallback; no editor test pass is claimed.
CHILD CLEANUP AND PERSISTENCE
All real subprocess waits are bounded. Raw fixtures always close stdin, wait
for the exact process, and have an exact-process kill/reap fallback on timeout
or cancellation. Successful EOF tests require return code zero, not forced
termination. Official stdio_client context cleanup closes stdin and applies
the SDK's bounded termination fallback. Blocking startup/import subprocesses
use subprocess.run with a timeout.
Final inspection:
Remaining step/distribution workspaces: []
Remaining matching test child processes: 0
The latter used Get-CimInstance Win32_Process, filtered to the exact repository
.venv executable and test/module command patterns; no process was killed by
name. Per-test workspaces and diagnostics were removed in fixture cleanup.
No background services/tasks were launched. Existing ignored scratch/build
products were not deleted or claimed as generated music.
DEVELOPMENT ISSUES AND CORRECTIONS
The first test collection failed in both new modules because a module-wide
parametrized anyio_backend marker also affected synchronous tests. Replaced it
with an explicit asyncio backend fixture. Initial strict mypy/lint findings
were corrected using typed test case/name collections, separate capability
checks, narrow SDK-decorator ignores, and Ruff formatting.
The first executable run then had 49 passed, 1 failed: a test incorrectly
expected id:null to trigger a malformed-input logging notification. Direct SDK
model inspection proved it is parsed as JSONRPCNotification. Split that case
into its own no-response regression and used a genuinely malformed missing-
method message for the stream-error case. Added clean EOF-before-initialization
and internal-output-validation diagnostic coverage. Final focused/full checks
pass with no remaining step-caused failures.
LIMITATIONS AND STEP 4 READINESS
No genuine Step 3 blocker remains. The SDK-backed skeleton, honest tools,
strict schemas/errors, startup validation, protocol-clean stdout, EOF cleanup,
tests, documentation, and this report are persistent and verified.
Ready for Step 4 review/authorization: controlled event-plan MIDI timing,
scheduling, and writing can proceed against the existing typed contracts.
No Step 4 implementation or later prompt was created.
Generation remains intentionally unavailable until later service wiring.
No production instrument mapping, AGP/SDP layout, lawful native fixture,
Cubase/plugin load-save round trip, or actual application compatibility has
been verified. Those independent evidence gates remain open. No manual client
or application acceptance test ran, and none is represented as a passing
automated test or skip. Only CPython 3.13.13/Windows and the selected dependency
versions were executed; other supported runtimes/platforms/SDK versions are
not certified. Startup syntax checks are not full filesystem confinement.
This is Step 3 readiness, not full-project or production-generation readiness.