Skip to content

Commit 8c2e89a

Browse files
committed
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.
1 parent b195a21 commit 8c2e89a

3 files changed

Lines changed: 111 additions & 6 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1493,6 +1493,18 @@ server.define_tool(name: "update_resource") do |server_context:, **args|
14931493
end
14941494
```
14951495

1496+
The `resources/subscribe` and `resources/unsubscribe` responses are empty results. The one field the spec allows
1497+
alongside is `_meta`, so a handler that returns `{ _meta: { ... } }` has it passed through; any other field it
1498+
returns is dropped. To convey a subscription identifier or other advisory data to the client, nest it under `_meta`
1499+
rather than returning it at the top level, which interoperating clients reject:
1500+
1501+
```ruby
1502+
server.resources_subscribe_handler do |params|
1503+
id = subscriptions.create(params[:uri].to_s)
1504+
{ _meta: { "myapp.example/subscriptionId" => id } }
1505+
end
1506+
```
1507+
14961508
### Sampling
14971509

14981510
The Model Context Protocol allows servers to request LLM completions from clients through the `sampling/createMessage` method.

‎lib/mcp/server.rb‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -407,19 +407,25 @@ def completion_handler(&block)
407407
end
408408

409409
# Sets a custom handler for `resources/subscribe` requests.
410-
# The block receives the parsed request params. The return value is
411-
# ignored; the response is always an empty result `{}` per the MCP specification.
410+
# The block receives the parsed request params. The response is an empty result, except that
411+
# a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
412+
# so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
413+
# under `_meta`.
412414
#
413415
# @yield [params] The request params containing `:uri`.
416+
# @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
414417
def resources_subscribe_handler(&block)
415418
@handlers[Methods::RESOURCES_SUBSCRIBE] = block
416419
end
417420

418421
# Sets a custom handler for `resources/unsubscribe` requests.
419-
# The block receives the parsed request params. The return value is
420-
# ignored; the response is always an empty result `{}` per the MCP specification.
422+
# The block receives the parsed request params. The response is an empty result, except that
423+
# a `_meta` hash the block returns is passed through - the spec defines no other member for this result,
424+
# so any other field the block returns is dropped. Nest a subscription identifier or other advisory data
425+
# under `_meta`.
421426
#
422427
# @yield [params] The request params containing `:uri`.
428+
# @yieldreturn [Hash, nil] Optionally `{ _meta: { ... } }`; any other shape yields an empty result.
423429
def resources_unsubscribe_handler(&block)
424430
@handlers[Methods::RESOURCES_UNSUBSCRIBE] = block
425431
end
@@ -621,8 +627,9 @@ def handle_request(request, method, session: nil, related_request_id: nil)
621627
contents.is_a?(InputRequiredResult) ? contents : build_read_resource_result(contents)
622628
when Methods::RESOURCES_SUBSCRIBE, Methods::RESOURCES_UNSUBSCRIBE
623629
validate_resource_subscription_params!(params)
624-
dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
625-
{}
630+
handler_result = dispatch_optional_context_handler(@handlers[method], params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
631+
632+
subscription_result(handler_result)
626633
when Methods::TOOLS_CALL
627634
call_tool(params, session: session, related_request_id: related_request_id, cancellation: cancellation, envelope: envelope)
628635
when Methods::PROMPTS_GET
@@ -906,6 +913,18 @@ def validate_resource_subscription_params!(params)
906913
end
907914
end
908915

916+
# The `resources/subscribe` and `resources/unsubscribe` result is an empty object except for the optional `_meta`
917+
# every result may carry: the TypeScript SDK validates it against `EmptyResultSchema.strict()`,
918+
# which rejects any other member, so only `_meta` is passed through from the handler. A handler that returns
919+
# anything else keeps the empty `{}` result it had before, so returning a subscription identifier or
920+
# other advisory data means nesting it under `_meta`.
921+
def subscription_result(handler_result)
922+
return {} unless handler_result.is_a?(Hash)
923+
924+
meta = handler_result[:_meta] || handler_result["_meta"]
925+
meta.is_a?(Hash) ? { _meta: meta } : {}
926+
end
927+
909928
def validate_initialize_params!(params)
910929
unless params.is_a?(Hash)
911930
raise RequestHandlerError.new("Invalid params", params, error_type: :invalid_params)

‎test/mcp/server_test.rb‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3623,6 +3623,80 @@ def read_resource_request(uri)
36233623
assert_equal "Invalid params", response[:error][:message]
36243624
end
36253625

3626+
# Builds an initialized server that advertises the `resources.subscribe` capability.
3627+
def subscription_server
3628+
server = Server.new(name: "test_server", capabilities: { resources: { subscribe: true } })
3629+
server.handle({ jsonrpc: "2.0", method: "initialize", id: 1, params: initialize_params })
3630+
server.handle({ jsonrpc: "2.0", method: "notifications/initialized" })
3631+
server
3632+
end
3633+
3634+
# Sends `method` (`resources/subscribe` or `resources/unsubscribe`) and returns the JSON-RPC result.
3635+
def handle_subscription(server, method)
3636+
server.handle({
3637+
jsonrpc: "2.0",
3638+
id: 2,
3639+
method: method,
3640+
params: { uri: "https://example.com/resource" },
3641+
})[:result]
3642+
end
3643+
3644+
test "#handle resources/subscribe passes a handler-returned _meta through to the result" do
3645+
server = subscription_server
3646+
server.resources_subscribe_handler { |_params| { _meta: { "acme.example/subscriptionId" => "sub-1" } } }
3647+
3648+
result = handle_subscription(server, "resources/subscribe")
3649+
3650+
assert_equal({ _meta: { "acme.example/subscriptionId" => "sub-1" } }, result)
3651+
end
3652+
3653+
test "#handle resources/unsubscribe passes a handler-returned _meta through to the result" do
3654+
server = subscription_server
3655+
server.resources_unsubscribe_handler { |_params| { _meta: { "acme.example/note" => "gone" } } }
3656+
3657+
result = handle_subscription(server, "resources/unsubscribe")
3658+
3659+
assert_equal({ _meta: { "acme.example/note" => "gone" } }, result)
3660+
end
3661+
3662+
test "#handle resources/subscribe drops a handler-returned field that is not _meta" do
3663+
# The spec's result defines no member other than `_meta`, so a top-level field the handler adds is not
3664+
# a subscription protocol; it stays out of the response.
3665+
server = subscription_server
3666+
server.resources_subscribe_handler { |_params| { subscriptionId: "sub-1" } }
3667+
3668+
result = handle_subscription(server, "resources/subscribe")
3669+
3670+
assert_equal({}, result)
3671+
end
3672+
3673+
test "#handle resources/subscribe accepts a string _meta key from the handler" do
3674+
server = subscription_server
3675+
server.resources_subscribe_handler { |_params| { "_meta" => { "k" => "v" } } }
3676+
3677+
result = handle_subscription(server, "resources/subscribe")
3678+
3679+
assert_equal({ _meta: { "k" => "v" } }, result)
3680+
end
3681+
3682+
test "#handle resources/subscribe ignores a handler-returned _meta that is not a hash" do
3683+
server = subscription_server
3684+
server.resources_subscribe_handler { |_params| { _meta: "not-a-hash" } }
3685+
3686+
result = handle_subscription(server, "resources/subscribe")
3687+
3688+
assert_equal({}, result)
3689+
end
3690+
3691+
test "#handle resources/subscribe keeps an empty result when the handler returns a non-hash" do
3692+
server = subscription_server
3693+
server.resources_subscribe_handler { |_params| nil }
3694+
3695+
result = handle_subscription(server, "resources/subscribe")
3696+
3697+
assert_equal({}, result)
3698+
end
3699+
36263700
test "#handle resources/subscribe without uri does not invoke a custom handler" do
36273701
server = Server.new(
36283702
name: "test_server",

0 commit comments

Comments
 (0)