243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
```
|
||
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.
|
||
```
|