ruby-sdk/lib/mcp
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Koichi ITO da5f9225ac Support sampling/createMessage per MCP specification
## Motivation and Context

The MCP specification defines `sampling/createMessage` to request LLM completions from the client.
The Ruby SDK did not yet support server-to-client requests,
so the server had no way to ask the client to sample an LLM.
This caused the `tools-call-sampling` conformance test to fail.

This adds `Server#create_sampling_message` to send a `sampling/createMessage` request
to the client via the transport layer. The method validates that the client declared
the `sampling` capability during initialization, and optionally checks the
`sampling.tools` capability when tools or tool_choice parameters are provided.

On the transport side, `Transport#send_request` is introduced as an abstract method,
with implementations in both `StdioTransport` and `StreamableHTTPTransport`.
Each transport assigns a unique request ID, sends the JSON-RPC request to the client,
and blocks until the client responds.

Client capabilities are stored per session via `ServerSession`, so validation is scoped
to the originating client. `ServerSession#create_sampling_message` uses
`build_sampling_params` for capability validation and sends the request directly through
the transport with the session ID, following the same pattern as `notify_progress`.

`Server#create_sampling_message` is the public API for single-client transports
(e.g., StdioTransport).

For multi-client transports (e.g., StreamableHTTPTransport),
`ServerSession#create_sampling_message` must be used to route requests to the correct client.
Tools using `server_context.create_sampling_message` automatically route to the correct session
regardless of transport.

`StreamableHTTPTransport#send_request` requires `session_id` to prevent broadcasting sampling requests
to all connected clients. Missing or invalid session IDs raise explicit errors instead of silently failing.

The `include_context` parameter is soft-deprecated in the MCP specification but is included
for compatibility with existing clients that declare the `sampling.context` capability.
Python and TypeScript SDKs also retain this parameter.

Ref: https://modelcontextprotocol.io/specification/latest/server/utilities/sampling

## How Has This Been Tested?

Added comprehensive tests in `test/mcp/server_sampling_test.rb` covering required and optional parameters,
capability validation, error handling, nil-param omission, per-session capability isolation,
and HTTP init capability scoping.

Added transport tests in `test/mcp/server/transports/stdio_transport_test.rb` and
`test/mcp/server/transports/streamable_http_transport_test.rb` for `send_request` round-trip behavior,
error responses, stateless mode rejection, missing session_id, invalid session_id, and no-active-stream error.

Conformance: `tools-call-sampling` is removed from expected failures. The conformance server's `TestSampling`
tool now calls `server_context.create_sampling_message` instead of returning a stub error.

This aligns the Ruby SDK with the MCP specification and other SDK implementations.

## Breaking Changes

None for end users.
`Transport#send_request` is a new abstract method. `ServerSession#create_sampling_message` is a new method.
2026-04-04 05:55:27 +09:00
..
client Add MCP::Client::Stdio transport 2026-03-19 12:41:27 +09:00
prompt Support Ruby 2.7 - Ruby 3.1 2026-01-06 10:38:56 +09:00
resource Fix Resource::Contents#to_h to use correct property names per MCP spec 2026-02-19 13:50:10 +09:00
server Support sampling/createMessage per MCP specification 2026-04-04 05:55:27 +09:00
tool Use symbolize_names: true in JSON.parse calls 2026-03-31 04:15:42 +09:00
transports Add a migration path for Server::Transports::StdioTransport 2025-06-10 16:27:22 +09:00
annotations.rb Extract MCP::Annotations into a dedicated file 2026-02-03 15:38:04 +09:00
client.rb Support completion/complete per MCP specification 2026-04-03 01:35:07 +09:00
configuration.rb Support Ruby 2.7 - Ruby 3.1 2026-01-06 10:38:56 +09:00
content.rb Add Content::EmbeddedResource class for embedded resource content type 2026-03-02 01:33:05 +09:00
icon.rb Support icons parameter 2025-12-30 05:35:22 +09:00
instrumentation.rb Support Ruby 2.7 - Ruby 3.1 2026-01-06 10:38:56 +09:00
logging_message_notification.rb logging_message_notification: Remove unused require 2026-02-05 16:05:08 -05:00
methods.rb Add Elicitation skeleton 2025-11-21 02:42:20 +09:00
progress.rb Remove Server#notify_progress broadcast API 2026-03-29 15:11:28 +09:00
prompt.rb Use autoload to defer loading of unused subsystems 2026-03-12 14:08:27 +09:00
resource.rb Use autoload to defer loading of unused subsystems 2026-03-12 14:08:27 +09:00
resource_template.rb Omit icons from responses when empty or nil 2026-01-12 09:46:45 +09:00
server.rb Support sampling/createMessage per MCP specification 2026-04-04 05:55:27 +09:00
server_context.rb Support sampling/createMessage per MCP specification 2026-04-04 05:55:27 +09:00
server_session.rb Support sampling/createMessage per MCP specification 2026-04-04 05:55:27 +09:00
string_utils.rb Fix ReDoS vulnerability in StringUtils#underscore 2026-01-09 01:14:52 +09:00
tool.rb Use autoload to defer loading of unused subsystems 2026-03-12 14:08:27 +09:00
transport.rb Support sampling/createMessage per MCP specification 2026-04-04 05:55:27 +09:00
version.rb Release 0.10.0 2026-03-30 06:13:16 +09:00