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:
Koichi ITO 2026-04-20 03:05:08 +09:00
commit ac7598a13d
3 changed files with 171 additions and 0 deletions

View file

@ -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

View file

@ -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.

View file

@ -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)