273 lines
17 KiB
Markdown
273 lines
17 KiB
Markdown
# Stdio MCP protocol and generation tools (Steps 2/8)
|
|
|
|
## Scope and negotiation
|
|
|
|
The .NET 10 Server apphost implements a small local stdio MCP server using
|
|
`System.Text.Json` and the BCL. It supports **only MCP `2025-11-25`**. An
|
|
`initialize` request for that version is echoed; any other string version
|
|
receives `2025-11-25` as the supported alternative. A client that cannot use
|
|
this version should disconnect. No network connection is made.
|
|
|
|
The only advertised capability is `tools: { "listChanged": false }`. The
|
|
production registry contains exactly `list_instrument_profiles` and
|
|
`generate_project`. No fake profiles, native writers or synthetic test tools
|
|
are advertised. Server identity is
|
|
`GAJ3T.MusicGen.RiffGrooveBuilder`, implementation version `0.2.0`.
|
|
|
|
## Framing and ownership
|
|
|
|
- Messages are strict UTF-8 JSON, delimited by LF or CRLF, not `Content-Length`
|
|
framing. A BOM is not removed. Invalid UTF-8 produces `-32700`, never
|
|
replacement characters. JSON strings can contain escaped `\n`; a literal
|
|
newline terminates the frame.
|
|
- The production limit is **1,048,576 UTF-8 bytes per incoming frame**, excluding
|
|
its LF or CRLF terminator. Exactly the limit is accepted. Reading uses a
|
|
fixed limit-plus-one frame buffer and a 4 KiB read buffer: an oversized
|
|
message is drained without accumulating its remainder. At its newline (or
|
|
EOF), one bounded `-32600` response with `id: null` and a fixed stderr
|
|
diagnostic is emitted, then processing resumes at the next frame.
|
|
- JSON parsing also applies `System.Text.Json`'s default maximum nesting depth
|
|
of 64. Exceeding it returns a parse error.
|
|
- An empty stream produces nothing. A nonempty final frame at EOF is processed
|
|
once, even without a trailing newline. A blank line is an empty JSON frame
|
|
and returns `-32700`. An incomplete final JSON document returns `-32700`.
|
|
- Every output is a complete compact JSON-RPC object followed by LF and a
|
|
flush. A write lock prevents concurrent responses from interleaving. A write
|
|
already in progress is not truncated by request cancellation.
|
|
- The transport borrows its streams; the entry point owns/disposes the streams
|
|
it opens. It never disposes the caller's diagnostic writer.
|
|
- EOF or Ctrl+C cancels active work and awaits its cancellation/cleanup. There
|
|
is no `shutdown` RPC. Fatal input/output failures are written to stderr and
|
|
exit with code 1; normal EOF/cancellation exits with code 0. Per-request
|
|
unexpected failures return `-32603` and diagnostic details only on stderr.
|
|
|
|
## Methods and lifecycle
|
|
|
|
| Method | Behavior |
|
|
| --- | --- |
|
|
| `initialize` | Request, once only. Requires object params containing string `protocolVersion`, object `capabilities`, and `clientInfo` with string `name` and `version`. Optional known metadata/capability fields are type-checked, including icons and nested client capability objects. Unknown client capability keys are allowed but never used. Successful initialization waits for `notifications/initialized`. |
|
|
| `notifications/initialized` | Notification with omitted or empty object params (optional object `_meta`). Transitions an initialized session to ready. Out-of-order, repeated or invalid notifications are ignored with a diagnostic and no response. |
|
|
| `ping` | Request allowed before, during and after initialization. Omitted/empty object params, optional `_meta`; returns `{}`. |
|
|
| `tools/list` | Requires ready state. Omitted/empty object params, optional `_meta`; returns the two production tools in stable name order with input/output schemas. No pagination cursor is issued; any supplied cursor is rejected. |
|
|
| `tools/call` | Requires ready state and object params with string `name`, optional object `arguments` (defaults to `{}`), optional `_meta`. Unknown tool or invalid arguments return `-32602`. |
|
|
| `notifications/cancelled` | Validates `requestId` and optional string `reason`. Cancels only the matching active request, never `initialize` or the server. Malformed, unknown or completed IDs are ignored. Reasons are not echoed. No notification response; a cancelled request normally has no response either. |
|
|
|
|
Fixed method params reject unknown members (including task augmentation);
|
|
`_meta` accepts extension fields, and request `_meta.progressToken`, if present,
|
|
must be a string or number. Client capabilities and implementation metadata
|
|
are not fetched or acted on. Tools cannot run before the complete handshake.
|
|
Known tool requests in the wrong state return `-32002`. Repeated initialization
|
|
returns `-32002`. Unknown request methods always return `-32601`, including
|
|
request-shaped notification methods.
|
|
|
|
Valid notifications never receive a response, including unsupported methods
|
|
and requests mistakenly sent without an ID. Unsupported notifications are
|
|
ignored with a fixed diagnostic; they cannot initialize or invoke a tool.
|
|
Malformed envelopes are invalid requests, not valid notifications.
|
|
|
|
Resources, prompts, sampling, elicitation, logging RPCs, progress emission,
|
|
task APIs, HTTP, server-initiated requests, and list-change notifications are
|
|
not implemented or advertised.
|
|
|
|
## JSON-RPC validation and errors
|
|
|
|
Requests/notifications require `jsonrpc: "2.0"` and a string `method`. Requests
|
|
use a string or signed 64-bit integer ID. String and numeric IDs are distinct;
|
|
responses preserve their values and types, not necessarily JSON escape spelling.
|
|
Null, boolean, fractional/exponent/decimal numeric IDs and integers outside
|
|
Int64 are unsupported. An unambiguous valid ID is preserved on an invalid
|
|
envelope; otherwise error `id` is null. Duplicate envelope member names and
|
|
batch arrays are rejected; MCP batch execution is not supported.
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| `-32700` | Malformed JSON, blank frame, or invalid UTF-8 |
|
|
| `-32600` | Invalid envelope/ID, batch, duplicate active request ID, oversized frame |
|
|
| `-32601` | Unknown request method |
|
|
| `-32602` | Invalid method params, unknown tool, invalid typed/semantic tool arguments or cursor |
|
|
| `-32603` | Unexpected handler/result-serialization failure |
|
|
| `-32002` | Inappropriate lifecycle state |
|
|
| `-32000` | Request admission limit reached |
|
|
|
|
There are at most **64 active requests**. Excess requests get an explicit
|
|
bounded error without blocking notification dispatch. The ID table never
|
|
replaces an active request: a duplicate receives `-32600` without cancelling or
|
|
overwriting the original. Async tool work does not block reading cancellation
|
|
or unrelated requests. Responses may complete out of order. Once a response
|
|
write has started, cancellation may race with its delivery; clients must
|
|
tolerate a late response. Registry snapshots and lifecycle/ID state are
|
|
synchronized.
|
|
|
|
## Typed tool boundary
|
|
|
|
Registration is internal application setup, not a user plugin/RPC feature.
|
|
Register uniquely named definitions before creating the session; the session
|
|
freezes the registry and does not emit list-change notifications.
|
|
|
|
`McpToolDefinition<TInput,TOutput>` uses non-null object DTO contracts. The same
|
|
strict camel-case serializer options generate output/default input JSON Schemas
|
|
with the .NET JSON Schema exporter (default JSON Schema 2020-12), deserialize
|
|
arguments and serialize results. Required constructor members, non-nullable
|
|
properties, types, duplicate properties and unknown members are validated.
|
|
Optional semantic validation raises `McpToolInputException` for `-32602`.
|
|
Enums serialize as camel-case strings, never integers. Production tools supply
|
|
explicit constrained input schemas, matching validators (including exact enum
|
|
case, non-null optional inputs, uniqueness and nested profiles), and a small
|
|
output-schema refinement for successful versus failed generation.
|
|
This remains a typed boundary, not a general-purpose arbitrary JSON Schema
|
|
engine; domain constraints are enforced by the registered validator/handler.
|
|
|
|
Handlers accept a request-scoped `CancellationToken` and must honor it and
|
|
clean up owned resources. They return `McpToolOutcome<TOutput>`: the emitted
|
|
object contains `structuredContent`, an identical serialized JSON text block
|
|
in `content`, and `isError`. Expected execution failures explicitly return a
|
|
typed schema-conforming outcome with `isError: true`; unexpected exceptions
|
|
never become successful tool results.
|
|
|
|
## Production tools (Step 8)
|
|
|
|
### `list_instrument_profiles`
|
|
|
|
The optional `role` is exactly `lead`, `bass` or `drums`. Omit it for all;
|
|
explicit null, integers, other casing and unknown fields are invalid params.
|
|
Output includes:
|
|
|
|
- `instruments`: stable `id`, `vendor`, `productCode`, `displayName`, `role`,
|
|
`documentationUrl`, `availability` (`profile_available`/`mapping_unavailable`).
|
|
- `profiles`: `id`, `instrumentId`, role/product/version/mapping revision,
|
|
`playableRange` (absolute minimum/maximum pitches), zero-based `channel`,
|
|
`articulations` (mechanisms, velocity constraints, behavior, explicit switch/
|
|
controller/voice data), `evidence`, `compatibilityNotes`, `nativeFormats`,
|
|
and `nativeStatus:"unverified"`.
|
|
- `formats`: `mid` has `writerStatus:"implemented"`; `agp`/`sdp` have
|
|
`writerStatus:"unavailable"`. Each `applicationStatus` is `unverified`.
|
|
|
|
Seven declared identities and five Documented profiles are currently
|
|
exposed: AGLP/AGM/AGT/AME Lead Sustain/PalmMute, ABJ Bass Sustain only.
|
|
AMR and SD3 have no admitted map. ABJ discovery advertises one articulation,
|
|
musical velocities 1-125 and zero-based channel 1; Lead uses channel 0.
|
|
Documented means source-backed,
|
|
not installed/application-verified; no synthetic/test fixture is exposed.
|
|
Native format applicability is not writer availability or application acceptance.
|
|
The embedded catalog is independent of cwd; runtime profile/VST loading is absent.
|
|
|
|
### `generate_project`
|
|
|
|
| Input | Contract |
|
|
| --- | --- |
|
|
| `description` | Required string, 1..16384 characters; the [bounded grammar](text-description-contract.md) applies |
|
|
| `outputDirectory` | Required nonempty string; explicit absolute filesystem directory, no traversal/device syntax |
|
|
| `projectName` | Required nonempty safe filename stem; no separators, traversal, reserved devices, alternate streams, trailing dot/space |
|
|
| `formats` | Optional nonempty unique array of exact strings `agp`, `sdp`, `mid`; omit for applicable native formats plus MIDI |
|
|
| `profiles` | Optional fixed object with optional nonempty string `lead`, `bass`, `drums` profile IDs; every selected role needs an explicit matching admitted ID |
|
|
| `fallbackToMidi` | Optional boolean, defaults true |
|
|
|
|
All fixed request/nested objects reject unknown/duplicate members. Supplied null
|
|
fields are not accepted. There is no automatic profile default or substitution.
|
|
Only explicitly selected roles are resolved; profiles for unselected roles fail.
|
|
Text that omits roles still follows the grammar's three-role default and fails
|
|
missing explicit Lead/Bass selections and unavailable Drums instead of silently
|
|
removing them. Missing Bass selection now returns `no_default_profile`, not
|
|
`mapping_unavailable`; unmapped Drums still returns `mapping_unavailable`.
|
|
Explicit ABJ PalmMute fails `unsupported_articulation`, never Sustain fallback.
|
|
Role-to-instrument binding is resolved from the admitted profile, not user folders.
|
|
|
|
The structured result has all of these required keys:
|
|
|
|
```text
|
|
status: complete | fallback | failed
|
|
interpretedComposition: { tempoBpm, meter, key, bars, roles, defaultsApplied } | null
|
|
artifacts: [{ format, roles, absolutePath, byteCount, profileIds }]
|
|
targets: [{
|
|
role, instrumentId, profileId, requestedFormat, outcome,
|
|
artifactPaths, reasonCode, message
|
|
}]
|
|
warnings: [{ code, message, role, requestedFormat }]
|
|
errors: [{ code, message, field, role }]
|
|
timing: { ticksPerQuarterNote, leadInTicks } | null
|
|
```
|
|
|
|
Enums are strings (target `outcome`: `written`, `fallback`, `failed`). Nullable
|
|
identity/reason/diagnostic fields are serialized explicitly as null, not omitted.
|
|
Early failures have null interpreted composition/timing. Other failures can retain
|
|
successful interpretation/planning details. The advertised conditional output
|
|
schema allows null composition/timing only for `failed`, requires nonempty
|
|
artifacts/targets and empty errors for success, and no artifacts plus nonempty
|
|
errors for failure. Artifact byte counts and absolute paths describe real,
|
|
nonempty files. Every applicable role/requested-format pair has a target; combined
|
|
MIDI targets share one path. Inapplicable requested formats instead fail globally.
|
|
Structured content is repeated byte-for-byte as serialized JSON in one text block;
|
|
`isError` is true only for `failed`, false for `complete` and `fallback`.
|
|
|
|
`agp` applies to selected Lead/Bass; `sdp` to selected Drums. Lead-only omitted
|
|
formats therefore mean AGP+MIDI, not SDP. Explicit inapplicable formats fail.
|
|
Both native writers are absent: applicable native requests with fallback enabled
|
|
write exactly one `<projectName>.mid` for the complete selected event plan.
|
|
An explicit MIDI request reuses that artifact. Each native target reports
|
|
`native_writer_unavailable`, and a warning discloses unverified compatibility.
|
|
There are no native files/placeholders/renamed MIDI files. With fallback disabled,
|
|
native requests fail before directory creation/output; MIDI-only still succeeds.
|
|
Every selected Documented mapping produces a warning containing source-only
|
|
status and the exact version/configuration/routing/timing compatibility notes.
|
|
|
|
Expected domain failures return `status:"failed"`, no artifacts, actionable
|
|
`errors` and failed targets with no usable paths. Codes include
|
|
`no_default_profile` (with available IDs), `unknown_profile`,
|
|
`profile_role_mismatch`, `unselected_role_profile`, `mapping_unavailable`,
|
|
`inapplicable_format`, `native_fallback_disabled`, `invalid_formats`,
|
|
`invalid_output_path`, parser/planner diagnostics, `midi_not_supported`,
|
|
`output_exists`, and `output_io_error`. Contract/JSON violations use `-32602`
|
|
instead. Invalid mappings/text, MIDI limitations, I/O, cancellation and unexpected
|
|
exceptions never trigger native fallback. Unexpected failures use the existing
|
|
logged `-32603` boundary, with details on stderr only.
|
|
|
|
Semantic/profile/native-format and shared MIDI meter/extent preflight occur
|
|
before directory creation. Generation calls the real staged no-overwrite MIDI
|
|
writer; early existence checks are not the race-safety mechanism. Only this
|
|
request's staging file is cleaned on failure/cancellation; existing destinations,
|
|
other requests' files and unrelated files are preserved. A created directory
|
|
may remain empty after an I/O failure. Cleanup/close failures retain aggregate
|
|
diagnostics and any remaining staging path at the logged error boundary.
|
|
|
|
Generation runs on a thread-pool worker, including text planning, profile/event
|
|
planning and synchronous filesystem/DryWetMIDI work. The reader stays available
|
|
for ping and cancellation; deterministic blocked-work unit tests verify this
|
|
even when tiny real requests finish too quickly. Cancellation propagates without
|
|
a tool response and is checked before publication. The library's synchronous
|
|
serialization has no cancellation API; a token cannot interrupt that call but
|
|
observed cancellation afterward prevents publication and cleans staging.
|
|
Publication is the commit point; cancellation racing after the last check/move
|
|
does not roll back the committed file. EOF cancels active requests: clients must
|
|
keep stdin open and wait for responses before closing it.
|
|
|
|
## Validation and primary references
|
|
|
|
Unit tests cover framing at/over the limit, strict UTF-8/EOF, serialized flushed
|
|
writes, envelopes and error codes, negotiation/state, schemas/results,
|
|
test-only handlers, cancellation with unrelated work surviving, duplicate
|
|
typed IDs, admission limits and fatal I/O. Real-apphost tests cover handshake,
|
|
notification silence, malformed-frame recovery, unknown methods/tools, invalid
|
|
params, LF/CRLF, Unicode IDs, exact-limit/oversized/invalid-UTF-8 frames and final
|
|
frames at EOF from both test-output and unrelated working directories.
|
|
Production-tool tests add strict schemas versus serialized results, discovery/
|
|
filtering, real RPC-generated MIDI read-back for all five admitted capabilities
|
|
and complete Lead+Bass arrangements, native
|
|
fallback and disabled fallback, selected-role/mapping failures, collisions,
|
|
responsive ping/cancellation and unchanged stdout purity.
|
|
All subprocess tests concurrently drain stdout/stderr and enforce bounded,
|
|
process-owned cleanup. Lifetime-token cancellation (the Ctrl+C code path) is
|
|
unit-tested; sending an actual interactive Windows console Ctrl+C event is not
|
|
an automated apphost test.
|
|
|
|
Primary MCP 2025-11-25 sources:
|
|
|
|
- [Transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
|
|
- [Lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
|
|
- [Cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation)
|
|
- [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
|
|
- [Schema](https://modelcontextprotocol.io/specification/2025-11-25/schema)
|
|
|
|
Native compatibility and full product readiness remain unverified; see
|
|
[the evidence inventory](format-compatibility.md). Publication and actual
|
|
plugin/Cubase acceptance belong to later steps.
|