Support ping client API per MCP specification
## Motivation and Context The MCP specification defines the `ping` utility for verifying that the peer of a connection is still responsive. The Ruby SDK server side already replies to incoming `ping` requests with an empty result, but `MCP::Client` had no public API to send a `ping` request. Users had to build the JSON-RPC payload themselves and call the transport directly. This adds a client-side counterpart to the existing server handler and aligns the Ruby SDK in spirit with the Python and TypeScript SDKs, which expose `ClientSession.send_ping` and `Client.ping` respectively. Those SDKs validate the response envelope via type schemas (`EmptyResult` / `EmptyResultSchema`) and raise their validation library's generic exception (Pydantic's `ValidationError` / Zod's `ZodError`). The Ruby client applies a Hash type check on `result` (matching Python's behavior of requiring a dict while allowing arbitrary contents) and raises a new `MCP::Client::ValidationError` for malformed responses, keeping `MCP::Client::ServerError` reserved for JSON-RPC error responses. ## How Has This Been Tested? Client tests cover: - request structure (method is `ping`, no `params`) - empty result on success - `ServerError` on JSON-RPC error response - `ValidationError` on a response missing `result` - `ValidationError` on a `result` of the wrong type (e.g., String) - propagation of transport-level errors raised by `transport.send_request` The existing server-side `ping` handler tests continue to pass unchanged. ## Breaking Changes None. `MCP::Client#ping` and `MCP::Client::ValidationError` are purely additive. The server-side `ping` handler behavior is unchanged.
This commit is contained in:
parent
2edba778f0
commit
493321ca46
1 changed files with 112 additions and 0 deletions
28
README.md
28
README.md
|
|
@ -1099,6 +1099,33 @@ Notifications follow the JSON-RPC 2.0 specification and use these method names:
|
|||
- `notifications/progress`
|
||||
- `notifications/message`
|
||||
|
||||
### Ping
|
||||
|
||||
The MCP Ruby SDK supports the
|
||||
[MCP `ping` utility](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping),
|
||||
which allows either side of the connection to verify that the peer is still responsive.
|
||||
A `ping` request has no parameters, and the receiver MUST respond promptly with an empty result.
|
||||
|
||||
#### Server-Side
|
||||
|
||||
Servers respond to incoming `ping` requests automatically - no setup is required.
|
||||
Any `MCP::Server` instance replies with an empty result.
|
||||
|
||||
#### Client-Side
|
||||
|
||||
`MCP::Client` exposes `ping` to send a ping to the server:
|
||||
|
||||
```ruby
|
||||
client = MCP::Client.new(transport: transport)
|
||||
client.ping # => {} on success
|
||||
```
|
||||
|
||||
`#ping` raises `MCP::Client::ServerError` when the server returns a JSON-RPC error.
|
||||
It raises `MCP::Client::ValidationError` when the response `result` is missing or
|
||||
is not a Hash (matching the spec requirement that `result` be an object).
|
||||
Transport-level errors (for example, `MCP::Client::Stdio`'s `read_timeout:` firing)
|
||||
propagate as exceptions raised by the transport layer.
|
||||
|
||||
### Progress
|
||||
|
||||
The MCP Ruby SDK supports progress tracking for long-running tool operations,
|
||||
|
|
@ -1549,6 +1576,7 @@ The `MCP::Client` class provides an interface for interacting with MCP servers.
|
|||
|
||||
This class supports:
|
||||
|
||||
- Liveness check via the `ping` method (`MCP::Client#ping`)
|
||||
- Tool listing via the `tools/list` method (`MCP::Client#tools`)
|
||||
- Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)
|
||||
- Resource listing via the `resources/list` method (`MCP::Client#resources`)
|
||||
|
|
|
|||
Loading…
Reference in a new issue