173 lines
8.3 KiB
Markdown
173 lines
8.3 KiB
Markdown
# Step 2: Implement stdio JSON-RPC and the MCP lifecycle
|
|
|
|
## Objective and prerequisites
|
|
|
|
Step 1 has been reviewed and accepted: Release build and all eight scaffold
|
|
tests pass. Read [the approved plan](plan.md), [the Step 1 report](report_1.md),
|
|
and existing source/tests before editing.
|
|
|
|
Implement a protocol-correct .NET 10 stdio MCP server, targeting version
|
|
`2025-11-25`. This step is transport/lifecycle/registry infrastructure only.
|
|
Stop before composition, real instrument profiles, generation tools or writers.
|
|
Do not create later prompts, modify orchestrator prompts/plan, commit, or delegate.
|
|
|
|
## Files to create or modify
|
|
|
|
```text
|
|
src\GAJ3T.MusicGen.RiffGrooveBuilder.Server\
|
|
Program.cs
|
|
Protocol\StdioTransport.cs
|
|
Protocol\JsonRpcDispatcher.cs
|
|
Protocol\McpSession.cs
|
|
Protocol\JsonRpcError.cs
|
|
Tools\McpToolRegistry.cs
|
|
Tools\McpToolDefinition.cs
|
|
tests\GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests\
|
|
GAJ3T.MusicGen.RiffGrooveBuilder.UnitTests.csproj
|
|
Protocol\StdioTransportTests.cs
|
|
Protocol\JsonRpcDispatcherTests.cs
|
|
Protocol\McpSessionTests.cs
|
|
tests\GAJ3T.MusicGen.RiffGrooveBuilder.IntegrationTests\
|
|
Stdio\ProcessStartupTests.cs
|
|
Stdio\McpProtocolTests.cs
|
|
README.md
|
|
docs\mcp-protocol.md
|
|
prompts\report_2.md
|
|
```
|
|
|
|
Small directly necessary protocol/test helper files are allowed. Prefer simple
|
|
typed contracts over a generic framework. Add a Server project reference to
|
|
UnitTests if needed. No new package is required; use System.Text.Json and BCL.
|
|
Refresh generated lock files only if the project reference change requires it.
|
|
|
|
## Protocol requirements
|
|
|
|
### Transport
|
|
|
|
- UTF-8, newline-delimited JSON-RPC, never `Content-Length` framing.
|
|
Serialized JSON strings may contain escaped newlines, not literal message
|
|
framing newlines. Accept LF and CRLF. Flush each completed output message.
|
|
- Stdout contains only complete protocol messages. Serialize writes so
|
|
overlapping request work cannot interleave JSON. Diagnostics use stderr.
|
|
- Bound incoming messages while reading, not only after allocating an
|
|
unbounded line. Use a documented internal limit (1 MiB is acceptable).
|
|
Reject an oversized frame with an explicit bounded diagnostic/protocol error,
|
|
resynchronize at its newline, and test continued operation.
|
|
- Reject invalid UTF-8 without silently substituting characters. Handle a final
|
|
nonempty frame at EOF explicitly and test the documented behavior.
|
|
- EOF and Ctrl+C shut down cleanly, cancelling outstanding work and disposing
|
|
only owned resources. An empty stdin stream produces no output.
|
|
|
|
### JSON-RPC
|
|
|
|
- Require `jsonrpc: "2.0"` and a string method for inbound requests/notifications.
|
|
Validate params shape against the method. Preserve supported string/integer
|
|
request IDs in responses; do not coerce strings to numbers.
|
|
- Reject malformed JSON with -32700, invalid envelopes/batch arrays with
|
|
-32600, unknown request methods with -32601, invalid method/tool parameters
|
|
with -32602, and unexpected internal failures with -32603.
|
|
- Error response `id` is null when no valid request ID can be identified.
|
|
Never answer a valid notification, including unknown notifications.
|
|
- Do not process JSON-RPC batches as a supported MCP feature.
|
|
- An exception boundary may report unexpected per-request failures explicitly,
|
|
log details to stderr and return -32603. Do not suppress exceptions into
|
|
success results or hide actual I/O failures.
|
|
|
|
### Lifecycle
|
|
|
|
- Support `initialize`, `notifications/initialized`, `ping`, `tools/list`,
|
|
`tools/call`, and `notifications/cancelled`.
|
|
- Validate initialization fields per the MCP specification. Return serverInfo,
|
|
supported protocolVersion and only implemented capabilities.
|
|
- Negotiate version: echo `2025-11-25` when requested; otherwise return
|
|
`2025-11-25` as the server's supported alternative. Do not claim support for
|
|
other protocol versions.
|
|
- Enforce initialization state and reject inappropriate requests with explicit
|
|
errors. Permit ping per lifecycle rules. Reject repeated initialization.
|
|
- Use stdin closure for shutdown, not an invented `shutdown` method.
|
|
- Ignore/log unsupported notifications without replying.
|
|
- Track outstanding request IDs and propagate valid cancellation notifications
|
|
to the matching active request; cancellation is not cancellation of the whole
|
|
server. Keep reading notifications while a handler is awaiting work.
|
|
- Keep lifecycle changes/registry access safe when work overlaps. Distinguish
|
|
requests with different ID types. Do not let duplicate active IDs cancel or
|
|
replace unrelated work.
|
|
|
|
### Tool registry
|
|
|
|
- Implement registration/lookup and schema serialization for tool definitions.
|
|
- Production registry is initially empty: `tools/list` returns `tools: []`.
|
|
Do not advertise placeholder profile/generation tools.
|
|
- An unknown tool is a protocol/tool-selection error, not a fake successful call.
|
|
- Provide a bounded typed handler boundary supporting input validation,
|
|
structuredContent plus text content, expected tool errors (`isError: true`),
|
|
and cancellation. Synthetic test-only tools can exercise these paths.
|
|
- Do not implement MCP resources, prompts, sampling, logging RPCs, task APIs,
|
|
HTTP, composition, or real generation in this step.
|
|
|
|
Use the primary MCP sources referenced in the plan to resolve protocol details.
|
|
Document supported/unsupported methods and capability/version behavior.
|
|
|
|
## Required tests
|
|
|
|
### Unit tests
|
|
|
|
Cover:
|
|
|
|
1. LF/CRLF framing, escaped newline content, UTF-8/non-ASCII content, invalid UTF-8,
|
|
empty EOF and the documented non-newline final-frame behavior.
|
|
2. Message size at/over the limit, resynchronization, complete serialized output.
|
|
3. Valid string/integer IDs, malformed JSON, invalid envelopes/IDs, batch
|
|
rejection, unknown methods and invalid params.
|
|
4. Notifications produce no response, even unknown ones.
|
|
5. Initialization success, unsupported-version negotiation, premature requests,
|
|
initialized transition, repeated initialization and ping.
|
|
6. Empty production registry; test-only registered tool discovery/calls and
|
|
schema/content agreement; unknown tool and handler validation failures.
|
|
7. A cancellable synthetic handler cancelled while awaiting work, unrelated
|
|
request survival, and overlapping response serialization.
|
|
|
|
Retain the meaningful framework/dependency scaffold unit tests.
|
|
|
|
### Real-process integration tests
|
|
|
|
- Update the prior input-discard startup test: only empty EOF remains silently
|
|
successful. Non-JSON input must now yield a parse error, not be discarded.
|
|
- Launch the real Server apphost, negotiate initialization, send
|
|
`notifications/initialized`, list empty tools, ping, and close stdin.
|
|
- Assert response IDs, MCP version/capabilities, per-line valid JSON, no
|
|
notification reply, empty or diagnostic-only stderr, and exit code zero.
|
|
- Exercise malformed input followed by a valid request on the same connection,
|
|
unknown method/tool, invalid arguments, and an unrelated working directory.
|
|
- Include timeout-bounded cleanup and concurrent draining of stdout/stderr.
|
|
Never kill by process name or leave a helper running.
|
|
|
|
## Validation and acceptance
|
|
|
|
Run targeted protocol tests during development, then:
|
|
|
|
```powershell
|
|
dotnet build .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-restore
|
|
dotnet test .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx -c Release --no-build
|
|
dotnet restore .\GAJ3T.MusicGen.RiffGrooveBuilder.slnx --locked-mode
|
|
```
|
|
|
|
If changed manifests make assets stale, restore after the manifest change.
|
|
The installed SDK is at `C:\Program Files\dotnet\dotnet.exe`; use a process-local
|
|
PATH adjustment if needed. The editor test tool failed discovery in Step 1;
|
|
CLI xUnit execution is the verified fallback, not a skipped test.
|
|
|
|
Exit criteria: actual stdio MCP lifecycle works, all tests pass including
|
|
retained scaffold coverage, no non-protocol stdout, no unimplemented tools
|
|
advertised, documentation matches behavior, and no scope expansion.
|
|
|
|
## Mandatory worker report
|
|
|
|
When complete, write your end-of-step report to ./prompts/report_2.md including: what was implemented, test results (pass/fail with details), any issues encountered, and whether you're ready for the next step
|
|
|
|
Put the entire report inside exactly one plain triple-backtick fence, with no
|
|
outside content. Include changed files, exact commands/exit codes, test counts,
|
|
protocol limits and decisions, any skipped checks, issues/blockers, and explicit
|
|
Step 2 readiness. Native compatibility remains unverified and outside this step.
|
|
Stop after writing the report.
|