22
33module MCP
44 # The per-request `_meta` envelope of the stateless "modern" lifecycle (MCP 2026-07-28, SEP-2575).
5- # The modern lifecycle has no `initialize` handshake: every request identifies its protocol version,
6- # client, and client capabilities through reserved `_meta` keys, and the server validates
7- # each request independently. Servers MUST NOT infer capabilities from prior requests,
8- # which is why the envelope is a per-request value object rather than session state.
5+ # The modern lifecycle has no `initialize` handshake: every request identifies its protocol version
6+ # and client capabilities through reserved `_meta` keys (plus an optional client identity),
7+ # and the server validates each request independently. Servers MUST NOT infer capabilities from
8+ # prior requests, which is why the envelope is a per-request value object rather than session state.
99 #
1010 # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
1111 class RequestEnvelope
@@ -22,26 +22,31 @@ class RequestEnvelope
2222 # finalized (spec PR modelcontextprotocol/modelcontextprotocol#3002). A server MAY omit it.
2323 SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo"
2424
25+ # `clientInfo` is deliberately absent: it became optional after the SEP was finalized
26+ # (spec PR modelcontextprotocol/modelcontextprotocol#3002), so servers MUST accept
27+ # envelopes without it. The TypeScript and Python SDKs validate the same required pair.
2528 REQUIRED_META_KEYS = [
2629 PROTOCOL_VERSION_META_KEY ,
27- CLIENT_INFO_META_KEY ,
2830 CLIENT_CAPABILITIES_META_KEY ,
2931 ] . freeze
3032
3133 class << self
32- # A request is classified as modern only when the full REQUIRED triple is present,
33- # matching the TypeScript SDK's `RequestMetaEnvelopeSchema` and the Python SDK's `_has_modern_envelope`.
34- # A partial triple is treated as legacy so existing `_meta` usage (`progressToken`, trace context) keeps
35- # flowing through the legacy path.
34+ # A request claims the modern lifecycle when its `_meta` carries `io.modelcontextprotocol/protocolVersion`,
35+ # matching the TypeScript SDK's envelope claim and the Python SDK's `_has_modern_envelope`.
36+ # Classification is deliberately looser than validation: a claimed-but-malformed envelope is
37+ # rejected by {parse!} with `-32602` instead of silently flowing through the legacy path,
38+ # while `_meta` without the claim key (`progressToken`, trace context) stays legacy.
3639 def modern? ( params )
3740 meta = extract_meta ( params )
3841 return false unless meta . is_a? ( Hash )
3942
40- REQUIRED_META_KEYS . all? { | key | !read ( meta , key ) . nil? }
43+ !read ( meta , PROTOCOL_VERSION_META_KEY ) . nil?
4144 end
4245
43- # Parses and validates the envelope. `request` is only used to enrich the raised error;
44- # callers dispatching notifications can omit it.
46+ # Parses and validates the envelope: `protocolVersion` and `clientCapabilities` are required,
47+ # `clientInfo` is optional. A missing or mistyped field is Invalid params (`-32602`) naming
48+ # the offending keys, the code and shape the spec mandates and the reference SDKs emit.
49+ # `request` is only used to enrich the raised error; callers dispatching notifications can omit it.
4550 def parse! ( params , request : nil )
4651 meta = extract_meta ( params )
4752 meta = { } unless meta . is_a? ( Hash )
@@ -50,11 +55,17 @@ def parse!(params, request: nil)
5055 client_info = read ( meta , CLIENT_INFO_META_KEY )
5156 client_capabilities = read ( meta , CLIENT_CAPABILITIES_META_KEY )
5257
53- unless protocol_version . is_a? ( String ) && client_info . is_a? ( Hash ) && client_capabilities . is_a? ( Hash )
58+ invalid_keys = [ ]
59+ invalid_keys << PROTOCOL_VERSION_META_KEY unless protocol_version . is_a? ( String )
60+ invalid_keys << CLIENT_CAPABILITIES_META_KEY unless client_capabilities . is_a? ( Hash )
61+ invalid_keys << CLIENT_INFO_META_KEY unless client_info . nil? || client_info . is_a? ( Hash )
62+
63+ unless invalid_keys . empty?
5464 raise Server ::RequestHandlerError . new (
55- "Invalid Request: modern requests require `#{ REQUIRED_META_KEYS . join ( "`, `" ) } ` in `_meta`" ,
65+ "Invalid params: missing or invalid `#{ invalid_keys . join ( "`, `" ) } ` in `_meta`" ,
5666 request ,
57- error_type : :invalid_request ,
67+ error_type : :invalid_params ,
68+ error_code : JsonRpcHandler ::ErrorCode ::INVALID_PARAMS ,
5869 )
5970 end
6071
@@ -87,9 +98,11 @@ def read(meta, key)
8798 end
8899 end
89100
101+ # `client_info` is `nil` when the client chose not to identify itself, which is legal:
102+ # it is self-reported data and MUST NOT drive behavior or security decisions anyway.
90103 attr_reader :protocol_version , :client_info , :client_capabilities , :log_level
91104
92- def initialize ( protocol_version :, client_info :, client_capabilities : , log_level : nil )
105+ def initialize ( protocol_version :, client_capabilities :, client_info : nil , log_level : nil )
93106 @protocol_version = protocol_version
94107 @client_info = client_info
95108 @client_capabilities = client_capabilities
0 commit comments