Support server-to-client ping per MCP specification
## Motivation and Context The MCP specification defines `ping` as a bidirectional utility: either party may issue it. https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping The previous PR added `MCP::Client#ping`. This PR adds the symmetric server-side send capability, `ServerSession#ping`. This aligns the Ruby SDK with the Python SDK (`ServerSession.send_ping`) and the TypeScript SDK (`Server.ping()`), both of which expose a server-initiated ping. In practice this enables a Ruby MCP server to health-check non-Ruby clients (e.g., Claude Desktop, the Python or TypeScript SDK client) during long-running tool operations. Scope is intentionally server-only: this PR does not add client-side inbound request dispatch, which is a larger refactor outside the ping utility. A Ruby `MCP::Client` therefore still cannot receive a server-initiated ping; that gap is tracked as a separate follow-up. ## How Has This Been Tested? New file `test/mcp/server_session_ping_test.rb` covers: - success (empty `result` returned) - `related_request_id` propagated through the transport when a session ID is set - `ValidationError` when the transport returns `nil` - `ValidationError` when the transport returns a non-Hash `result` - transport-level errors propagate unchanged - ping succeeds without any client capability declaration (per spec, ping has no capability gate) `test/mcp/server_context_test.rb` adds two tests for `ServerContext#ping` delegation (happy path and `NoMethodError` when the session lacks `#ping`). The existing server-side `ping` handler tests continue to pass unchanged. ## Breaking Changes None. `MCP::ServerContext#ping` and `MCP::Server::ValidationError` are purely additive.
This commit is contained in:
parent
d17cc51c20
commit
ac7598a13d
3 changed files with 171 additions and 0 deletions
|
|
@ -67,6 +67,11 @@ module MCP
|
|||
end
|
||||
end
|
||||
|
||||
# Raised when a client response fails server-side validation, e.g., a success response
|
||||
# whose `result` field is missing or has the wrong type. This is distinct from a
|
||||
# client-returned JSON-RPC error.
|
||||
class ValidationError < StandardError; end
|
||||
|
||||
include Instrumentation
|
||||
include Pagination
|
||||
|
||||
|
|
|
|||
|
|
@ -59,6 +59,28 @@ module MCP
|
|||
end
|
||||
end
|
||||
|
||||
# Sends a `ping` request to the originating client to verify it is still responsive.
|
||||
# Per the MCP spec, the client MUST respond promptly with an empty result.
|
||||
#
|
||||
# @return [Hash] An empty hash on success.
|
||||
# @raise [Server::ValidationError] If the response `result` is not a Hash.
|
||||
# @raise [NoMethodError] If the session does not support sending pings.
|
||||
#
|
||||
# @example
|
||||
# def self.call(server_context:)
|
||||
# server_context.ping # => {}
|
||||
# # ...
|
||||
# end
|
||||
#
|
||||
# @see https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping
|
||||
def ping
|
||||
if @notification_target.respond_to?(:ping)
|
||||
@notification_target.ping(related_request_id: @related_request_id)
|
||||
else
|
||||
raise NoMethodError, "undefined method 'ping' for #{self}"
|
||||
end
|
||||
end
|
||||
|
||||
# Delegates to the session so the request is scoped to the originating client.
|
||||
# Falls back to `@context` (via `method_missing`) when `@notification_target`
|
||||
# does not support sampling.
|
||||
|
|
|
|||
|
|
@ -106,6 +106,14 @@ module MCP
|
|||
send_to_transport_request(Methods::ROOTS_LIST, nil, related_request_id: related_request_id)
|
||||
end
|
||||
|
||||
# Sends a `ping` request scoped to this session.
|
||||
def ping(related_request_id: nil)
|
||||
result = send_to_transport_request(Methods::PING, nil, related_request_id: related_request_id)
|
||||
raise Server::ValidationError, "Response validation failed: invalid `result`" unless result.is_a?(Hash)
|
||||
|
||||
result
|
||||
end
|
||||
|
||||
# Sends a `sampling/createMessage` request scoped to this session.
|
||||
def create_sampling_message(related_request_id: nil, **kwargs)
|
||||
params = @server.build_sampling_params(client_capabilities, **kwargs)
|
||||
|
|
|
|||
Loading…
Reference in a new issue