Skip to content

Support ping client API per MCP specification#324

Merged
koic merged 1 commit intomodelcontextprotocol:mainfrom
koic:ping_client_to_server
Apr 20, 2026
Merged

Support ping client API per MCP specification#324
koic merged 1 commit intomodelcontextprotocol:mainfrom
koic:ping_client_to_server

Conversation

@koic
Copy link
Copy Markdown
Member

@koic koic commented Apr 20, 2026

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.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

## 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.
@koic koic merged commit baa093d into modelcontextprotocol:main Apr 20, 2026
11 checks passed
@koic koic deleted the ping_client_to_server branch April 20, 2026 03:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants