Pass a handler-returned _meta through the subscribe result

## Motivation and Context

`resources/subscribe` and `resources/unsubscribe` answered with a hardcoded `{}`, discarding whatever
the registered handler returned. A server had no way to attach anything to the response - not even `_meta`,
which the specification allows on every result. The handler docstring justified the discard as "always
an empty result `{}` per the MCP specification", but the spec does not require an empty object here:
the subscribe result is an `EmptyResult`, and every result may carry `_meta`.

The one field that is interoperable is `_meta`. The TypeScript SDK validates the subscribe result against
`EmptyResultSchema.strict()`, which rejects any member other than `_meta`, so a top-level field like
a bespoke `subscriptionId` would be refused by a TypeScript client. The Python SDK passes the handler's `EmptyResult`
return through, `_meta` included. Passing `_meta` matches both while staying within what the spec defines.

The subscribe and unsubscribe handlers now pass a returned `_meta` hash through to the result and drop anything else.
`subscription_result` reads `_meta` under a symbol or string key and includes it only when it is itself
a hash; every other return shape - a non-hash, or a hash without a usable `_meta` - keeps the empty `{}` result it
produced before. Advisory data such as a subscription identifier goes under `_meta`, namespaced, rather than
at the top level. This affects only 2025-11-25 and earlier connections, since `resources/subscribe`
and `resources/unsubscribe` are removed from the modern lifecycle.

Fixes #508.

## How Has This Been Tested?

New tests in `test/mcp/server_test.rb` cover a `_meta` hash passing through on both `resources/subscribe`
and `resources/unsubscribe`, a non-`_meta` field being dropped, a string `_meta` key working, a non-hash `_meta`
being ignored, and a non-hash return keeping the empty result. The existing subscribe and unsubscribe tests,
which return `{}` and assert an empty result, are unchanged.

## Breaking Changes

None. A handler that does not return a hash carrying a `_meta` hash - which is every handler written against
the previous "return value is ignored" contract - still produces the empty `{}` result.
This commit is contained in:
Koichi ITO 2026-08-13 00:47:39 +09:00
commit 8c2e89afd5

View file

@ -407,19 +407,25 @@ module MCP
end
# Sets a custom handler for `resources/subscribe` requests.
# The block receives the parsed request params. The return value is
# ignored; the response is always an empty result `{}` per the MCP specification.
# The block receives the parsed request params. The response is an empty result, except that
# a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
# so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
# under `_meta`.
#
# @yield [params] The request params containing `:uri`.
# @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
def resources_subscribe_handler(&block)
@handlers[Methods::RESOURCES_SUBSCRIBE] = block
end
# Sets a custom handler for `resources/unsubscribe` requests.
# The block receives the parsed request params. The return value is
# ignored; the response is always an empty result `{}` per the MCP specification.
# The block receives the parsed request params. The response is an empty result, except that
# a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
# so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
# under `_meta`.
#
# @yield [params] The request params containing `:uri`.
# @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
def resources_unsubscribe_handler(&block)
@handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
end
@ -621,8 +627,9 @@ module MCP
contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
validate_resource_subscription_params!(params)
dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
{}
handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
subscription_result(handler_result)
when Methods::TOOLS_CALL
call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
when Methods::PROMPTS_GET
@ -906,6 +913,18 @@ module MCP
end
end
# The `resources/subscribe` and `resources/unsubscribe` result is an empty object except for the optional `_meta`
# every result may carry: the TypeScript SDK validates it against `EmptyResultSchema.strict()`,
# which rejects any other member, so only `_meta` is passed through from the handler. A handler that returns
# anything else keeps the empty `{}` result it had before, so returning a subscription identifier or
# other advisory data means nesting it under `_meta`.
def subscription_result(handler_result)
return {} unless handler_result.is_a?(Hash)
meta = handler_result[:_meta] || handler_result["_meta"]
meta.is_a?(Hash) ? { _meta: meta } : {}
end
def validate_initialize_params!(params)
unless params.is_a?(Hash)
raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)